Skip to content

Agent sessions

A session is one agent's conversation, keyed by (tenant, parent, agent, label). The parent is a place URI or another session ID. Reopening a key continues its journal. A label isolates an independent pass; Fresh generates a new label.

flow/session names the conversation (session.Store: Open, children, links, run indexes, grants, reservations), flow/thread keeps its journal, and flow/runtime runs its turns. A host opens or continues a session through the store and accepts a run on it with the runtime.

Hosts authenticate and authorize before accepting a run. AcceptOwnSession preserves a host's already unique per-agent event ID. Its child variant records the durable parent and question for terminal-result notification.

Agent tools and governance

runtime.WithSessionRuntime installs session_call, session_listen, session_read, session_status and session_link in the sandbox. Calls use the parent's pinned Access.Spawn. The pinned policy's session_depth defaults to 3 and open_children to 8. Admission atomically reserves a slot per parent across replicas. Retrying a call reuses its reservation; only failed admission or a terminal ledger result releases it.

runtime.WithSessionTools limits those verbs to the ones a host names. A verb left out is not offered to a turn and does not resolve for a spec that names it. With no names, a turn is offered none: a host that calls agents through its own tool (runtime.WithCallTool) can keep session_read and session_link and leave the calling verbs out. Sessions themselves do not change.

A recorded parent stop fences child admission before and after reservation. If acceptance races the stop, the runtime records the child's stop before acknowledging the call, including calls started with wait: false.

session_call continues a child by default. label and fresh isolate contexts. wait: false returns its session and run IDs. session_listen snapshots up to eight sessions' current runs and parks on their terminal results. With until: "message", it pins transcript heads and waits for later entries, including sessions with no run yet. Optional cursors: [{session, since}] supplies last-seen positions. Results include bounded messages and their next cursors. The worker's janitor repairs missed notifications, including future messages. Both waits are durable and release their worker. No terminal state is inferred from silence.

Agent reads stay within their tree unless an AccessStore explicitly grants access. A context or evidence link grants nothing. Grants and revocations are authenticated host operations. They never cross tenants and are not inherited by another agent merely because it is a child of the granted session.

A host uses runtime.WithChildStarter for its own governed admission path. The hook must use SessionCall.ID as its idempotency key, return immediately after durable acceptance, and never poll for an answer. WithChildRunID supplies its deterministic run ID before admission; the starter must return that ID. Recovery preserves accepted work and fences abandoned admission with a failed ledger record before releasing the slot. WithSessionRuntime must also be set on a host-created sandbox.

Lineage

Every event of a run carries its lineage: Root, ParentRun and ParentToolCall. A root run is its own root and names no parent. A host sets a child's lineage with runtime.WithLineage on the context it accepts the child with. AcceptOwnChild and the session child admissions take the root and parent from the durable parent, so the host passes only the call id. A delegation flow starts itself is called through the parent's tool call, by the id the parent's run.delta.tool.call events carry. A ChildStarter receives that lineage on its context. A turn reads its own from Request.Lineage and passes Lineage.Child(RunID, call) to a run it starts. The lineage is fixed in the durable input, so a retry, replay or resume stamps the same values. A run without lineage stores none.

An accept fails with ErrInvalid when a call names no parent run, a parent run has no root, a run that no run called names another root, a run is its own parent or the called root of its tree, or a child admission names a parent or root other than the durable parent's.

Storage and roles

runtime.WithSessions takes the store: session.NewMemory, or session.NewPostgres on the caller's pool, which persists identity, links, run indexes, grants and reservations. Custom stores must implement AdmissionStore for agent calls, or admission fails closed. Without AccessStore, cross-tree reads are denied.

Unlabelled surface sessions retain their existing fiber_thread_* journal keys. Children and labelled sessions have isolated keys. Old durable inputs replay without session metadata and keep their original journal identity.

Budgets and live usage

A standalone session run requires a positive limits.budget. Each subagent call also requires its own explicit subagents[].budget allocation. Zero grants no work. BudgetStore atomically reserves parent capacity across concurrent calls, persists integer cost, token and request caps, and settles immutable receipts. Each native turn receives the remaining reservation through saige's budget. Unpriced models require token or request caps without a money ceiling. Unknown spend retains the reservation. An abandoned attempt is charged conservatively; a failed budgeted turn ends rather than retrying beyond its reserved allowance.

A completed parent account can retain outstanding child reservations. Late child or grandchild receipts settle through closed ancestors, once, after restart. UsageStore reads live tree totals: actual model call IDs are deduplicated at every ancestor, so child totals are never added a second time. Completed run outputs and events remain immutable snapshots.

The live usage index is repaired from retained per-call receipts before a turn finishes or starts its next wait. Temporary index failures park a memoized reconciliation step. The janitor resumes it after recovery or worker restart, without repeating completed model work or consuming its retry budget. Replayed AccountingIDs remain idempotent; uncertain provider spend is never invented.

Hosts with WithChildStarter own budget admission and native request caps; flow does not reserve the same money again. Legacy Accept and AcceptOwn inputs without budget declarations remain compatible. Explicit session posts and standalone child calls fail closed without a grant or capable budget store. Custom turn runtimes receive turn.Input.Budget and must enforce those caps.

Verification

Race tests cover identity creation, labelled and fresh history, tenant isolation, explicit grants and revocation, concurrent admission and budget reservations, immutable settlement receipts, runtime restart with late descendant settlement, usage redelivery, native request caps, and both terminal and message waits with only one worker. Postgres tests require SAIGE_TEST_POSTGRES_DSN.

Legacy host-admitted children use AcceptOwnChild: parentage must name a retained run in the same tenant, remains immutable across concurrent retries, and records no question or automatic parent resumption. The host still owns admission policy and budgets.