docs(stream): explain generation-bound replay
Two cursor values, one checkpoint. Document resets and reconnects for client authors.
15 unmodified lines161718192021222320212223242526272829303132333435363727282938394041424344454636 unmodified lines15 unmodified lines
## Stream failures and recovery
Session streams require the `text/event-stream` content type. Each batch carriesa nonnegative integer cursor and an event array. The CLI validates the wholebatch before consuming it and advances the cursor only after every callbacksucceeds. Unknown event kinds are ignored;missing kinds and malformed known events are protocol failures.a nonempty `generation`, a nonnegative integer `cursor`, and an `events` array.The generation identifies one lifetime of the session actor. Reconnect requestssend both `after_generation` and `after_seq`; an initial request omits both.A missing or different generation, or a sequence outside the replay window,returns a durable transcript reset. Empty keepalive batches carry the currentpair too.
The CLI validates the whole batch before consuming it and saves both cursorvalues only after every callback succeeds. Initial attachment and a generationchange require a leading reset. Within one generation, the sequence cannotdecrease without a reset. A generation change with a reset is normal recovery.A change without a reset is a protocol failure. The reset replaces visiblehistory and clears partial tool arguments. Older-history navigation continuesto use transcript row IDs. Unknown event kinds are ignored.Missing kinds and malformed known events are protocol failures.
Transport failures, ordinary EOF, HTTP 408/429, and server errors reconnect witha delay starting at 500 milliseconds and increasing to at most five seconds.Cancellation ends the subscription quietly. Other HTTP refusals, explicit SSEfailures, and consumer callback failures end it with a visible notice. A terminalfailure also stops status polling for that attachment.EOF and transient failures retain the saved pair. Cancellation ends thesubscription quietly and clears the pair, as does explicit protocol recovery.Other HTTP refusals, explicit SSE failures, and consumer callback failures endthe subscription with a visible notice. A terminal failure also stops statuspolling for that attachment.
The TUI attempts one durable transcript reset per attachment after a protocolfailure. It clears partial tool arguments and requires the recovery stream tobegin with a reset. A second protocol failure ends automatic recovery; reopening36 unmodified lines