Streaming

Documentation Index

Fetch the complete documentation index at: https://docs.second.so/llms.txt

Use this file to discover all available pages before exploring further.

​

The two-hop architecture

Agent Worker  →  Worker SSE  →  Next.js Bridge  →  AI SDK UIMessageStream  →  Browser (useChat)

​

What’s provider-specific vs. provider-agnostic

​

Runtime normalization

​

Worker SSE format (Hop 1) — Claude

data: {"type":"system","subtype":"init","session_id":"abc123"}
data: {"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}}
data: {"type":"stream_event","event":{"type":"content_block_start","content_block":{"type":"tool_use","name":"Bash","id":"tc_1"}}}
data: {"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{\"command\":\"ls\"}"}}}
data: {"type":"stream_event","event":{"type":"content_block_stop"}}
data: {"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tc_1","content":"file1.ts\nfile2.ts"}]}}
data: {"type":"assistant","message":{"content":[...]}}
data: {"type":"result","result":"Done."}
data: [DONE]

​

SDK message types

​

AI SDK UIMessageStream format (Hop 2) — all providers

data: {"type":"text-start","id":"txt_1"}
data: {"type":"text-delta","id":"txt_1","delta":"Hello, "}
data: {"type":"text-delta","id":"txt_1","delta":"let me check."}
data: {"type":"text-end","id":"txt_1"}
data: {"type":"tool-input-start","toolCallId":"tc_1","toolName":"Bash","dynamic":true}
data: {"type":"tool-input-delta","toolCallId":"tc_1","inputTextDelta":"{\"command\":\"ls\"}"}
data: {"type":"tool-input-available","toolCallId":"tc_1","toolName":"Bash","input":{"command":"ls"},"dynamic":true}
data: {"type":"tool-output-available","toolCallId":"tc_1","output":"file1.ts\nfile2.ts","dynamic":true}
data: {"type":"finish"}
data: [DONE]

​

Claude bridge translation rules

​

Dynamic tool parts

​

Builder run lifecycle

​

Frontend integration

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";

const { messages, sendMessage, status, resumeStream } = useChat({
  transport: new DefaultChatTransport({
    api: `/api/workspaces/${workspaceId}/apps/${appId}/runs/${runId}/chat`,
    prepareReconnectToStreamRequest: ({ api }) => ({ api: `${api}/stream` }),
  }),
  messages: initialMessages,
});

​

Resume behavior

1. Workspace realtime run events (run.starting, run.stream_ready)
2. Initial page load when the run is already streaming and persisted messages already exist (initialMessages.length > 0)
3. Browser back/forward restores where a no-store status check finds a streaming run even if the route props were stale

​

Multi-tab message sync

POST /chat handler → workspace event publish → shared workspace SSE → useRunSync hook → setMessages + resumeStream/replay

1. WorkspaceRealtimeProvider owns one shared GET /api/workspaces/[workspaceId]/events SSE connection around the workspace shell. The connection is shared across tabs with BroadcastChannel and Web Locks.
2. Builder run repository updates publish compact workspace events: run.starting, run.stream_ready, run.completed, and run.failed. The payload contains ids and status only, never prompts, source files, secrets, or full messages.
3. On connect or reconnect, the workspace events endpoint emits compact catch-up events for currently streaming runs so mounted tabs can recover if they missed the original publish.
4. AppChat owns useChat; useRunSync listens to the workspace realtime provider for events matching its { workspaceId, appId, runId }.
5. When a tab’s useRunSync hook receives run.starting or run.stream_ready and useChat status is "ready" (not already streaming/submitted), it:
   • Fetches the latest messages from GET .../chat
   • Calls setMessages() to update useChat’s state in-place (no component remount)
   • Calls resumeStream() to reconnect to the live Redis stream
6. When Tab B receives run.completed or run.failed (and is not already streaming), it fetches final messages and calls setMessages() to display the complete conversation.
7. When streaming ends after a sync-triggered resume, a final fetch ensures messages are complete (covers the case where completed was skipped because Tab B was mid-resume).

​

Race-condition hardening

