Graphorin API reference v0.12.1

---

Graphorin API reference / @graphorin/sessions / facade / Session

Interface: Session

Defined in: packages/sessions/src/facade.ts:182

Per-session ergonomic facade returned by SessionManager.create / SessionManager.get.

Stable

Properties

Property	Modifier	Type	Description	Defined in
commentaryPolicy	readonly	CommentaryPolicy	Effective commentary policy for this session.	packages/sessions/src/facade.ts:186
id	readonly	string	-	packages/sessions/src/facade.ts:183
scope	readonly	SessionScope	-	packages/sessions/src/facade.ts:184

Methods

appendHandoff()

appendHandoff(record): Promise<HandoffRecord>;

Defined in: packages/sessions/src/facade.ts:213

Append a handoff record. RP-2: this does not auto-fire from Agent.toTool() - the agent accumulates HandoffRecords in its own RunState; the operator forwards them here (see examples/multi-agent-crew).

Parameters

Parameter	Type
record	Omit<HandoffRecord, "at"> & { at?: string; }

Returns

Promise<HandoffRecord>

---

attachWorkflowRun()

attachWorkflowRun(run): Promise<SessionWorkflowRun>;

Defined in: packages/sessions/src/facade.ts:222

Attach a workflow run to this session.

Parameters

Parameter	Type
run	Omit<SessionWorkflowRun, "sessionId" | "attachedAt"> & { attachedAt?: string; }

Returns

Promise<SessionWorkflowRun>

---

audit()

audit(opts?): Promise<readonly SessionAuditEntry[]>;

Defined in: packages/sessions/src/facade.ts:267

Recent audit rows for this session, newest-first.

Parameters

Parameter	Type
opts?	{ limit?: number; }
opts.limit?	number

Returns

Promise<readonly SessionAuditEntry[]>

---

close()

close(): Promise<void>;

Defined in: packages/sessions/src/facade.ts:236

Mark the session closed. Idempotent.

Returns

Promise<void>

---

compact()

compact(opts?): Promise<{
  removed: number;
  summarized: number;
  summary?: string;
}>;

Defined in: packages/sessions/src/facade.ts:203

Manual compaction - wraps memory.session.compact(...).

Parameters

Parameter	Type
opts?	{ keepLastN?: number; }
opts.keepLastN?	number

Returns

Promise<{ removed: number; summarized: number; summary?: string; }>

---

export()

export(opts): Promise<SessionExportFooterRecord>;

Defined in: packages/sessions/src/facade.ts:250

Stream the session as a JSONL session-export 1.0 document.

Parameters

Parameter	Type
opts	SessionExportOptions

Returns

Promise&lt;SessionExportFooterRecord&gt;

---

fork()

fork(opts?): Promise<Session>;

Defined in: packages/sessions/src/facade.ts:248

Fork the session at a given point. Returns a fresh Session with copied session-level metadata; the new session id is autogenerated.

Note: forking copies SESSION-level metadata only. Replicating message rows is a downstream consumer concern - the agent runtime iterates the source's list({ sinceMessageId }) and writes via push() on the new session as needed. Full message-replicating forks remain post-v0.1.

Parameters

Parameter	Type
opts?	{ title?: string; }
opts.title?	string

Returns

Promise&lt;Session&gt;

---

handoffsByAgent()

handoffsByAgent(agentId, direction?): Promise<readonly HandoffRecord[]>;

Defined in: packages/sessions/src/facade.ts:217

Filter handoffs by agent + direction.

Parameters

Parameter	Type
agentId	string
direction?	"from" | "to" | "both"

Returns

Promise&lt;readonly HandoffRecord[]&gt;

---

list()

list(opts?): Promise<readonly Message[]>;

Defined in: packages/sessions/src/facade.ts:196

List messages - wraps memory.session.list(scope, ...).

Parameters

Parameter	Type
opts?	SessionListOptions

Returns

Promise&lt;readonly Message[]&gt;

---

listHandoffs()

listHandoffs(): Promise<readonly HandoffRecord[]>;

Defined in: packages/sessions/src/facade.ts:215

Every handoff in this session, oldest-first.

Returns

Promise&lt;readonly HandoffRecord[]&gt;

---

metadata()

metadata(): Promise<SessionMetadata>;

Defined in: packages/sessions/src/facade.ts:187

Returns

Promise&lt;SessionMetadata&gt;

---

push()

push(message, options?): Promise<MessageRef>;

Defined in: packages/sessions/src/facade.ts:194

Persist a new message - wraps memory.session.push(scope, ...). B3: options.verdict threads the run loop's per-turn security verdict (AgentResult.verdicts) onto the stored row so the memory ingest gate can act on it.

Parameters

Parameter	Type
message	Message
options?	SessionMessagePushOptions

Returns

Promise&lt;MessageRef&gt;

---

recordToolCassette()

recordToolCassette(opts): ToolCassetteRecorder;

Defined in: packages/sessions/src/facade.ts:265

Begin recording a tool cassette. RP-2: the recorder is not wired into the agent runtime automatically - the operator subscribes to the agent's RunContext events and forwards tool.execute.end / .error into recorder.recordToolCall(...). See examples/multi-agent-crew for the canonical wiring.

Parameters

Parameter	Type
opts	SessionRecordCassetteOptions

Returns

ToolCassetteRecorder

---

replay()

replay(opts?): AsyncIterable<SessionReplayEvent>;

Defined in: packages/sessions/src/facade.ts:252

Sanitized-by-default replay.

Parameters

Parameter	Type
opts?	SessionReplayOptions & { liveInvocation?: (record) => Promise&lt;{ args: unknown; idempotencyKey?: string; validateRecordedOutput?: (output) => string | null; }>; traceSource?: | AsyncIterable<SpanRecord&lt;SpanType&gt;, any, any> | Iterable<SpanRecord&lt;SpanType&gt;, any, any>; }

Returns

AsyncIterable&lt;SessionReplayEvent&gt;

---

search()

search(query, opts?): Promise<readonly MemoryHit<MemoryRecord>[]>;

Defined in: packages/sessions/src/facade.ts:198

Hybrid (FTS5) search over messages - wraps memory.session.search(...).

Parameters

Parameter	Type
query	string
opts?	{ signal?: AbortSignal; topK?: number; }
opts.signal?	AbortSignal
opts.topK?	number

Returns

Promise<readonly MemoryHit&lt;MemoryRecord&gt;[]>

---

updateWorkflowRunStatus()

updateWorkflowRunStatus(
   workflowId, 
   threadId, 
status): Promise<void>;

Defined in: packages/sessions/src/facade.ts:230

Update a workflow run's status.

Parameters

Parameter	Type
workflowId	string
threadId	string
status	"completed" | "failed" | "running" | "suspended"

Returns

Promise&lt;void&gt;

---

workflowRuns()

workflowRuns(): Promise<readonly SessionWorkflowRun[]>;

Defined in: packages/sessions/src/facade.ts:228

List workflow runs attached to this session.

Returns

Promise&lt;readonly SessionWorkflowRun[]&gt;