Implement a streaming state reducer

Each server event carries a run ID and a one-based sequence number. A delta event appends text, done marks a complete answer, and error ends the run with a safe error message. The sequence covers every persisted event for that run, so a client can tell a replay from a gap.

The client starts a run through a local action. It accepts only events that belong to the active run and requires contiguous sequence numbers. An event that was already applied is ignored, and a gap marks the response interrupted rather than silently losing text.

The duplicate rule assumes the payload for a sequence number never changes; two different payloads under one number are a protocol violation for server-side integrity checks to catch.

Local Stop means the client stopped this attempt. It does not assert that the server cancelled every operation. A separate reconciliation step can later update the persisted run record from authoritative server state.

The reducer receives the current state and one action and returns the next state. It is pure: no clock, no network, and no mutation of its inputs. It never throws: a bad sequence number becomes a failed state, not an exception. When an action changes nothing it returns the same state object, so useReducer can skip the re-render; any change returns a new object with exactly the five fields runId, status, text, lastSeq, and error.

type Status = "idle" | "streaming" | "complete" | "interrupted" | "stopped" | "failed";
type State = {
  runId: string | null;
  status: Status;
  text: string;
  lastSeq: number;
  error: string | null;
};
// seq is untrusted network data: the reducer validates it before use (rule 4).
type ServerEvent = { runId: string; seq: unknown } & (
  | { type: "delta"; text: string }
  | { type: "done" }
  | { type: "error"; message: string }
);
type Action =
  | { type: "start"; runId: string }
  | { type: "stop"; runId: string }
  | { type: "disconnect"; runId: string }
  | { type: "event"; event: ServerEvent };

const initialState: State = {
  runId: null, status: "idle", text: "", lastSeq: 0, error: null
};

declare function reduceStream(state: State, action: Action): State;

Apply these rules in order; the first one that matches decides the result.

1. start returns a fresh streaming state for its run, { runId, status: "streaming", text: "", lastSeq: 0, error: null }, whatever the current state.
2. Any other action whose run ID differs from state.runId, or any other action while status is not "streaming", returns the same state object. Complete, interrupted, stopped, and failed are therefore sticky until the next start.
3. stop sets status "stopped", and disconnect sets "interrupted". Text, lastSeq, and error are kept.
4. An event whose seq is not a safe integer of at least 1 sets status "failed" with error "Invalid event sequence".
5. An event with seq <= lastSeq was already applied: return the same state object, not an equal copy.
6. An event with seq !== lastSeq + 1 sets status "interrupted" with error "Missing event", keeping text and lastSeq.
7. Otherwise apply the event and set lastSeq to its seq: delta appends its text, done sets "complete", and error sets "failed" with the event's message as the error.

A gap ends live accumulation on purpose. Reconnecting needs a separate snapshot or resume operation (the Hard question in this topic), not more events sent into an interrupted state.

The Python version is reduce_stream(state, action) on dictionaries, with run_id and last_seq in place of runId and lastSeq. Everything else, including the status and error strings, is identical. In Python, seq must be an int that is not a bool, from 1 to 2**53 - 1.

A fetch response body supplies bytes. Decode them incrementally with TextDecoderStream or one persistent TextDecoder called with { stream: true }. A multibyte character may span two reads, so decoding each read on its own can corrupt text.

Then parse the application framing. For newline-delimited JSON, keep the unfinished line between reads and parse only complete frames. For server-sent events, use an SSE parser that follows its field and event rules. Splitting on whatever boundary a read happens to end at is not enough.

Set maximum event and buffer sizes, validate every parsed object, and reject unsupported protocol versions. A frame that never completes must not grow memory without bound. A heartbeat is transport metadata: it should not append text or create a gap in the persisted content-event sequence.

Create an AbortController for each run. Dispatch start once the backend has accepted the request and assigned its run identity. Pass the signal to fetch, check response.ok and the expected content type, then consume and validate frames.

Dispatch each validated event with its run ID. If the reader reaches the end of the stream while the run is still streaming and no terminal event was observed, dispatch disconnect. Catch an abort separately from other errors so a user's Stop is not presented as an outage.

In React, start the run from a user action or a carefully managed effect. Cleanup should abort the old reader on unmount or replacement. Development-mode effect re-runs can expose duplicate-start bugs, so use server-side request idempotency when a repeated submission would be costly.

Use reducer dispatch or functional updates for incremental text. Appending to a text value captured inside a long-lived callback can overwrite newer chunks.

Associate each controller with its run ID. Pressing Stop for R1 must not abort R2 because a shared variable was replaced. The reducer's identity check protects state, but the transport layer must also cancel the right request.

When an old catch or finally handler runs, it should update only its own run. A generic setLoading(false) in an outdated request can hide the loading indicator of the current one.

Updating React state for every small delta can create unnecessary work. Batch deltas over a short interval or an animation frame when needed, then flush pending text before processing done, error, or stop.

Keep event accounting separate from render batching. If several deltas are combined for display, keep the sequence cursor of the last applied event so a replay does not duplicate content.

Cap message size, and measure responsiveness before adding complexity: Markdown parsing and syntax highlighting can cost more than the text-state update itself.

After an interruption, keep the partial answer with a clear label. If the server supports status lookup, query the original run before creating a new generation: it may already have completed and stored the final result.

A new attempt receives a new run identity and its own UI treatment. Do not concatenate it onto the old partial answer. Keep the user's input so they can retry without retyping.

A server-side tool action may have completed even if the answer stream failed. Fetch authoritative operation state or resume the same durable run rather than replaying side effects.

Use a dedicated status region for changes such as generating, interrupted, and complete. Keep the streamed transcript readable without announcing every delta. Preserve keyboard focus, and let the user control scrolling while reading earlier messages.

Render untrusted output with a safe Markdown configuration and explicit link behavior. Keep citation metadata separate from text until references can be resolved, and show unresolved references as pending or unavailable according to the UI contract.

Test the complete flow with a keyboard and a screen reader. An aria-live attribute alone does not establish that the interaction is usable.

The reducer tests cover state transitions. Add transport tests that split JSON and UTF-8 across arbitrary reads, combine several frames in one read, omit the terminal event, and send malformed or oversized data.

Add UI tests for rapid submit, stop, and resubmit, unmount during generation, empty output, a partial error, and a terminal event arriving before a render batch flushes. Confirm that the controller aborts the intended request.

Use a local fake streaming server or a controlled reader fixture. You do not need a paid provider to reproduce these integration failures.