HTTP streams and recovery #
This reference describes session replay and collection invalidations. OpenAPI defines event variants and payload bounds. HTTP API behavior defines common HTTP rules.
Session watch #
http_session_stream.gleam
owns HTTP attachment. The session actor
captures live state and replay position.
GET /sessions/{session_id} with Accept: text/event-stream watches one
session. Initial attachment omits after_generation and after_seq. Reconnect
sends both from the last fully consumed batch. tail applies when a snapshot is
needed. JSON reads return the same cursor pair for subsequent attachment.
Vary: Accept distinguishes the representations. A successfully installed JSON
session snapshot counts as the initial reset. Its cursor can seed the SSE watch
after the snapshot callback succeeds. Without an installed snapshot, the client
omits the cursor and requires reset.
A batch uses this envelope. snapshot appears only with a leading reset.
{
"generation": "J6kYj6IGcXyP3eMIp-WL3A",
"cursor": 42,
"events": [
{"type": "reset", "data": {"reason": "initial"}}
],
"snapshot": {
"id": "019a0000-0000-7000-8000-000000000001",
"history": {"items": [], "older": null, "newer": null, "high_water": 0},
"current_progress": [],
"pending_inputs": []
}
}
The example shows the relevant snapshot fields. A real snapshot is the complete
Session representation defined in OpenAPI. Generation is a
nonempty base64url 128-bit random identity created by the session actor
initializer. Sequence is a nonnegative integer in that generation. Empty
keepalive batches carry both values and an empty events array. Keepalives do not
advance the event sequence. The data: JSON is authoritative. This protocol
does not use SSE id or automatic Last-Event-ID recovery.
The session checks generation equality before consulting numeric replay bounds.
Missing or different generation, or an unavailable sequence, requires a durable
snapshot reset. Malformed cursor components return 400 before headers. A
well-formed future or evicted cursor resets. The replay buffer retains at most
256 events or 992 KiB, whichever bound is reached first. An oversized event is
represented by bounded history references.
Registration and state capture serialize with session publication. A reset
captures state, bounded current progress, pending ownership, and replay cursor
together, then loads history through the captured durable high-water mark. It
also captures ordered active_output segments. Their inline text or signed
content references include the complete unfinished prefix at that cursor,
including output evicted from the replay buffer. Text and thinking share a 64
KiB encoded inline budget. Spill references fix their byte cutoff and remain
readable for 15 minutes even when the response commits during hydration. Content
reads retain the original snapshot query while following next. Continuations
cannot extend the original snapshot's lifetime. Expiration returns
410 active_output_expired and requires a fresh session snapshot. Capture
publishes any pending coalesced progress or activity before choosing the cursor.
Live-state changes advance the actor sequence. One cursor cannot identify
conflicting status, progress, or activity replacements. Events after that cursor
remain eligible for replay. Slow snapshot loading cannot silently skip an
evicted interval: the subscription resets again or closes with failure.
Transcript loading failure emits failure and closes. It never installs a
successful replacement cursor.
Client delivery follows these rules:
- Validate the complete batch, generation, sequence, and known event fields.
- Require a leading reset on first attachment or a generation change.
- On reset, replace visible recent history, pending state, and live progress. Stage full active-output hydration before installing the replacement. Restore history and the captured prefixes before delivering later deltas. Clear partial arguments and transient text from the previous stream.
- Deliver all events in order. Same-generation replay cannot regress the sequence without a reset.
- Save generation and sequence together only after every callback succeeds.
EOF and transient failures retain the last consumed pair. Explicit recovery and cancellation clear it. A generation change with reset is ordinary recovery. A change without reset is a protocol failure. The client can attempt one cursor-free recovery. A second protocol failure is surfaced to the user. Reset history is authoritative for its covered window. Previously loaded older history remains accessible by durable positions and is deduplicated by entry ID. Reset replaces daemon-derived views. It preserves local drafts and unresolved creation or input handles, reconciling them only by matching identities.
Session events and progress #
Each event has type and data, its typed body. A published session event also
has sequence, its position in the generation. Control events reset and failure
have no sequence. Session identity is implicit in the subscribed URL. Events
within a batch are ordered. There is no ordering claim between streams belonging
to different sessions. A failure control appears alone, without a snapshot, and
terminates the stream even before attachment has succeeded. Clients never treat
it as a successful reset.
For example, an incremental batch appends text:
{
"generation": "J6kYj6IGcXyP3eMIp-WL3A",
"cursor": 43,
"events": [
{
"type": "text",
"sequence": 43,
"data": {"run_id": "run-1", "message_id": "message-1", "text": "Hello"}
}
]
}
Incremental event sequences increase contiguously from the requested cursor. The batch cursor is the last published event represented by the batch. Clients apply a batch atomically to local state or deduplicate already delivered events by generation and sequence. This prevents duplication when an earlier callback succeeds and a later callback fails before the batch cursor is saved.
SessionEvent in OpenAPI is the published event union. Control
events use the reset and failure schemas. Shell-command, side-question, kernel,
and glance updates are part of the current contract alongside text, progress,
and input outcomes.
The Go event decoder validates known variants. Human shell commands and side questions explain their identities and reconciliation rules.
Assistant text and reasoning are provisional until committed. Clients reconcile
completed entries by stable identity, including every bounded chunk of a long
provisional segment. Canonical text and thinking publication precedes its commit
marker. Clients replace provisional chunks together with that publication.
replaces_all_live also clears fragments omitted from bounded backfill after a
storage failure. Generation, model step, and attempt separate live identities.
Model retry can end an attempt without creating another user input. Family mail
events are durable notes with nullable
mail: { "mail_id": ..., "sender_session_id": ..., "receiver_session_id": ..., "kind": ..., "bytes": ... }.
Sender is null for external senders. Kind is task, message, result,
unreviewed, or webhook. Bytes count the UTF-8 message body. unreviewed is
an answer forwarded after a child ended without replying. A null sender also
includes a bounded sender_label, such as a hook name, at most 100 Unicode
scalar values and 400 UTF-8 bytes. The agent view animates these identities
without interpreting note text.
Progress identifies the call, its generating or running phase, and an intent derived from declared metadata or execution evidence. Unknown intent remains valid. The daemon does not parse Python to invent a label, and clients do not accumulate arguments to infer behavior.
Calls interleave by call_id. Identity changes across actor lifetimes, runs,
provider steps, retries, and output indexes. Preview updates replace the latest
window. offset_scalars counts decoded source Unicode scalars before that
window, including newlines. It does not count JSON escapes, bytes, grapheme
clusters, or terminal columns.
OpenAPI defines preview and event bounds. Excess generating calls disable previews for that attempt while execution continues. Full arguments and results remain in durable history.
First appearance and transition to running publish immediately. Other preview
updates coalesce over 100 ms. Attachment captures updates awaiting publication.
Completion, cancellation, failure, retry, and reset clear obsolete previews.
Argument parsing occurs once per provider fragment, before subscriber delivery.
Full tool arguments and results remain durable. Capability tool_progress: 1 is
required. There is no legacy client reconstruction.
Collection watch and overload #
http_events.gleam subscribes through
the bounded bus.
GET /sessions with Accept: text/event-stream uses the same scope filters as
the JSON collection, excluding pagination and sort. It sends invalidations, not
transcripts or duplicate full argument payloads. Its first batch contains
ready and reset, requiring an authoritative collection read. No cursor or
replay promise applies to this stream.
{
"events": [
{"type": "ready", "data": {}},
{"type": "reset", "data": {"reason": "initial"}}
]
}
An incremental batch contains invalidate events with resource URLs and
affected session IDs, plus bounded activity replacements for visible agents.
An activity event has this typed body:
{
"type": "activity",
"data": {
"session_id": "session-1",
"cursor": {"generation": "J6kYj6IGcXyP3eMIp-WL3A", "sequence": 10},
"status": {"phase": "idle", "run_id": null, "interrupt_requested": false, "blocking_reason": null},
"current_progress": [],
"activity": {
"lines": [],
"output_scalars": 0,
"output_utf8_bytes": 0,
"observed_at": "2026-10-02T14:00:00Z",
"latest_input": null,
"latest_answer": null
}
}
}
Status, current progress, activity, and cursor are captured together and replace
the row's live state together. The cursor matches the summary cursor. Separate
updates cannot share a cursor while replacing only one of those fields.
Collection mail events carry the same mail metadata as session notes, without
message text. Peer labels come from session summaries. Unknown peer IDs trigger
a metadata read. These animation events have no replay guarantee. Scope filters
cover both entry and removal, including a workspace change moving a row out of
the filter. The daemon invalidates the scope when it cannot resolve membership
cheaply or safely.
A client subscribes, waits for ready, then reads authoritative JSON pages. Changes during loading leave the view dirty and cause another refresh. Activity replacements arriving during that read are applied afterward by their per-session generation and sequence. Equal or older sequences cannot overwrite a newer row. An actor-generation mismatch requires refreshing that row. This yields a current view without claiming an atomic snapshot across actors. Reconnect always repeats the readiness and refresh flow.
The bus queue holds at most 256 events and 1 MiB per subscriber. Mailboxes carry at most one outstanding wake, never full payloads. Publication uses bounded nonblocking admission. Session streams read the existing replay buffer rather than maintaining additional payload queues. Flushes coalesce over 100 ms. Progress and display events have independent payload bounds.
At overflow, the collection stream emits overflow and closes if the socket can
still accept the signal. Closure alone also requires refresh. Delivery of the
final marker cannot be guaranteed to a stalled reader. The client refreshes by
resubscribing, waiting for ready, and then reading the authoritative tree,
status, progress, and glances. It does not append new state to an obsolete
graph. Disconnect and failed writes release the subscription and its queue.
Both stream kinds send keepalives at least every five seconds when quiet. Sockets have bounded write waits. Publication never awaits subscriber socket writes. A stalled reader cannot retain an unbounded mailbox or force another subscriber's writes to wait behind its own. Reverse proxies must pass streaming responses without buffering. History, images, and large extension results remain bounded HTTP reads, not unsolicited stream data.