# HTTP streams and recovery This reference describes session replay and collection invalidations. [OpenAPI](openapi.yaml) defines event variants and payload bounds. [HTTP API behavior](http-api-design.md) defines common HTTP rules. ## Session watch [`http_session_stream.gleam`](../src/albedo/daemon/http_session_stream.gleam) owns HTTP attachment. The [session actor](../src/albedo/daemon/session.gleam) 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. ```json { "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](openapi.yaml). 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: 1. Validate the complete batch, generation, sequence, and known event fields. 2. Require a leading reset on first attachment or a generation change. 3. 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. 4. Deliver all events in order. Same-generation replay cannot regress the sequence without a reset. 5. 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: ```json { "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](openapi.yaml) 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](../cli/internal/daemon/session_events.go) validates known variants. [Human shell commands](http-sessions.md#human-shell-commands) and [side questions](http-sessions.md#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`](../src/albedo/daemon/http_events.gleam) subscribes through the bounded [bus](../src/albedo/daemon/bus.gleam). `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. ```json { "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: ```json { "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. ## Related guides - [API overview](http-api-design.md) - [Session lifecycle and recovery](http-sessions.md) - [Extension HTTP behavior](http-extensions.md) - [Change the HTTP API](contributing-api.md)