LLM Streaming UX
Pathrule1 Rule • 2 Memories • 2 Skills
LLM streaming UX is a distributed state machine spanning provider events, server tools, transport, client rendering, cancellation, and persistence. This bundle defines typed events, message identity, commit boundaries, reconnect behavior, accessible updates, and adversarial stream tests. Unlike AI SDK, it owns product behavior under partial, failed, and resumed output rather than a specific streaming helper API.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
implement-streaming-ux
app/
api/
chat/
Stream typed events with stable identity and order
src/
ai/
Persistence follows semantic commit points
components/
chat/
The interface renders state, not transport activity
tests/
ai/
test-streaming-failures
Rules
1Stream typed events with stable identity and order/app/api/chathighstrictThe transport carries message, part, event, sequence, and terminal state instead of unframed text chunks.
| 1 | The transport carries message, part, event, sequence, and terminal state instead of unframed text chunks. Raw chunk concatenation cannot represent tool calls, citations, errors, refusal, usage, reconnect position, or duplicate delivery safely. Enforce this boundary in /app/api/chat so invalid work stops before it reaches another subsystem or creates an externally visible side effect. |
| 2 | |
| 3 | - Assign the assistant message and each content or tool part a stable server-generated identifier before streaming deltas. |
| 4 | - Use explicit event types for start, delta, tool state, metadata, error, canceled, and completed outcomes. |
| 5 | - Include a monotonic sequence or resumable cursor and make clients ignore already-applied events. |
| 6 | - Emit exactly one terminal outcome and close the stream after durable finalization or explicit failure. |
| 7 | |
| 8 | Verification: Duplicate, reorder, delay, and drop events around tool and terminal boundaries; confirm the client converges or reconnects without corrupting content or effects. |
Memories
2Persistence follows semantic commit points/src/aiA visible delta is not yet a completed message, a confirmed tool result, or a billable product outcome.
| 1 | A visible delta is not yet a completed message, a confirmed tool result, or a billable product outcome. Persist the message shell and event cursor early for recovery, but mark content and tool parts with explicit in-progress, failed, canceled, and complete states. |
| 2 | |
| 3 | Commit tool side effects through their own idempotent transaction before emitting a successful result. Finalize assistant content only after the terminal provider event and server validation. Keep partial output available for diagnostics or user recovery without presenting it as authoritative completion. Keep the decision explicit at /src/ai; moving it into an incidental caller makes behavior depend on which route happened to execute first. |
| 4 | |
| 5 | See /app/api/chat for event framing and /src/components/chat for state rendering. That related boundary consumes this decision and carries the evidence that proves it still holds. |
The interface renders state, not transport activity/src/components/chatChunk arrival rate is noisy and does not map directly to readable motion, focus, or trustworthy completion.
| 1 | Chunk arrival rate is noisy and does not map directly to readable motion, focus, or trustworthy completion. Buffer visual text updates to a stable cadence while applying semantic events such as tool start, approval, failure, and completion immediately. |
| 2 | |
| 3 | Keep focus under user control and announce meaningful state changes through a restrained live region. Show cancellation as an available action while work is active and a durable outcome after it wins the race. Preserve the message identity and visible partial state across reconnect instead of adding another message. Keep the decision explicit at /src/components/chat; moving it into an incidental caller makes behavior depend on which route happened to execute first. |
| 4 | |
| 5 | See /app/api/chat for terminal truth and the streaming UX test skill for degraded networks. That related boundary consumes this decision and carries the evidence that proves it still holds. |
Skills
2implement-streaming-ux/rootImplement an LLM streaming flow from typed server events through accessible client state and persistence.
| 1 | --- |
| 2 | name: implement-streaming-ux |
| 3 | description: Implement an LLM streaming flow from typed server events through accessible client state and persistence. |
| 4 | --- |
| 5 | |
| 6 | # Implement Streaming Ux |
| 7 | |
| 8 | Run this procedure whenever the governed surface changes or its operational evidence becomes stale. |
| 9 | |
| 10 | 1. Define the event union, message and part identifiers, sequence or cursor, terminal outcomes, and serialization tests before building the UI. |
| 11 | 2. Implement server production with cancellation propagation, idempotent tool effects, durable cursors, and one terminal transition. |
| 12 | 3. Build a client reducer that applies duplicate-safe events, batches text rendering, restores persisted state, and exposes retry or reconnect without new identities. |
| 13 | 4. Add accessible busy, tool, approval, error, canceled, and complete states; verify focus, reduced motion, copy, selection, and screen-reader announcements. |
| 14 | |
| 15 | Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory. |
test-streaming-failures/tests/aiTest partial, duplicated, reordered, disconnected, canceled, and failed LLM streams across server and client boundaries.
| 1 | --- |
| 2 | name: test-streaming-failures |
| 3 | description: Test partial, duplicated, reordered, disconnected, canceled, and failed LLM streams across server and client boundaries. |
| 4 | --- |
| 5 | |
| 6 | # Test Streaming Failures |
| 7 | |
| 8 | Run this procedure whenever the governed surface changes or its operational evidence becomes stale. |
| 9 | |
| 10 | 1. Create deterministic event fixtures with text, tool, metadata, refusal, usage, error, canceled, and completed events around every boundary. |
| 11 | 2. Inject duplicate, missing, delayed, and out-of-order delivery plus disconnect before and after tool commit and final persistence. |
| 12 | 3. Race user cancellation with provider completion and tool completion; confirm exactly one terminal state and no orphaned side effect. |
| 13 | 4. Reconnect from every cursor, reload the UI, and verify message identity, rendered content, accessibility state, stored status, and usage remain consistent. |
| 14 | |
| 15 | Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory. |
Why this pattern
Agents append raw text chunks until done, leaving tool states, partial persistence, reconnects, cancellations, duplicate events, and screen-reader updates undefined.
Built for Teams building chat, generation, or agent interfaces that render incremental model and tool output.
Keeps your assistant from:
- Duplicate or reordered chunks corrupting the visible message
- Canceled or failed output persisted as complete
- Reconnects rerunning tools or creating a second assistant message
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-08-25