Sessions

A Session is nvoken's durable conversation record. Most applications let the first Invocation create it, then store the returned session_id beside their own thread or ticket.

Create or resolve a Session

Pass a host-owned key when admitting the first turn:

{
  "agent_key": "support",
  "tenant_key": "acme",
  "user_key": "user-481",
  "session_key": "ticket-7391",
  "idempotency_key": "ticket-7391:message-1",
  "input": "Where is my order?",
  "spec": { "model": { "provider": "anthropic", "id": "claude-sonnet-5" } }
}

session_key is resolved within the effective tenant partition and Agent. It does not have to be globally unique.

You can also call POST /v1/sessions before the first turn. That is useful when a product needs a durable thread ID before it has a message. An unbound Session gets its Agent from the first admitted Invocation.

Keep product labels in metadata

Session metadata is opaque host data such as a ticket ID, board key, or display title. nvoken returns it but never interprets it.

Set metadata at creation through session_options.metadata. Later, use PATCH /v1/sessions/{session_id} with a merge patch: a string sets a key, null removes it, and omitted keys stay unchanged.

Do not put authorization decisions in metadata. tenant_key and the caller's credential establish isolation; metadata and user_key are filters only.

Serialize turns

A Session may have one queued, running, or waiting Invocation. The next turn is rejected by default until that Invocation settles.

An SDK's bound Session also serializes calls inside one process:

const chat = agent.session({ sessionKey: "ticket-7391", tenantKey: "acme" });
 
await chat.text("My order number is 1842.");
console.log(await chat.text("What was my order number?"));

The service rule remains authoritative across processes. Local serialization only avoids a predictable conflict in one client.

Compact provider context

Compaction is optional and must be chosen when the first Invocation creates the Session, because its policy is checked against that model:

await agent.invoke("Start a long research thread.", {
  sessionKey: "research-42",
  sessionOptions: {
    compaction: { triggerTokens: "auto" },
  },
});

auto resolves to a token threshold based on the model's context window. You can provide an exact threshold and an optional summary model from the same provider.

Compaction changes only what nvoken sends to the provider. It does not edit or remove canonical messages. The resolved policy is visible on the Session, and summary usage is included in Session usage.

Set an idle retention window

Creation may include:

{
  "session_options": {
    "retention": { "ttl_seconds": 86400 }
  }
}

The allowed window is one hour to thirty days. It measures idle time, so every admission and settlement moves expires_at forward. Automatic expiry skips a Session with active work.

Omit retention for a conversation the user expects to find again. A short window fits scratch work or a one-shot structured task.

Read messages or drain changes

Use GET /v1/sessions/{id}/messages for ordinary paged transcript reads.

Use GET /v1/sessions/{id}/transcript when a worker needs a fixed-cut, incremental drain. Continue with next_page_token until has_more is false, then store resume_cursor for the next drain. New writes do not extend an old page traversal forever.

The Session stream exposes the same transcript projection over SSE. See Streaming & recovery.

Delete with care

DELETE /v1/sessions/{session_id} immediately erases the Session and its whole subtree. That includes Invocations, messages, ToolCalls, checkpoints, compactions, provider artifacts, and undelivered notifications.

The operation is not a complete tenant or account deletion by itself. Stop new admission in the host, list every matching Session, and delete until the list is empty. Usage reports shrink when the underlying Invocation evidence is removed, so keep a separate billing ledger if usage affects invoices.

There is no Session fork endpoint. A branch is a new Session whose starting context is chosen by the host.