OrchaHow to use durable sessions
Read conversation history
Render OrchaJS conversation history with .history() for messages, actions, and skills.
Use .history() to render a conversation in your application:
const history = await orcha.supportAgent.history(sessionId, {
page: 1,
pageSize: 25,
});
for (const item of history.items) {
if (item.type === "message") {
console.log(item.role, item.content);
}
if (item.type === "client_action") {
console.log(item.name, item.callId, item.status);
}
}history() removes low-level provider bookkeeping. Its items represent
messages and useful agent activity such as actions, skills, subagents, and
evaluations.
Example response
{
items: [
{
id: "message:3", // Stable item ID.
type: "message", // How to interpret this item.
createdAt: "2026-09-28T12:00:04Z", // ISO timestamp.
role: "user", // "user" or "assistant".
content: [
{ type: "text", text: "Where is my order?" },
],
},
{
id: "client-action:call_123",
type: "client_action",
createdAt: "2026-09-28T12:00:09Z",
name: "request_human_approval",
callId: "call_123",
status: "waiting",
arguments: { amount: 750, currency: "USD" },
summary: "request human approval is waiting for the client.",
},
],
page: 1, // Current page.
pageSize: 25, // Maximum items on this page.
total: 2, // Total projected history items.
hasMore: false, // Whether an older page exists.
// The current SessionSnapshot is also included here.
sessionId: "ses_01K...",
agent: "supportAgent",
status: "active",
metadata: {},
createdAt: "2026-09-28T12:00:00Z",
updatedAt: "2026-09-28T12:00:09Z",
runStatus: "waiting_for_client_action",
pendingClientActions: [
{
callId: "call_123",
name: "request_human_approval",
arguments: { amount: 750, currency: "USD" },
},
],
}Pagination
Page 1 contains the newest page. Higher page numbers move backward through the session:
const older = await orcha.supportAgent.history(sessionId, {
page: 2,
pageSize: 50,
});Use events() when you need the canonical event log
instead of a user-facing history.
API reference
history(
sessionId: string,
options?: {
page?: number;
pageSize?: number;
},
): Promise<SessionHistory>
type SessionHistory = SessionSnapshot & {
items: SessionHistoryItem[];
page: number;
pageSize: number;
total: number;
hasMore: boolean;
};pagedefaults to1.pageSizedefaults to50and accepts1through100.- Pages are newest-first: page 2 is older than page 1.
- Snapshot fields describe the session at the time of the request.
History item
type SessionHistoryItem = {
id: string;
type:
| "message"
| "action"
| "client_action"
| "subagent"
| "skill"
| "evaluation"
| "session_completed";
createdAt: string;
role?: "user" | "assistant";
content?: MessageContent[];
name?: string;
status?: "running" | "waiting" | "paused" | "completed" | "failed";
summary?: string;
callId?: string;
childSessionId?: string;
arguments?: Record<string, unknown>;
durationMs?: number;
usage?: Usage;
metrics?: EvaluationMetric[];
};All items contain id, type, and createdAt. Other fields depend on
type:
message—role,content, and assistantusagewhen available.action—name,callId,status,arguments,durationMs, andsummaryas available.client_action—name,callId,status, pendingarguments, andsummary.subagent—name,childSessionId,callId,status,usage, andsummary.skill—name,status, andsummary.evaluation—name,status,metrics,durationMs, andsummary.session_completed— completionstatusandsummary.
Message content
type MessageContent =
| { type: "text"; text: string }
| {
type: "image" | "video" | "audio" | "url";
mimeType: string;
fileUri: string;
}
| {
type: "file";
filePath: string;
mimeType: string;
};