• Pending-to-streaming claim: the server atomically claims a run before talking to the worker, so remounts during sandbox initialization cannot start a second worker query.
• Duplicate POST no-op: if a run is already streaming, the chat POST returns an empty successful stream instead of failing the UI or starting another query.
• Single resume owner: useChat no longer auto-resumes on mount via resume: true; useRunSync owns resume flow.
• Sender guard: local send paths set statusRef.current = "submitted" before calling sendMessage(...), preventing run-event handlers from racing the sender tab before React state commits.
• No clobber during local send: sync setMessages(...) updates are ignored while local status is "submitted"/"streaming", so optimistic local user messages are not overwritten by stale server snapshots.
• Initial prompt preflight: brand-new app pages verify the run is still pending and empty before auto-sending the stored app prompt. Cancelled preflight checks release their in-memory guard so route transitions and browser history can retry safely.
• Stale history POST guard: completed/failed runs can only be re-claimed when the posted message list is longer than the persisted one, so stale back/forward requests cannot replace a full conversation with the first message.
• Initial load guard for new runs: initial live sync runs only when runStatus === "streaming" and initialMessages.length > 0, preventing false “connecting” state on brand-new runs.
• Back/forward status check: restored app pages do a delayed no-store status read. If the server says the run is already streaming, the page hydrates the latest snapshot and enters the live-sync path even when route props were stale.
• Resume retry after 204: a 204 from GET .../chat/stream means “not attachable yet”, not “done”. While the run remains streaming, the polling fallback keeps retrying the real stream attach so browser forward does not wait for final persistence.
• Replay buffer fallback: UI stream chunks are captured in Redis with ordered sequence numbers and terminal state. A reconnecting tab can catch up from replay and then follow live chunks even if the resumable-stream instance is unavailable.
• Unmount-safe POST: route changes do not abort the active chat POST, so browser back/forward can reconnect to the same run instead of terminating it.
• Optimistic sidebar app entry: app creation updates the mounted sidebar via a local event before navigation. This avoids a post-navigation router.refresh() that could interrupt first-mount chat initialization.
• Shared events connection: workspace lifecycle events and app data streams are shared across tabs with BroadcastChannel + Web Locks when available, so many tabs do not exhaust the browser’s per-origin HTTP connection budget.
• Interruptible rendering: message rendering uses deferred values and throttled stream updates so navigation remains responsive during long streams.

​

Rendering

​

AI Element components

​

code-block.tsx

• Composer-style card (--composer-bg, --composer-shadow, rounded-2xl)
• Language icon per file type (terminal for bash/sh, braces for JS/TS, JSON icon, globe for HTML, etc.) + language label
• Syntax highlighting via sugar-high (3KB, zero-dep, no async/WASM)
• Copy-to-clipboard button with hover state
• Light/dark theme aware — uses --sh-* CSS variables from globals.css

​

reasoning.tsx

• Auto-opens when isStreaming becomes true
• Uses part state from the AI SDK to label active vs finished reasoning
• Falls back to message position when older persisted messages do not have a precise reasoning state
• User can manually toggle at any time

​

plan-card.tsx

• Overview — high-level summary paragraph
• Main Features — flat list with name + description per feature
• Data Flow — how data moves through the app
• Agents / Backend — side-by-side sections, showing “Not available” badge when null
• Actions — “Approve & Build” and “Request Changes” buttons (always visible, disabled during streaming). Skeleton placeholders shown while tool input streams.

​

terminal.tsx

• Traffic light dots (red/yellow/green) in the header
• Command with $ prefix in green (emerald for light mode, green-400 for dark)
• Scrollable output area (max 192px)
• Green checkmark when done, spinner while running, copy button next to command
• Light/dark theme aware — white bg in light mode, dark in dark mode

​

tool-card.tsx

