Graphorin API reference v0.1.0

---

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

Interface: Session

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

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:146
id	readonly	string	-	packages/sessions/src/facade.ts:143
scope	readonly	SessionScope	-	packages/sessions/src/facade.ts:144

Methods

appendHandoff()

appendHandoff(record): Promise<HandoffRecord>;

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

Append a handoff record. Auto-fires from Agent.toTool() in @graphorin/agent.

Parameters

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

Returns

Promise<HandoffRecord>

---

attachWorkflowRun()

attachWorkflowRun(run): Promise<SessionWorkflowRun>;

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

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:216

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:187

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:158

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:201

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:199

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:168

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:151

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:166

Every handoff in this session, oldest-first.

Returns

Promise&lt;readonly HandoffRecord[]&gt;

---

metadata()

metadata(): Promise<SessionMetadata>;

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

Returns

Promise&lt;SessionMetadata&gt;

---

push()

push(message): Promise<MessageRef>;

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

Persist a new message — wraps memory.session.push(scope, ...).

Parameters

Parameter	Type
message	Message

Returns

Promise&lt;MessageRef&gt;

---

recordToolCassette()

recordToolCassette(opts): ToolCassetteRecorder;

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

Begin recording a tool cassette. The recorder is wired into the agent runtime (@graphorin/agent) so each tool.execute.end / .error event flows through.

Parameters

Parameter	Type
opts	SessionRecordCassetteOptions

Returns

ToolCassetteRecorder

---

replay()

replay(opts?): AsyncIterable<SessionReplayEvent>;

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

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:153

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:181

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:179

List workflow runs attached to this session.

Returns

Promise&lt;readonly SessionWorkflowRun[]&gt;