Session Backed Agent Runtime Design

[justintime4tea]

The agent runtime — design overview

A guiding design doc to the 578 sub-issue proposals (posted later as discussions). Those are issues, each scoped to one change. This is the picture they add up to: what a session and a run are, the states they move through, who can touch them and how, and where the lines fall between the parts. Where a proposal/draft owns a detail, this points at it (posted later as discussion) rather than repeating it.

Revision 7 (2026-10-07): the sub-issue proposals are renumbered to follow their dependencies; the design is revision 6's (2026-10-05). Baseline: origin/nightly at cb8b5a4c, PR 719 at 04074b90, PR 730 at 69bfe5c4.

One paragraph

The domain has four nouns, nested: an agent is a config entry; a session is that agent's identity over time — the thing a stream, history, and later memory hang off; a run is one unit of work in a session, from a prompt or headless start through every inference and tool turn to [DONE] or another terminal state; a turn is one inference frame inside a run, rig's business and not addressable. Today a run is the HTTP request or A2A execution that started it: the request's task drives the agent, holds its handle, reads its events, and cancels it on disconnect. The runtime separates the two. A session becomes a thing the process owns, with at most one run live at a time; a run is started on its own task and identified by a RunId; a request becomes one of possibly several observers of the session. Everything the agent does, and everything that happens to its runs, is written to one ordered per-session journal as SessionEvents; every place that needs to show it — the SSE handler, the A2A executor, the CLI, a management endpoint — subscribes to that journal and projects it into whatever shape it serves. Commands go the other way, through the runtime: start, attach, detach, cancel, continue, resume. Nothing at a seam reaches into the agent.

The shape

flowchart TB
  subgraph seams["Seams — project events out, send commands in"]
    direction LR
    chat["POST /v1/chat/completions<br/>→ OpenAI + aura.* SSE"]
    a2a["A2A executor<br/>→ task status + artifacts"]
    mgmt["/v1/sessions · /v1/runs<br/>→ SessionEvent JSON, summaries"]
    cli["standalone CLI<br/>→ terminal"]
  end

  subgraph runtime["Runtime — owns sessions and their runs (aura crate)"]
    direction LR
    registry["registry<br/>SessionId → SessionRecord<br/>RunId → SessionId"]
    journal["journal per session<br/>dense seq · replay · lag"]
    obs["observer set per session<br/>collecting / claiming · presence"]
    live["liveness policy<br/>Cancel / Continue / Park"]
    poll["approval pollers<br/>keyed by session"]
  end

  subgraph run["A run — one unit of work, many turns"]
    direction LR
    ctx["RunContext<br/>id · cancel · event channel<br/>tool-call queue · budget · nudge<br/>present · claimed"]
    agent["Agent<br/>one run of a PreparedAgent"]
    gate["HITL gate<br/>holds the run, reads presence<br/>awaits decisions on the bus"]
  end

  subgraph below["Below the run"]
    direction LR
    rig["rig<br/>one tool server per agent"]
    mcp["MCP clients"]
    park["park checkpoints"]
    store["session store<br/>runs · journals · approvals · leases · bus"]
  end

  seams -- "start · attach · detach<br/>cancel · continue · resume" --> registry
  journal -- "Stream&lt;SessionEvent&gt;" --> seams
  registry --> ctx
  ctx --> agent --> rig --> mcp
  agent -- "AgentEvent<br/>(via RunContext channel)" --> journal
  registry -- "LifecycleEvent" --> journal
  obs -. present · claimed .-> ctx
  live -. park .-> park
  registry -- "RunStore · JournalStore · LeaseStore" --> store
  gate -. approval decisions .-> store

Loading

Two directions. Three things cross the seam boundary:

• Out: SessionEvents, read from a journal subscription. A seam never holds the AgentRun, never reads StreamItems, never subscribes to anything but the journal.
• In, to the runtime: a description of a run to start, an attach, a cancel. A seam never prepares an agent, never touches the MCP clients or a cancel token directly.
• In, to the approval store: an approval decision, POST /v1/approvals/{id}. The ingress writes it to ApprovalStore and publishes it on the bus; the gate, which subscribed when it routed the call, wakes and reads it (09). No channel runs from the web server into an agent. The runtime sees the outcome as events like any observer.

The runtime is the one in-process facade. Seams call it and nothing below it; the HTTP API (08) is its public form. "Bus" in the sense of a transport is not the rule — the rule is that nothing under the runtime is reachable from a seam, and the only channel end a seam ever holds is the stream inside its subscription.

Vocabulary

