The stream contract

[claude]

Question

How does an answer get from the server to a browser, live, to however many clients are watching?

Provider seam design already fixed what the loop produces: an AsyncIterable normalizing to delta / done{usage} / error{kind}, where transient errors retry internally and auth/refusal surface immediately. App shell and stack carried that to the renderer over Electron IPC — a single consumer on the same machine, with no connection to lose. Neither assumption holds now.

Blocked on The answer log, which fixes what a joining client can be handed.

Decide:

• Transport. Server-Sent Events or WebSocket. SSE is one-directional, reconnects for free with Last-Event-ID, and survives proxies; WebSocket costs more but is needed if a client ever sends anything upstream — which turns on whether The control surface puts controls in the client. Decide the transport and say what would force the other choice.
• The event vocabulary. How Provider seam design #5's delta/done/error map onto the wire, plus whatever the client needs that the seam doesn't emit: a new-answer boundary, the interrupt-and-replace signal from The output window, and the loop's own state — Cost control's status-pill vocabulary (throttled, paused (budget), paused (runaway guard)) has to reach the client somehow.
• What a joining client receives. The settled constraint is that it loads previously logged answers. Decide how many, in what order, and how the boundary between replayed history and the live stream is marked — including the case where a client joins mid-answer, with a partial answer already streaming.
• Fan-out. N simultaneous clients on one loop. Whether they all see identical state, what a slow or wedged client costs the others, and backpressure — the loop must not stall because a phone went to sleep.
• Reconnect and resume. What a client does after a dropped connection, whether it resumes from a cursor or refetches, and how it avoids re-rendering an answer it already has.
• Idle behaviour. Keepalives, and what the server does with a connection that's been silent for hours — a phone on a lock screen is the normal case, not the edge case.

Deliverable: the wire protocol — transport, event shape, connect/replay/resume semantics, and fan-out rules — specific enough that The web client can be built against it without further decisions.

---

Generated by Claude Code

[jpka]

Map update — trigger is now manual, not automatic. The map's Trigger constraint changed: the user clicks a "solve now" button in the web client instead of an interval + change-detection loop. This settles, as a fact this ticket inherits rather than decides, that the client sends at least one command upstream — the Transport bullet's "needed if a client ever sends anything upstream, which turns on whether The control surface puts controls in the client" is no longer conditional on that ticket's outcome; it's already true. This doesn't by itself force WebSocket over SSE (a solve-now trigger could be a small out-of-band request rather than sharing the answer-stream socket), but decide the transport with that constraint already in hand rather than as an open unknown. See Screen Solver's updated Notes table.

[jpka]

Decided. Transport is SSE for the live answer stream, plus a separate POST /solve for the trigger — not one WebSocket carrying everything. The traffic pattern is one-directional broadcast (server pushes deltas to N passive viewers) plus occasional discrete commands, which SSE plus plain HTTP handles without the extra bidirectional-connection machinery a WebSocket would add.

Endpoints:

• POST /solve — the "solve now" trigger. Always accepted, always interrupts whatever solve is currently in flight (no 409 Busy — matches The output window's interrupt-and-replace behavior directly). Returns 202 Accepted immediately after only synchronous, immediately-knowable validation (400 if no capture window is configured, 503 if the host isn't ready). Everything that only becomes knowable once the provider call is underway — rate limit, refusal, the in-prompt bail token — flows through the stream, never the POST's response body.
• GET /answers — backlog. Plain REST endpoint returning the full answers.jsonl contents as a JSON array, in order. Fetched once by the client on page load, separate from the live connection. Kept separate rather than replayed over SSE because conflating "hydrate history" with "watch what happens next" would force a replay-vs-live distinction into the event shape for no benefit — matches The output window's focus-pane-plus-history-drawer split, which already treats history as its own UI area.
• GET /events (SSE, text/event-stream) — one shared broadcast. Every connected client (desktop, phone, however many) receives the identical live event sequence; no per-client filtering, no auth (consistent with Reach and trust being out of scope).

Named SSE events (native event:/data: framing, not a single generic type with a JSON discriminator — lets the client addEventListener per type directly):

• start — a new solve began. No title in the payload (the title is the model's own # heading, streamed as text, per Solve-call prompt design). Client resets to a fresh empty pane; if the previous pane wasn't already done, its content is pushed to history tagged interrupted.
• delta — {text}, a text chunk.
• done — {usage}.
• error — {kind}.
• sync — {text}, the accumulated text of the currently in-flight solve. Sent only to a connection that opens while a solve is already mid-stream, in place of start — this is how a late-joining phone catches the partial answer instead of sitting blank until the next done. The server holds the current in-flight accumulated text in memory to make this possible, which it already effectively needs per The answer log's "written once at the terminal event" model.

Reconnection falls out for free. EventSource auto-reconnects on drop by design, and a reconnect is indistinguishable from a fresh mid-flight join from the server's point of view — so the sync mechanism handles both cases with no Last-Event-ID replay logic needed.

Closes half of the map's "watching away from the host" fog. A connection sitting between a start (or sync) and the matching done is the "actively solving" indicator for any client that can't see the host's yellow WGC border — this is what a phone across the room gets instead of the border. The other half of that fog — pause/resume, settings, anything else client-controllable — is The control surface's to decide.

Not decided here: whether POST /solve, GET /answers, and GET /events sit behind any additional client-facing affordance (e.g. how the web client itself is served, same-origin static files vs. separate origin) — that's The web client's territory, now unblocked. Detailed error-surface taxonomy for the error{kind} payload's possible values is Failure and edge-case behavior's territory, still blocked on The control surface.

[jpka]

Resolved — see decision comment above.