• Write — FilePlusIcon + filename + “Created” + green +N stats. Collapsible: expands to show a GitHub-style diff (all lines green for new files).
• Edit — FilePenLineIcon + filename + “Edited” + colored +N -N stats. Collapsible: expands to show red (deleted) and green (added) lines. Diff is computed from the tool’s old_string/new_string input.
• Read — FileSearchIcon + filename for one file. Multi-file reads show Read N files as a closed-by-default collapsible list of the exact file paths.
• List — FolderSearchIcon + folder path for one location. Multi-location lists show Listed N locations as a closed-by-default collapsible list of the exact paths.
• Glob — FolderSearchIcon + pattern. Simple one-liner.
• Grep — SearchIcon + pattern. Simple one-liner.
• WebSearch — GlobeIcon + query. With fewer than 3 results: inline source chips with favicons. With 3+ results: stacked overlapping favicon circles + “N sources”, collapsible to show all source chips.
• WebFetch — GlobeIcon + hostname + “Fetched” + clickable source chip with favicon.

​

custom-tool-card.tsx

• Integration name and favicon from tool.integration
• Action label from tool.displayName, falling back to a title-cased tool name
• HTTP method and endpoint host from tool.endpoint
• Expandable Input and Output panels with parsed JSON formatting. If the worker returns mock data or an error preface before a JSON payload, the card keeps the note and formats the payload separately.

​

Architecture

useChat → messages[].parts[] → part.type switch → AI Element component

​

Scroll behavior

┌─ relative container (flex-1) ──────────────┐
│ ┌─ absolute inset-0 ────────────────────┐  │
│ │ StickToBottom (messages, pb-48)       │  │
│ └───────────────────────────────────────┘  │
│ ┌─ absolute bottom-0 z-20 ─────────────┐  │
│ │ Composer input (pointer-events-auto)  │  │
│ └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

​

API routes

​

POST /api/workspaces/[workspaceId]/apps/[appId]/runs/[runId]/chat

1. Authenticates the request and loads the app + run by { workspaceId, appId, runId }.
2. Atomically marks the run as streaming. The claim succeeds only for pending runs or legitimate follow-up messages with a longer message list. If the claim fails because another request already started the run, or because a stale browser history request posted old messages, returns an empty successful stream.
3. Creates a UIMessageStream with the bridge in the execute callback.
4. The SSE stream is tee’d via consumeSseStream, registered in Redis, saved to the run as activeStreamId, and captured into the run replay buffer.
5. After the bridge finishes, fetches the session file from the worker and saves it to MongoDB for cross-container resume.
6. On finish, persists the final messages to MongoDB via completeRun.

​

GET /api/workspaces/[workspaceId]/apps/[appId]/runs/[runId]/chat

​

GET .../chat/stream

1. Loads the run’s activeStreamId and status from MongoDB.
2. If the run is streaming but not attachable yet, waits briefly for Redis run events before deciding.
3. If no active stream or run is completed/failed, returns 204 (no content).
4. If replay chunks exist, returns a replay/follow SSE stream. The optional cursor query parameter skips chunks the client already saw.
5. If replay is not available, creates a ResumableStreamContext with Redis pub/sub and calls resumeExistingStream.
6. Returns the resumed stream as SSE with x-vercel-ai-ui-message-stream: v1 header.

​

GET /api/workspaces/[workspaceId]/events

​

Persistence

1. Run is created as pending with empty messages.
2. User sends a message → chat POST saves the optimistic UIMessage[] and marks the run as streaming.
3. Agent streams its response → the SSE stream is tee’d via consumeSseStream, published to Redis for multi-client resume, and captured in a Redis replay buffer. The activeStreamId is saved to the run document.
4. Agent finishes → the bridge fetches provider-aware session state from the worker.
5. onFinish saves the latest provider session state under both sessionState and runtimeSessionStates.<runtimeId>, records how many persisted UI messages that native session covers, then completeRun saves the full UIMessage[] array, clears activeStreamId, and marks the run as "completed".

​

Cross-container resume

1. The chat route loads the selected runtime’s entry from runtimeSessionStates, falling back to sessionState when it belongs to the selected runtime.
2. The session state is passed to the worker request.
3. Claude restores JSONL state when needed; Codex CLI and OpenCode receive their native session IDs when available.
4. The runtime adapter resumes the provider session and streams normalized events.