OrchaHow to use durable sessions
Read a session
Read an OrchaJS session snapshot with .get() for status, output, and pending client actions.
Use .get() to read the latest session state without starting another run:
const session = await orcha.supportAgent.get(sessionId);
console.log(session.status);
console.log(session.lastOutput);This is useful when restoring a page after a refresh, checking background work, or finding a pending client action.
Example snapshot
{
sessionId: "ses_01K...", // The durable session ID.
agent: "supportAgent", // Registered agent key.
name: "Order ord_1001", // Optional display name.
status: "active", // Overall session state.
metadata: { customerId: "cus_123" }, // Application data you attached.
createdAt: "2026-09-28T12:00:00Z", // ISO creation time.
updatedAt: "2026-09-28T12:01:12Z", // ISO time of the latest event.
runStatus: "completed", // State of the latest run.
pendingClientActions: [], // Client actions still waiting.
lastOutput: "Your order has shipped.", // Latest assistant output.
usage: { // Latest run token usage.
inputTokens: 320,
outputTokens: 42,
reasoningTokens: null,
cacheReadTokens: 0,
cacheWriteTokens: 0,
},
}Restore a pending action
const session = await orcha.supportAgent.get(sessionId);
if (session.runStatus === "waiting_for_client_action") {
const call = session.pendingClientActions[0];
console.log(call.name, call.arguments);
}Resolve it with resume().
API reference
get(sessionId: string): Promise<SessionSnapshot>
type SessionSnapshot = {
sessionId: string;
agent: string;
name?: string;
status: "active" | "paused" | "completed";
metadata: Record<string, string | number | boolean | null>;
createdAt: string;
updatedAt: string;
runStatus?:
| "running"
| "waiting_for_subagent"
| "waiting_for_client_action"
| "paused"
| "completed"
| "failed";
pendingClientActions: ClientToolCall[];
lineage?: {
origin: "delegated";
parentAgent: string;
parentSessionId: string;
parentCallId: string;
};
lastOutput?: AgentOutput;
usage?: Usage;
};
type ClientToolCall = {
callId: string;
name: string;
arguments: Record<string, unknown>;
};
type Usage = {
inputTokens: number;
outputTokens: number;
reasoningTokens: number | null;
cacheReadTokens: number;
cacheWriteTokens: number;
};Status fields
status describes the durable session:
active— available, waiting for a client action, or currently running.paused— explicitly paused with.pause().completed— its lifecycle is complete.
runStatus describes only the latest run:
running— the model is working.waiting_for_subagent— a child agent is working.waiting_for_client_action— your client must return tool results.paused— work was explicitly paused.completed— the latest run finished normally.failed— the latest run failed.
Optional fields
lineageexists on delegated subagent sessions and points back to the parent.lastOutputis text for text agents or parsed data for JSON agents.usagecan be absent before the session has recorded model usage.runStatuscan be absent before the first run starts.
.get() throws session_not_found when the ID does not belong to this
registered agent.