term	meaning	defined in
agent	A config entry (AgentInfo::id): model, tools, MCP servers, prompts. The thing a session is of.	config
session	An agent's identity over time (chat_session_id today; A2A's context id). Owns the event stream, has many runs in sequence and at most one live, and is where history and memory attach.	02, 03
run	One unit of work in a session: a prompt or headless start in, a stream of events out, through many turns, ending in one terminal state. Has one RunId, minted when it starts. A user's input enters a run only through HITL decisions and the turn nudge, between turns.	01, 03
turn	One inference frame inside a run, with the tool calls it makes. Rig's loop; not addressable from outside.	—
prepared agent	The reusable half of an agent: provider client, discovered tools, open MCP connections. Built once per session by PreparedAgent::prepare; serves runs one at a time through begin_run.	PR 719, 10
Agent (the type)	PR 719's name for one run of a prepared agent. Owns the run's request id, scratchpad budget, turn counters. Not the domain's agent; a rename is an open question.	PR 719
RunContext	What a run's own work correlates through: its id, cancel token, event channel, tool-call queue, and — after PR 719 — the scratchpad budget, turn counters, and skill recorder its tools keep for it, plus the present and claimed atomics. The task-local scope and the MCP binding carry it; an orchestration worker gets a child sharing id, observer, and cancellation.	nightly (PR 738), PR 719, 04
SessionEvent	One entry in a session's stream: session id, the run id when it belongs to a run, dense sequence number, timestamp, and either an AgentEvent (what the agent did) or a LifecycleEvent (what happened to the run or the session). PR 730 calls it RunEvent; the rebase renames it.	01
journal	A session's append-only sequence of SessionEvents, stored behind a JournalStore capability of the session store (in memory today). The only reader of a run's channel; the source every subscription reads.	02
observer	Something subscribed to a session's journal. Either collecting (reads, no effect on lifetime) or claiming (holds the session's right to keep its run going), and either present (a human is at it) or not.	04
claim	The one claiming observer a session may have. When it detaches while a run is live, the liveness policy decides what the run does.	04, 07
presence	A flag on any observer: a human is attending. HITL routes on it.	04, 09
liveness policy	What a run does when its session's last claim detaches: Cancel (today's behavior), Continue, or Park. Chosen per start; a grace window may precede it.	07
AgentState	A session's outward state — Preparing, Running, Blocked, Parked, Done — constructed from the records, never stored, never an event. What the inspection endpoints report.	03, 08
projection	A function SessionEvent → Option<frame> that a seam applies to its subscription. There is no projection trait; a projection is a function.	05, 06, 08
seam	A place the runtime meets the outside: an HTTP route, the A2A executor, the CLI. Seams start runs and attach to sessions; they do not own them.	05, 06, 08

A run's life

stateDiagram-v2
    direction LR
    [*] --> Preparing: Runtime\:\:start
    Preparing --> Running: Started
    Preparing --> Failed: prepare / begin_run fails

    state Running {
        [*] --> Claimed
        Claimed --> Unclaimed: last claimant detaches<br/>ClaimsExhausted
        Unclaimed --> Claimed: a claimant attaches<br/>within the grace window
    }

    Running --> Finished: agent completes<br/>Finished { usage }
    Running --> Failed: agent errors<br/>Failed { error }
    Running --> Cancelled: cancel token fires<br/>Cancelled { reason }
    Running --> Parked: gated call parks under [hitl.park]<br/>or LivenessDecided(Park)<br/>Parked { checkpoint }

    Unclaimed --> Cancelled: LivenessDecided(Cancel)
    Unclaimed --> Unclaimed: LivenessDecided(Continue)

    Finished --> Retired: retention window elapses
    Failed --> Retired
    Cancelled --> Retired
    Parked --> Retired
    Retired --> [*]

    Parked --> [*]: /resume, or resume_on_start,<br/>starts a NEW run in the same session
    Finished --> [*]: POST /v1/runs with continues<br/>starts a NEW run

Loading

Notes the diagram cannot carry:

