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.
s, err := app.Session(ctx, session.Open{
Parent: "github://acme/service/pull/5", Agent: "reviewer",
Channel: "github://acme/service/pull/5",
})
if err != nil { return err }
accepted, err := s.Post(ctx, "Review this change")
Post returns a durable acceptance. Stream tails the session and newly created
direct children, with a map of run IDs to sequence cursors. Read returns at most
200 journal entries after a cursor. Summary returns deterministic excerpts with
entry citations. Children and Link expose the tree and context references.
Hosts authenticate and authorize before opening a handle. 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. Humagen uses this seam for
pkg/call. 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.
Storage and roles
WithSessions replaces the memory default. WithPostgres persists identity,
links, run indexes, grants and reservations on the caller's pool. 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.
Run(ctx, RoleExecution) runs workers only. RoleIngress, RoleDispatch and
RoleDelivery select the other responsibilities. Omitting roles starts all of
them. Handler() is the combined webhook handler. The older one-shot Ask and
Reply, RunDelivery, RunExecution and WebhookHandler remain compatibility
entry points while callers migrate.
Budgets and live usage
Standalone Session.Post 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.
Session.Usage reads live tree totals from UsageStore: 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 FLOW_POSTGRES_TEST_URL.
Hosts can preserve their definition validation with WithDefinitionResolver.
It carries the host resolver without registering an executable provider. 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.