Data structure: Map<number, ServerMessage> (the ReorderBuffer class)
I chose a Map keyed by seq because it provides O(1) insertion and lookup, which is critical when tokens arrive every 30ms and we need to buffer out-of-order messages without jank.
The buffer maintains a nextExpectedSeq counter. When a message arrives:
- If
seq < nextExpectedSeq, it's a duplicate — silently dropped. - If
seq === nextExpectedSeq, it's emitted immediately, then we flush any contiguous buffered messages fromnextExpectedSeq+1upward. - If
seq > nextExpectedSeq, it's out of order — stored in the map until the gap is filled.
This approach handles:
- Gaps: If seq 5 arrives before seq 4, seq 5 is buffered. When seq 4 arrives, both are emitted in order.
- Duplicates: Direct seq comparison against
nextExpectedSeqand the map means duplicates never double-emit. - Chaos reordering: The buffer size (max 200) handles worst-case out-of-ordering since seq values grow linearly with message count; a full buffer is a protocol violation scenario.
Alternative considered: Pushing everything into an array and sorting by seq on each tick. Rejected because that would be O(n log n) on every token arrival. At 30+ events/sec, that's measurable jank.
Strategy: Block-level rendering with deterministic dimensions
The tool card rendering follows these principles:
- Streaming text renders as
white-space: pre-wrapinside a block element. The text grows downward naturally. When aTOOL_CALLarrives, the current text is frozen in place — no reflow happens because the text elements are already laid out. - Tool cards are rendered below the text in the same message bubble, as stacked block elements within a
toolCallStackgrid container. Since the streaming text is a block and the tool card is a block below it, the card pushes subsequent content down without affecting the text's position. - The streaming cursor is a single
▊character rendered asdisplay: inline-blockwithanimation: blink 1s. It occupies exactly one character width, so its appearance/disappearance doesn't cause reflow. This is critical — a::afterpseudo-element or absolute-positioned cursor would require more careful management. - No height animations or transitions. The tool card appears immediately (no CSS transitions from
height: 0toheight: auto, which would cause layout shifts). It just appears as a new block element in the flow.
Tool call → Tool result transition: The card starts with toolCardPending class (amber left border, "Running..." status). When TOOL_RESULT arrives, it transitions to toolCardResult (green border, "Complete" status, result JSON shown). The card element stays in the same DOM position throughout — no removal/reinsertion, no layout shift.
Tracking "consumed" vs "received":
The key insight is that WebSocketManager.processedSeq tracks the highest seq that has been rendered to the DOM, not just received over the socket. Here's how it works:
- When the WebSocket receives a message, it goes through the
ReorderBufferfirst (for ordering/dedup). - Ordered messages are processed by
processMessage(), which updates refs (not React state). - Periodically (
flushState()), refs are copied to React state to trigger re-renders. - Only when each server message is fully processed does
setProcessedSeq()update the WebSocketManager'sprocessedSeq(updated per-message, not only atSTREAM_END, so mid-stream reconnect sends a correctRESUME).
On reconnection:
WebSocketManager.onopendetects thatprocessedSeq > 0(meaning there was previous state).- It immediately sends
RESUME { last_seq: processedSeq }as the first message on the new connection. - The server replays all events after that seq.
- Replayed events go through the same
ReorderBuffer→processMessagepipeline, which deduplicates against already-rendered content.
Mid-tool-call recovery: If the connection drops after TOOL_CALL but before TOOL_RESULT:
- The tool card stays visible with "Running..." state (it's in the React state from the last flush).
- When the connection resumes, the server replays from the last processed seq (which was before the tool call if it wasn't fully acknowledged, or after it if
TOOL_ACKwas sent). - If the
TOOL_RESULTis replayed, the card updates to show the result. - The tool card's
useEffectonly sendsTOOL_ACKonce (guarded byackSentref), so replayed tool calls won't double-ACK.
If this needed to handle 50 concurrent agent streams on one screen:
-
Virtualized rendering: Currently,
messageListrenders every message. At 50 streams, that's hundreds of simultaneous messages. We'd use a virtual list (e.g.,react-windowor@tanstack/virtual) to render only visible messages. -
Per-stream WebSocket managers: Each agent stream would get its own
WebSocketManagerinstance, with its ownReorderBufferand seq tracking. TheuseAgentConsolehook would become a collection of hooks (one per stream), or a single hook managing aMap<streamId, StreamState>. -
Dedicated trace timeline per stream: The current single timeline would become per-stream, or a combined timeline with streamId as a filter dimension. Each timeline would use virtualized rendering internally.
-
Shared context inspector with stream selector: The context panel would show which stream's context is being inspected, with a selector to switch between streams. Memory would be bounded by keeping only the last N snapshots per stream.
-
Throttled state flushes: With 50 streams, each emitting 30+ events/sec, flushing to React state on every message would saturate the render thread. We'd use a shared flush scheduler that coalesces updates and flushes on
requestAnimationFrame(max 60 flushes/sec total, not per stream). -
Worker for reordering/diffing: The
ReorderBufferandcomputeDiffoperations would be offloaded to a Web Worker to avoid blocking the main thread. PostMessage would deliver ordered messages and diff results to the React renderer.
If responses were 100x longer (full documents, not chat):
-
Lazy text rendering: Instead of appending all tokens to a single string, we'd render text as a list of "chunks" (e.g., 100-token batches). The initial render shows the first batch, with subsequent batches rendered as they arrive. This prevents a single massive DOM text node from causing layout slowdowns.
-
Virtualized document view: The document would render in a virtual scroller, showing only the visible portion. As the user scrolls, more chunks are materialized into the DOM. This is the standard approach for long documents (like Google Docs' rendering).
-
Streaming to disk-backed storage: Accumulating 100x the token count in memory would be unsustainable. We'd write completed chunks to IndexedDB (or a shared worker's storage), keeping only the most recent ~500 tokens in memory for immediate display. The user can scroll back, triggering a load from IndexedDB.
-
Throttled context diff: For context snapshots that could be proportionally larger, we'd limit diff computation to only the keys visible in the collapsed tree view (deferring deep diffs until the user expands a node). This avoids the O(n) traversal of the entire object on every snapshot.
-
Incremental trace timeline: The trace timeline would cap visible events (e.g., last 1000 events) with a "load earlier" button, similar to how Chrome DevTools Network tab handles many requests.
The TOOL_ACK timeout creates a race condition: The server waits 5 seconds for a TOOL_ACK before sending TOOL_RESULT anyway. But if the network is slow or the client's render cycle is deferred (e.g., the browser tab was backgrounded), the TOOL_ACK might arrive after the timeout fires.
In this case:
- The server logs a violation for late
TOOL_ACK. - The server sends
TOOL_RESULTanyway. - The client processes the result normally.
The race condition means a client can be protocol-compliant in intent (it did acknowledge) but still get flagged for a violation (the ACK arrived late). The mitigation is to send TOOL_ACK immediately when the tool call is received (not when it's rendered), using a setTimeout(0) or similar to defer the render but send the ACK synchronously. However, the assignment spec says "when the client has rendered a tool call card", so the client must render first. This tension is inherent in the protocol.
A socket drop must not terminate an unfinished script. Replaying only the prefix leaves clients waiting for a STREAM_END that was never generated. The mock server now pauses the existing script until a replacement socket sends RESUME, replays history after last_seq, and then continues the same script and stream ID. The client can resume from zero if the first frame was lost. Waiting for reconnection is abortable by a new turn or reset, and bounded to 90 seconds.
Tool ACK tracking is installed before delivery (including replay), with its five-second timeout armed after delivery. This accepts an immediate ACK without charging injected latency against the client. Sequence ordering and deduplication remain in the client's ReorderBuffer. A reset/new turn aborts old work; an old script's finally block cannot clear the new script's controller.
The verifier requires the requested server mode, retains logs before each reset, and exits nonzero for any failed scenario, including a timeout. Successful later scenarios can no longer hide an earlier failure.