The life of a session
An AgentSession isn't a process that runs until it stops — it moves through a small set of governed, observable states. It's born scoped, runs in turns, waits when it needs a human, sleeps when idle, and ends accountably. Knowing those states is knowing what an agent is actually doing.
It starts scoped
A session begins from a channel message, the CLI, or a kubectl apply. It inherits everything its
class allows — tools, identity, authorization — and narrows from there, with its own
budget and its own audit trail. Before it acts it may pause at the door: a guest may need
start approval, a passthrough agent needs your credentials,
and an ask/dynamic agent needs an identity choice. These are waits, not failures —
the session parks until the answer arrives.
It runs in turns
Once cleared, it runs turns: the model proposes tool calls, the gated pipeline runs them, the results feed back. Its status is visible the whole time — thinking, a tool running, a plan's progress — and a silence watchdog catches a turn that goes quiet rather than letting it hang.
It waits when it must
Some states are deliberate pauses. When the agent hits an action that needs sign-off it parks awaiting a decision and surfaces an approval; it can park awaiting credentials or an identity choice. Parking is not spinning — a parked session isn't burning its budget on nothing, and the person it's waiting on is told what it needs.
It sleeps when idle
A session that goes quiet doesn't hold a pod forever. After an idle interval its pods are reaped to free resources — but the session stays wakeable: the next message rehydrates it and it picks up exactly where it left off. Continuity is a property of the durable session, not of a process staying alive, which is why a conversation can span days without an idle agent costing anything.
It's bounded
Every session carries a budget: ceilings on tokens, on turns, and on cumulative active run-time (time parked on a human doesn't count). A separate hard expiration caps its wall-clock lifetime even while it sleeps. Hit a ceiling and the session ends cleanly rather than running away — the budgets are a backstop the class sets once and every session inherits.
It ends accountably
A session finishes Succeeded or Failed. If its class declares delivery requirements, it can't complete until it has actually handed over the work it produced. At completion the audit chain heads are anchored — the tamper-evident record of what happened is sealed — and only then is the session reaped. A session can also be placed on a hold: frozen in place for inspection instead of torn down, when something needs a closer look.