Orcha
How to use durable sessions

List sessions

List OrchaJS durable sessions with .list() and filter by status or metadata.

Use .list() to show sessions created by one registered agent:

const sessions = await orcha.supportAgent.list({
  page: 1,
  pageSize: 25,
});

for (const session of sessions.items) {
  console.log(session.name, session.status);
}

Filter sessions

Find paused sessions:

const paused = await orcha.supportAgent.list({
  status: "paused",
});

Find sessions attached to one application record:

const customerSessions = await orcha.supportAgent.list({
  metadata: {
    customerId: "cus_123",
  },
});

Filters can be combined:

const work = await orcha.supportAgent.list({
  status: "active",
  metadata: {
    customerId: "cus_123",
    priority: "high",
  },
});

Example response

{
  items: [
    {
      sessionId: "ses_01K...",
      agent: "supportAgent",
      name: "Order ord_1001",
      status: "active",
      metadata: { customerId: "cus_123" },
      createdAt: "2026-09-28T12:00:00Z",
      updatedAt: "2026-09-28T12:04:00Z",
      runStatus: "completed",
      pendingClientActions: [],
      lastOutput: "Your order has shipped.",
      usage: {
        inputTokens: 320,
        outputTokens: 42,
        reasoningTokens: null,
        cacheReadTokens: 0,
        cacheWriteTokens: 0,
      },
    },
  ],
  page: 1,         // Current page.
  pageSize: 25,    // Maximum items on this page.
  total: 1,        // Sessions matching the filters.
  hasMore: false,  // Whether another page exists.
}

API reference

list(options?: {
  page?: number;
  pageSize?: number;
  status?: "active" | "paused" | "completed";
  metadata?: Record<string, string | number | boolean | null>;
}): Promise<SessionList>

type SessionList = {
  items: SessionSnapshot[];
  page: number;
  pageSize: number;
  total: number;
  hasMore: boolean;
};
  • page defaults to 1.
  • pageSize defaults to 50 and accepts 1 through 100.
  • status matches the durable session status, not runStatus.
  • metadata matches sessions containing the supplied key-value pairs.
  • items contains complete SessionSnapshot objects.
  • total is the total number matching the filters, not just this page.
  • hasMore indicates whether the next page exists.

.list() is scoped to the registered agent it is called on. orcha.supportAgent.list() does not return sessions owned by another top-level agent.