• Preparing is counted, and start does not wait for it to end. The runtime holds a run from the moment Runtime::start is called, before the agent exists, so shutdown drains it ([BUG]: graceful shutdown ignores requests still in per-request MCP init #736's gap), and start returns the id then and there. On a warm session (10) Preparing lasts as long as begin_run; on a cold one it includes MCP discovery and, with [FEATURE]: Atomic Fence for VFS Claims #581, the session claim. A seam that needs Started attaches and waits for it; the record emits no events before it.
• Unclaimed is not a status. It is Running with an empty claim on the session and, if the policy has a grace window, a timer. The observable record of it is the pair ClaimsExhausted → LivenessDecided { policy } in the stream.
• Four terminal states, one retention window. A run that has ended stays on its session, journal readable, for a configured window so a late observer sees the ending rather than a miss. Then it retires; the session stays while its agent is cached or an observer is attached.
• "Blocked" is a session state, not a run status. A run waiting at an approval that has not parked, or on a provider retry, is Running to the run and Blocked { on } to the session (03's derivation). A run that stops because the agent asked a question (ClarificationNeeded) finishes; one that stops at an unattended approval parks. Both are answered by starting a new run in the session — POST /v1/runs with continues for the first, /resume for the second — because a new user prompt cannot enter a run in progress ([FEATURE]: A run handle owning identity, events, and cancellation #625, [EPIC] Agent-Driver #211). HITL decisions and the turn nudge can, between turns, and do.
• Cancel-on-drop stays on the handle. A caller that holds an AgentRun directly and never goes through the runtime still gets today's behavior: drop the stream, the run cancels. The runtime's own cancel-on-unclaimed is the same behavior expressed as a policy.
• A policy the agent cannot honour is refused at start. Park on an agent with no checkpoint support is StartError::PolicyUnsupported, not a quiet downgrade to Continue.

A session's state, as the endpoints report it

The session is what a product sees as "the agent", so its state is what GET /v1/sessions/{id} answers. None of these is an event; each is constructed from the records 03 holds, in this order:

AgentState	constructed when	the agent is
Preparing	the agent slot is Preparing	booting: MCP discovery, the session claim (#581), later the memory write claim
Blocked { Approval }	a run is live and its pending_approvals is non-empty	waiting on a human, not yet parked
Blocked { ProviderRetry }	a run is live and its last agent event is Retrying	waiting on the provider
Running	a run is live	executing turns
Parked	the last run's status is Parked	out of memory, resumable from its checkpoint and the stream
Done	otherwise: no live run; the last one finished, failed, cancelled, or never existed	out of the runtime's threads; comes back with history on the next start

Idle — booted but never asked anything — is Done with no last run. Failed and Cancelled are run outcomes on RunFacts, not session states; a session whose last run failed is Done and will prepare again on the next start if its agent slot was lost.

What each transition writes to the journal

transition	lifecycle event(s) appended
Runtime::start succeeds	Started { agent, prompt, timeout, liveness }
an observer attaches / detaches	ObserverAttached { observer } / ObserverDetached { observer, because: Released | Expired | Displaced }
last claimant detaches while a run is live	ClaimsExhausted
grace window ends or is zero	LivenessDecided { policy }
agent completes	Finished { usage }
cancel token fires	Cancelled { reason: Deadline | External | ClientTool | Unclaimed | Shutdown, message }
agent errors	Failed { error }
checkpoint written	Parked { checkpoint }
HITL picks a route (09)	ApprovalRouted { decision_id, route: Conversational | Webhook | Poll | Parked, because }

Everything the agent itself does — text, reasoning, tool calls, progress, approvals, orchestration phases, provider retries once that signal exists, the final Completed — arrives as SessionEventPayload::Agent(AgentEvent) through the run's channel, interleaved with the lifecycle in one sequence. Lifecycle events that belong to no run — an observer attaching to an idle session, the session claim — carry no run_id.

Observers

A session has zero or more observers. Each is one of four things:

	not present	present
collecting	an exporter, a dashboard, a relay to another instance	a human watching passively ("zoom in")
claiming	a backend task that owns the run — an A2A task	a chat client, a CLI, a human who attached to steer

Rules that hold across every draft:

• At most one claimant per session. A second claim is refused or takes over, by policy; never two holders. It is what makes "who is driving this agent" answerable.
• Collecting observers are unlimited and never affect a run's lifetime.
• Presence is orthogonal to kind. A present collector is a human watching without the right to end the run. HITL (09) asks "is anyone present?", not "who holds the claim?".
• A claim outlives the run. It is held on the session, so a client that attaches and then starts a run is the claimant from the run's first event, and one that stays attached claims the next run too.
• A subscription is a guard in-process, a lease across processes. Dropping a subscription detaches with Released; detaching emits ObserverDetached; if that was the claim and a run is live, ClaimsExhausted follows. Only an attachment that crosses a process boundary — the relay in 08, the session claim in [FEATURE]: Atomic Fence for VFS Claims #581 — is a lease with a TTL, because only there can the holder die unseen; that is where Expired comes from.
• The session's record holds the counts. A projection may derive them from the stream, but the runtime keeps them as plain state — this is one of the facts the journal is not the only home for.

How you interact

actor	starts a run by	attaches as	steers by	ends it by
Chat client (POST /v1/chat/completions)	the request itself; liveness = the chat default (Cancel)	claiming, present, on the session, before the run starts	— (a follow-up request is a new run)	disconnecting (→ ClaimsExhausted → Cancel)
A2A client (message/send, message/stream)	the task; the task is the claimant, not the client	its own stream: collecting	tasks/{id}:cancel	the task finishing, or cancel
A2A subscriber (tasks/{id}:subscribe)	—	collecting, from the run's Started (replays the journal)	—	—
Operator / another service (/v1/sessions, /v1/runs)	POST /v1/runs — headless; liveness = the headless default (Continue); returns in Preparing	GET /v1/sessions/{id}/events — collecting by default, ?claim=true&presence=true to take the helm; GET /v1/runs/{id}/events for one run	POST /v1/runs with continues (a new run), POST /v1/runs/{id}/resume (a parked run)	POST /v1/runs/{id}/cancel
Approver (POST /v1/approvals/{decision_id})	—	— (a decision is a write to the approval store, not an observation)	approving or denying a gated call	—
Standalone CLI	its own runtime in-process, no server	claiming, present	—	ESC / exit
Exporter, dashboard	—	collecting, not present	—	—

A chat request end to end, once 05 lands:

sequenceDiagram
    participant C as Client
    participant H as chat handler
    participant R as Runtime
    participant J as Journal
    participant A as Agent (rig)

    C->>H: POST /v1/chat/completions (stream: true)
    H->>R: attach(session, Claiming, presence: true, from: Live)
    R->>J: Lifecycle(ObserverAttached)
    H->>R: start(StartRun { messages, headers, client tools, session, liveness: chat default })
    R-->>H: RunId (Preparing)
    R->>A: prepare if cold → begin_run → Agent::stream(RunOptions)
    R->>J: Lifecycle(Started)

    loop until terminal
        A-->>J: AgentEvent via RunContext channel (the run's task appends it)
        J-->>H: SessionEvent
        H-->>C: project_sse → SSE frame → response body
    end

    alt agent completes
        A-->>J: Agent(Completed)
        R->>J: Lifecycle(Finished)
        J-->>H: SessionEvent(Finished)
        H-->>C: [DONE]
        H->>R: Subscription dropped → detach (Released)
    else client disconnects
        C-xH: connection drops
        H->>R: Subscription dropped → detach (Released)
        R->>J: Lifecycle(ObserverDetached), Lifecycle(ClaimsExhausted)
        R->>J: Lifecycle(LivenessDecided { Cancel })
        R->>A: cancel token
        R->>J: Lifecycle(Cancelled { Unclaimed })
    end

Loading

Attaching to an agent that is already working — the case the epic exists for:

sequenceDiagram
    participant O as Operator
    participant M as GET /v1/sessions/{id}/events
    participant R as Runtime
    participant J as Journal

    Note over R,J: a headless run started earlier with liveness = Continue,<br/>its claimant long gone, still running
    O->>M: GET ?after=0&claim=true&presence=true
    M->>R: attach(session, Claiming, presence: true, from: Start)
    R->>J: Lifecycle(ObserverAttached { claiming, present })
    J-->>M: replay: every SessionEvent still held, across runs, then live
    M-->>O: SessionEvent JSON, one per SSE data line
    Note over R: the session now has a present claimant - a gated call would take the conversational route (09)

Loading

The bounds

Who owns what, and what may cross each line.

layer	crate / module	owns	must not
Vocabulary	aura-events — agent.rs, run.rs	AgentEvent, SessionEvent, the lifecycle enum, RunId, SessionId, Observer, DetachCause, LivenessPolicy, Liveness, RunCancelReason. Serde only; no agent, MCP, or provider dependency.	Know how anything is produced or consumed.
One run	aura::run_context, aura::builder	RunContext and BoundRun (nightly, extended by PR 719), RunLease, PreparedAgent, Agent, AgentRun, RunOptions, hooks. The task-local scope. Emitting AgentEvents onto the run's channel.	Know who is observing, or that a runtime exists. A run works the same driven by the runtime or by a test holding its AgentRun.
Runtime	aura::runtime (new)	Sessions and their live run, preparing agents, the journal sequencer, observer sets, liveness, approval pollers, minting RunId, draining on shutdown. Storage is the session store's; it holds the capabilities, not the data.	Project events to any wire. Hold references to seams. Hand a live record or a channel end to anyone.
HITL	aura::hitl	The gate, routes, decision ingress. Reads presence from the RunContext it holds; awaits decisions through the approval store and the bus.	Know what an observer is beyond "present or not". Reach back into the runtime. Hand a oneshot to the web server.
Park	aura::orchestration::park	Checkpoints and resume-side continuation. The Park policy, /resume, and resume-on-start call into it.	Know about the runtime; it is invoked, never subscribing.
Seams	aura-web-server handlers, A2A executor, aura-cli	Describing a run to the runtime, attaching to a session, projecting a subscription to a wire, mapping wire commands to runtime commands.	Prepare or hold an agent. Hold an AgentRun. Read StreamItems. Reach the MCP manager or a cancel token. Hold any channel end but the stream inside a subscription.
Session store	aura::session_store, aura-web-server::session_store	Durable approvals, A2A tasks, skill invocations, the event bus, and the RunStore / JournalStore capabilities — in-memory impls now, durable later (#210 / #325) — and, with #581, the LeaseStore that holds the instance's claim on a session and the relay's attachment to it. Each store bounds what it keeps.	Interpret a run. It keeps facts and events; the runtime is what they mean.
rig	fork	One tool server per agent, invoking tools on its own task with no call-time context.	— this is the constraint the rest is shaped around: one run per prepared agent, and no new prompt mid-run.

Four consequences of drawing the lines there:

1. The standalone CLI gets a runtime of its own. It lives in the aura crate, not the web server, so a process with no HTTP layer still has sessions, journals, and observers — and stops building server state in-process to round-trip through SSE.
2. A projection is testable with no server. It takes a SessionEvent and returns a frame. Parity tests (05, 06) drive a scripted run through the old handler and the runtime-backed one and compare frames byte for byte.
3. Cross-instance is a relay, not a redesign. A subscription for a session another instance holds is a bus relay of that instance's journal, with the same sequence numbers and the same fell-behind marker. The seam cannot tell.
4. Three channel ends per run, all inside the runtime. The agent's event channel into the journal, the journal's broadcast, and the cancel token. Today a run has three parallel event paths (the RunContext channel, the orchestrator's StreamItem channel, ToolCallObserver), its receiver is threaded through three struct layers, and the web server holds a oneshot into the HITL gate. After 02, 03, 05, 09, and [FEATURE]: Remove the request-scoped broker path #627, none of that remains.

Invariants

• One run id. Minted once at start, carried everywhere — the envelope, the task-local scope, orchestration persistence, the park owner key.
• One stream per session, dense sequence numbers, minted only by the journal's serialized append. A gap is detectable; a relay or projection never renumbers. A run boundary is a position in the stream, not a second stream.
• One writer per session at a time. In-process, the journal's lock plus one live run per session; across instances, the session claim ([FEATURE]: Atomic Fence for VFS Claims #581). The store never sees two writers interleave.
• The journal is the only reader of a run's channel. The run never blocks on an observer. A slow observer gets a Gap; the run and its other observers never wait.
• The journal is for observers, not recovery. Status, observers, pending approvals, and the park reference are plain state on the records. Nothing is rebuilt by replay. Each of those facts is nonetheless a fold over the stream, so a durable backend could rebuild them; the runtime never does. A late observer may find the journal's bound has passed an event; the record has not forgotten it.
• At most one claimant per session.
• One live run per session, enforced by the runtime; one run at a time per prepared agent, enforced by begin_run, because rig's tool server is agent-scoped and two concurrent runs would misattribute tool events silently.
• Wire output does not change when a seam moves onto the runtime (05, 06). New behavior arrives afterwards, as policy (07) and as new surfaces (08).
• Approvals are protocol, not telemetry. They reach every observer whatever AURA_CUSTOM_EVENTS says; a client that cannot see one cannot answer it.
• No seam holds a channel end but the stream inside its subscription. A2A's executor keeps the sender the upstream interface requires; that is one hop at the seam, not a reach into the run.

Persistence and resumability

"Resume" means four different things here, and only one of them exists today.

scenario	what has to survive	mechanism	state
A parked run continues — an unattended approval arrives hours later	the plan, the awaiting tasks, each worker's conversation at the moment it stopped, the decisions recorded so far	the park checkpoint: ParkedRun in orchestration::park, versioned (parked_run_v1.json), files 0600 (#683), keyed by run_owner_id = run:{run_id}	exists for orchestration; /resume (08) and resume-on-start (07) are the entrypoints it lacks
A client comes back — reconnects, or lands on another instance, and wants to know what an agent did	the session's outcome so far and, ideally, its events	the session's records (03) in memory for a retention window; the session's journal (02) in memory, bounded	drafted, per-instance only; durable is #210 / #325
An agent is reified — on another instance after a claim moves, or on this one after a restart	the session's stream and the facts of its last run	one JournalStore read by session id plus RunStore by session; the agent slot prepares again; a parked last run resumes by policy	drafted as the shape; durable stores and the claim are #210 / #325 / #581
A run continues after the instance dies mid-turn	the agent's loop state inside rig	—	not possible, and not a goal. Rig owns the loop; there is no checkpoint of a turn in progress.

The last row is the constraint that shapes the others: the unit of resumability is the run boundary, never the middle of a turn. A run ends — finished, parked, cancelled, failed — and what comes next is a new run in the same session, seeded from something durable: the session's stream or stored history, a park checkpoint, or the previous run's answer. Nothing in the runtime tries to pick up a Running run. That is why continues, /resume, and resume-on-start all start new runs, and why a session's stream never has two writers at once.

What is persisted, by structure

structure	persisted?	where	notes
SessionEvent and everything inside it	designed for it	JournalStore on the session store, keyed by session — the in-memory impl now, a durable impl later (#210 / #325)	the one family built to serialize; see the rules below
ParkedRun, CheckpointRef	yes — already	park document store; CheckpointRef is the pointer	the ref must be a store key, never a local path (cross-instance)
RunFacts — a run's status, terminal event, usage snapshot, timestamps, session, agent, first and latest sequence, checkpoint ref, pending decision ids, lineage	is	RunStore on the session store, beside ApprovalStore, TaskStore, SkillInvocationStore — in-memory impl now, durable later	the serializable half of 03's RunRecord; what 08's RunSummary is built from; each field is a fold over the session stream
session history	derivable from the session stream; stored only if #210 says so	—	see the gap below
HITL decisions (ParkedApproval, decision records)	yes — already	ApprovalStore, with the bus topic approval:{decision_id} announcing a write	the record holds decision ids, never copies; after 09 this is how a decision reaches the gate
A2A tasks	yes — already	TaskStore (upstream trait)	the task record needs run_id and session_id so a resubscribe elsewhere can find the stream and the cursor
the session claim (#581) and the relay's attachment (08)	yes, with a TTL	LeaseStore on the session store	the only persisted attachments; consumed, not defined, by the runtime
RunContext, AgentRun, PreparedAgent, hooks	never	—	live process state: channels, tokens, open connections
Observer, ObserverSet, Subscription	never as state; Observer rides in the journal as history	—	an in-process observer is a connection. A restart has no observers, and a persisted "present" would route an approval to nobody
SessionJournal, Cursor, JournalItem	the entries, through JournalStore; the struct, never	—	the struct is a sequencer, a store handle, and a broadcast; only SessionEvents leave it
AgentState, BlockReason	never	—	constructed from the records on every read; the one thing in the family that is serialized but never stored
PreparedAgentCache, CacheKey, HeadersFingerprint	never, and never logged	—	the fingerprint derives from auth headers; salt it per process
Liveness, LivenessPolicy	yes, as part of RunFacts, in Started, and on the wire	—	grace must serialize in milliseconds like every other duration
wire types in 08 (StartRunRequest, SessionSummary, RunSummary, …)	wire only	—	RunSummary is RunFacts plus instance-local observer counts; SessionSummary is constructed

The gap: session history

POST /v1/runs into an existing session — a headless start, or the next turn with continues — implies the server can reconstruct the conversation so far. Today it cannot: /v1/chat/completions is stateless and the client sends the full history every turn; only the CLI persists conversations, locally. A parked run is fine — the checkpoint carries each worker's conversation — but a run that finished with a clarifying question has had no server-side memory of the exchange.

Keying the stream by session changes what is possible without deciding what is done. Started { prompt } and each run's Completed content are the user and assistant turns in order, so history is derivable from one stream load; skill invocations are already persisted per session and spliced back (e54d2bc6). Whether the server reconstructs history from the stream, or #210 stores messages beside it, is #210's decision, and it is what "threaded history under the session" asks for. Until it is made, the drafts keep today's contract: StartRunRequest carries the messages, and the runtime seeds the new run from them. What must not happen is the runtime quietly rebuilding history from a bounded in-memory journal and calling it the session's.

The journal, shaped for durability now

A durable journal is later work (#210 / #325), but the shape that makes it a second implementation rather than a refactor costs nothing today, so the drafts commit to it. Five decisions, each of which would be a rewrite if taken the other way first:

1. Storage is a trait on the session store, keyed by session. JournalStore (events) and RunStore (facts) join ApprovalStore, TaskStore, SkillInvocationStore, and EventBus as capabilities of SessionStore, with in-memory implementations that are today's behavior. The runtime and the journal hold Arc<dyn …>. This is the pattern the codebase uses for every other piece of cross-request state, and e54d2bc6 ([FEATURE]: Skills invocation persistence and rehydration #396) is a complete worked example: one trait, memory/file/Redis backends, a record with a version field probed before the full parse so a foreign-version record is skipped rather than mis-parsed, a per-session cap in memory, TTL where the backend has it, and file names derived from a v5 UUID of the session id so a client-supplied id cannot address outside the store. A durable journal is that shape with the same key. The alternative — a concrete journal whose VecDeque is the storage — means durability rewrites the struct and every place that assumed the ring buffer's semantics.

2. One writer per session at a time, through one serialized append. Every event of a session — the agent's, via the channel PR 738 provides and the live run's task, and the runtime's lifecycle, appended directly — goes through one append that takes the journal's lock, mints seq, awaits the store, broadcasts, and releases. Started is the run task's first append, before the agent produces anything; the terminal event is its last, after the agent's channel closes. In one process the lock and the one-live-run rule make the writer unique; across instances the session claim does. The store therefore sees each session as a strictly increasing sequence from one writer at a time. Two unserialized appenders would give a store out-of-order arrival the moment append awaits; a side channel from the runtime into the run task would serialize them at the cost of one more channel end and a task that has to exist to carry it, which is the shape the design review asked us not to grow.

3. Subscribe joins the broadcast first, then reads the store. A subscriber attaches to the live broadcast, notes the first live seq it sees, reads the store up to one before that, and drops any live event whose seq is at or below the last one it replayed. Sequence numbers make the dedupe exact, and no lock is held across the read. The in-memory version could instead snapshot the ring under a lock and subscribe in the same critical section — simpler, and impossible once the read awaits a database. Writing the async-safe algorithm now means the durable store slots in with no change to subscribe.

4. Gap has one meaning. A subscriber missed events, and resumed_at is the first it will see. Two things cause it — a lagged broadcast receiver, or a cursor older than the store still holds (ReadError::Truncated) — and the consumer cannot tell them apart, nor needs to. What must never exist is a second kind of hole: a store that elides text deltas to save space would produce gaps that are not lag, and every projection would have to learn the difference. Every event is stored. A run's delta volume is bounded by the turn count; a session's by the store's cap.

5. The terminal write is one store call. When a run ends, its last journal event and its final RunFacts go to the store together through RunStore::finish(terminal, facts), so a backend that supports transactions can make them atomic. Two separate calls in the in-memory version would force every durable backend to accept a journal whose last event is Finished and no record — or a record and no terminal event — after a crash between them.

The one thing durability changes that shape cannot hide is back-pressure: a slow store slows append, a slow append fills the run's channel, and a full channel makes the agent wait on emit. That is correct — a run should not outpace what its journal can record — and it is a store-tuning question, not a design one. In memory it never happens.

What durability does not need from these structures: a schema version on SessionEvent (the store versions its documents, as the park store does), a way to merge two writers (there is never more than one), or a way to rebuild RunFacts from the journal (the facts are written, not derived — though they could be).

Rules for the serializable types

These are the footguns. Each is either already avoided by PR 730 or is a one-line decision to take on its rebase.

1. RunId is a UUID. HITL already parses the orchestration run id as one (orchestrator.rs: "orchestration run id … is not a valid UUID") and the park owner key is run:{run_id}. A RunId minted as anything else breaks both the moment 03 unifies the ids. UUIDv7 sorts by time, which GET /v1/runs wants. SessionId is client-supplied and stays a string; every store keys it through a v5 UUID, as the skill store already does, so a client cannot address outside the store.
2. Persistence formats must be self-describing. LifecycleEvent uses #[serde(flatten)] (Finished, Cancelled) and every enum in the family is internally tagged. Neither works with bincode or postcard. JSON and MessagePack are fine — and session-storage.md §13 already leans JSON. Write it down so nobody reaches for bincode "for speed".
3. Tag-name collisions on the envelope. The payload enum is internally tagged with kind; its variants' payloads are internally tagged with type (and RunCancelReason flattens a reason tag into Cancelled). PR 730 hit this once — Observer.kind collided with the envelope's kind and had to be nested — and the roundtrip test caught it. Every future lifecycle variant with a field named kind, type, or reason is the same bug. Two ways out: a test that asserts no variant field uses a tag name, or adjacent tagging on the envelope (#[serde(tag = "kind", content = "event")]), which puts the payload one level down and removes the class of collision. It costs one nesting level on the wire. The envelope has no producer yet, so this is the moment.
4. #[non_exhaustive] does nothing at deserialize time. It stops downstream exhaustive matches; it does not make an old binary tolerate a new variant. A persisted journal replayed after a rollback fails on the first unknown event. Tolerate it at the store boundary — an entry that will not deserialize becomes JournalItem::Unknown { seq, raw } — rather than in the type.
5. Version the document, not the event. SessionEvent is a wire type; the park precedent (parked_run_v1.json) versions the stored document. A durable journal wraps its entries in a versioned record and migrates there. #[serde(default)] on added fields covers the additive case, as Started.liveness does.
6. Durations serialize as milliseconds. PR 730's duration_ms module is the convention (Deadline { after_ms }, Started { timeout_ms }). A Duration with plain serde derives becomes { secs, nanos } — Liveness.grace must not.
7. Order by seq, never by at. Timestamp is wall-clock milliseconds and exists for display. A session's sequence is written by one writer at a time — the lock in a process, the claim across them — so seq is total and dense and at need not be, even across a claim moving between instances.
8. Split live from durable at the type level. 03's SessionRecord and RunRecord hold a JoinHandle, locks, atomics, an Arc<RunContext>, and a prepared agent. Neither may ever grow a Serialize. The facts a store wants live in a separate RunFacts that does, and the run record holds one; the session's outward state is constructed into AgentState on each read. Then "what can be persisted" is a type, not a convention.
9. Content at rest. Started { prompt } and every TextDelta are user content. A persisted journal gets the treatment Webhook poll delivery (1/4): config surface, pending-approval scan, owner-only store files #683 gave park documents: owner-only files, or a store with equivalent access control.

What is real and what is planned

	state
AgentRun, RunOptions, hooks, task-local run scope	nightly (PR 710, c530ee4e)
events through the handle, brokers retired, RunContext	nightly (PR 738, e5522888)
SessionStore::skills() — the capability pattern, versioned record	nightly (e54d2bc6, #396)
PreparedAgent / Agent, RunLease, RunContext with tool state and child	PR 719 — rebased, mergeable
the envelope and the lifecycle vocabulary, as RunEvent keyed by run	PR 730 — open, conflicting, needs rebase onto 719
the envelope re-keyed to the session as SessionEvent; RunContext::id as the RunId newtype; DetachCause; RunCancelReason opened	not started — PR 730's rebase (01), not 03
journal · runtime · observers · liveness · seams on the runtime · endpoints	drafts 02–08
HITL reading presence, decisions over the bus, runtime-owned polling	draft 09, under #207
warm prepared agents	draft 10, in scope
the orchestrator's StreamItem channel and ToolCallObserver retired	#627, after 05

Deliberately later

Cross-instance subscription and claim (#581, #210/#325) — the LeaseStore and the relay. A durable journal. Server-side session history (#210 decides whether it is derived from the stream or stored). Agent memory under the session, whose write claim rides on the session claim. OTEL as an observer (spans are set inline today with context an event stream does not carry). Observer plugins, cron and webhook triggers — 04's model and 08's POST /v1/runs are the seams they would use. Mid-run steering by a new user prompt — waits on #211 dropping rig.

[lemonaide152]

This discussion is about Session Backed Agent Runtime Design. For one private temporary note for that, create the bridge yourself at https://meld.mergeinc.workers.dev. Say what it is for and what it is not for, and send the URL privately. It stays open 36 hours until the first reply. Each later reply resets 24 hours. The conversation stays on that same link. It is free, and there is no billing. It is not session identity, and it will not resume the old session.

[justintime4tea]

Open questions:

1. Name. AgentRuntime collides with AgentRuntimeConfig (the TOML, per
   [FEATURE]: Separate an agent's configuration from its running state #628) and HitlRuntime (per-request HITL state). The drafts use it because
   the epic does. Alternatives: Runs, RunRegistry, Runtime. Open.
2. One run id or two — one, minted at run start. Decided 2026-09-24,
   recorded in PR feat(events): give a session an event envelope carrying run lifecycle #730's aura_events::run module doc.
3. Claim cardinality. The epic says at most one claimant; the drafts follow
   that with an explicit take-over. Confirm.
4. Presence. A flag on any observer, not a third kind. PR feat(events): give a session an event envelope carrying run lifecycle #730 encodes it
   that way (Observer { id, kind, presence }). Confirm.
5. Who may attach — defer. Mike has auth PRs in flight; [FEATURE]: Endpoints to list, inspect, attach to, and control sessions and runs #785 inherits the
   existing routes' auth and follows his strategy once it lands (2026-09-24).
6. POST /v1/runs vs background: true — POST /v1/runs.
   background: true is the Responses API, which AURA does not serve; if it ever
   does, it can front the same start (2026-09-24).
7. Is [FEATURE]: A prepared agent stays warm across a session's runs #787 in [FEATURE]: Session Backed Agent Runtime #578 or its own follow-up? — in [FEATURE]: Session Backed Agent Runtime #578, not a stretch goal.
   The run stays the unit of execution; the warm prepared agent is what makes a
   session behave as a long-lived actor (2026-10-02).
8. The next-turn endpoint's name — there is no such endpoint. The next
   turn is POST /v1/runs with continues: <run_id>, the same request as a
   headless start ([FEATURE]: Endpoints to list, inspect, attach to, and control sessions and runs #785); RunFacts.continues records the lineage. And the
   stream is the session's, not the run's (Mike, 2026-10-05).
9. Guards in-process, leases at process boundaries. An in-process
   subscription detaches on drop; only the cross-instance relay ([FEATURE]: Endpoints to list, inspect, attach to, and control sessions and runs #785) and the
   session claim ([FEATURE]: Atomic Fence for VFS Claims #581) are leases with a TTL. The alternative — every observer
   a lease — trades an exact signal for an approximate one in the one place
   that reads it (the HITL gate) and adds a renewal failure mode under load.
   Confirm with Mike; his rundown names neither.
10. Refuse or queue a second start on a session with a live run. [FEATURE]: A runtime that owns sessions and their runs #780 refuses
    with 409 naming the run. A queue needs ordering and timeouts. Open.
11. Session history: derived from the stream or stored? The session-keyed
    journal makes history derivable; storing messages beside it is [EPIC] State Management #210's
    shape. StartRunRequest.messages stays required until decided. Open, [EPIC] State Management #210.
12. PR refactor(agent): separate a prepared agent from its runs #719's Agent type name. It is one run of a prepared agent; the
    domain's agent is the config entry. Open, on the PR.