End-to-End Coordination

Why this page exists

The previous five pages are split by side — four on the send side, one on the receive side. But the most painful real-world issues are vertical, cutting across both sides — “what actually happens between click and DOM update”, “why did the client stop but the server is still burning tokens”, “how does resume really land in production”. None of the five pages answers these completely on its own.

This page stitches the five together into an end-to-end view:

• The full call chain of a single sendMessage (client + server + transport)
• Every UIMessageChunk type’s meaning and trigger (the single source of truth for the wire protocol)
• Three genuinely two-sided protocols — abort / resume / error — that cannot be debugged from one side only

Nothing from the first five pages is repeated; this page only covers “how the pieces fit together”.

The full round-trip of one sendMessage

Starting from the most common scenario: the user types in a textarea and clicks submit. Below is the complete call chain from click to DOM update.

Where each hop lives in the source:

UIMessageChunk full-type reference

This is the only wire protocol between client and server — every SSE frame parses into one of these types. The complete union is at [email protected]/dist/index.d.ts:2158-2273.

Grouped by role (7 groups):

1. Stream lifecycle control

2. Text content

Same id for start/delta/end = one text segment. Different ids = different segments (e.g. model emits a text block → calls a tool → emits another text block = two text parts with different ids).

3. Reasoning / Thinking

4. Tool calls

dynamic-tool variants: if the tool is runtime-discovered (MCP / dynamic registration), the chunk carries dynamic: true, and the client should render it as a DynamicToolUIPart (type: 'dynamic-tool') rather than the static tool-${name} form.

5. Sources / Files

6. Custom business events

{
  type: `data-${string}`;   // e.g. data-progress, data-todos-update, data-run-init
  data: unknown;            // business-layer-defined shape
  id?: string;
  transient?: boolean;      // true = client only sees it in onData, not written to message.parts
}

Full detail of this protocol: UI Stream Orchestration → Custom data-* event protocol and useChat → onData.

7. Message-level metadata

Cheat sheet

A total of 25 types (counting data-${string} as one):

Bidirectional abort — the easiest hop to drop

The user clicks stop, or closes the tab, or their network drops. That signal must propagate all the way from client through server to LLM provider. Drop any single hop and you get:

• Client says “stopped”, but the server is still burning tokens
• LLM call completes and writes to DB, but the user is already gone
• Long tool operations (shell commands, HTTP requests) can’t be aborted

The full four-hop chain:

Dropping each hop: symptoms

Correct template (Hono)

import { convertToModelMessages, streamText } from "ai";
import { Hono } from "hono";

app.post("/api/chat", async (c) => {
  const { messages } = await c.req.json();

  const result = streamText({
    model,
    messages: await convertToModelMessages(messages),
    tools,
    abortSignal: c.req.raw.signal, // ← Key: Hono's raw request carries the signal
    // tool execute signatures MUST accept { abortSignal } and forward to downstream fetch / subprocess
  });

  return result.toUIMessageStreamResponse();
});

Correct template (Next.js Route Handler)

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model,
    messages: await convertToModelMessages(messages),
    tools,
    abortSignal: req.signal, // ← Key
  });

  return result.toUIMessageStreamResponse();
}

Tool-internal abort convention

const searchTool = tool({
  description: "...",
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ query }, { abortSignal }) => {
    const res = await fetch(`https://api.example.com/search?q=${query}`, {
      signal: abortSignal, // ← This line, so long fetches can be aborted
    });
    return res.json();
  },
});

End-to-end resume implementation

The useChat page covered the one-line client side (resume: true); the server side is where the real work lives. This section gives the full two-sided pattern.

Core constraints

1. Chunks must be replayable: on reconnect, all previously emitted chunks must be re-sent, then new chunks continue. This requires the server to buffer as it generates.
2. Chat id must be stable: the client’s useChat({ id }) on re-mount must pass the same id, or the server won’t find the buffer.
3. Storage must be cross-process visible: a single-process in-memory buffer handles only single-worker reconnect; multi-worker deployments or pod restarts lose state — production uses Redis stream / Pub-Sub.

Client behavior

useChat({
  id: chatId, // stable, derived from URL / props
  resume: true, // on mount auto-calls transport.reconnectToStream({ chatId })
});

DefaultChatTransport.reconnectToStream POSTs to ${api}?chatId={id}. If it returns null or an empty stream, client enters ready, no replay; if it returns a non-empty stream, client consumes it like a normal stream.

Server implementation (Redis Stream approach)

Pseudocode, core idea:

// POST /api/chat — new conversation
app.post("/api/chat", async (c) => {
  const body = await c.req.json();
  const chatId = body.id;

  const result = streamText({...});
  const uiStream = result.toUIMessageStream();

  // Key: tee one copy into Redis, return the other to the client
  const [forClient, forBuffer] = uiStream.tee();

  // Asynchronously write each chunk of forBuffer into Redis stream (keyed by chatId)
  ctx.waitUntil(writeStreamToRedis(chatId, forBuffer));

  return new Response(forClient, { headers: sseHeaders });
});

// POST /api/chat?chatId=xxx — reconnect
app.post("/api/chat", async (c) => {
  const reconnectId = c.req.query("chatId");
  if (reconnectId) {
    // Query Redis; if the stream exists, return (replay existing + subscribe to new)
    const bufferedStream = await readStreamFromRedis(reconnectId);
    if (bufferedStream) {
      return new Response(bufferedStream, { headers: sseHeaders });
    }
    // Stream completed or doesn't exist → return empty, client returns to ready
    return new Response(null, { status: 204 });
  }
  // ... normal new-conversation path
});

Idempotency

• Each chunk on the server can carry an auto-incrementing seq number (Redis XADD’s native id field works)
• On reconnect, client passes the last received seq (?chatId=xxx&lastSeq=42)
• Server replays only seq > lastSeq
• This avoids double-applying text-delta on reconnect (text-delta is incremental — replaying twice doubles the content)

DefaultChatTransport’s default implementation does not auto-dedupe by seq — exact dedup requires custom prepareReconnectToStreamRequest coordinated with the server route. For most cases: agent step loops produce full text-start → text-delta → text-end blocks per step; persist after text-end, and the client’s message.parts rebuild naturally dedupes by part id.

Common pitfalls

Four error paths

Server-side errors reach the client’s onError via four different paths, corresponding to four different network behaviors:

Client-side signals per path

useChat({
  onError: (error) => {
    // Fires only for paths A / B / C
    // Path D does NOT go here; it goes to onFinish's isDisconnect
  },
  onFinish: ({ isAbort, isDisconnect, isError, finishReason }) => {
    // Four states are mutually exclusive:
    // - Normal completion: all three flags false, finishReason = 'stop' / 'length' / 'tool-calls' / ...
    // - User stop: isAbort = true
    // - Network disconnect: isDisconnect = true (path D)
    // - Mid-stream error: isError = true (path C)
    // - Paths A / B: onFinish does NOT fire (stream never started)
  },
});

Correct server-side layering

Paths A / B (pre-flight): just throw / return HTTP error response:

app.post("/api/chat", async (c) => {
  if (!c.req.header("Authorization")) {
    return c.json({ error: "Unauthorized" }, 401); // ← Path A
  }
  // ...
});

Path C (mid-stream): go through the onError serializer:

const result = streamText({...});

return result.toUIMessageStreamResponse({
  onError: (error) => {
    // Key: this return value becomes the error chunk's errorText
    // Don't return error.message directly — may leak internal stack info
    log.error("stream.failed", error);
    return "Internal error, please retry.";
  },
});

If onError returns a string, the stream emits a { type: "error", errorText: "..." } chunk before ending; the client’s onError and onFinish({ isError: true }) both fire.

Path D (connection severed): server often can’t detect this (or only indirectly via request.signal). The client detects it from the fetch rejection.

Four client-side recovery strategies

SSE environment-layer traps

Streaming SSE puts requirements on every layer of the network path. In production, these are the layers that commonly break:

Reverse-proxy buffering

nginx by default buffers the response and holds it until enough bytes accumulate. SSE stream buffered = client sees “a big burst all at once” instead of “small chunks as they arrive”.

location /api/chat {
  proxy_pass http://app;
  proxy_buffering off;         # ← Key
  proxy_cache off;
  proxy_set_header Connection "";
  proxy_http_version 1.1;
  chunked_transfer_encoding on;
}

Cloudflare

Default Auto Minify and some compression features can break SSE. In Cloudflare dashboard, disable Auto Minify / Rocket Loader / Speed features for the /api/chat path. Or add a response header:

return result.toUIMessageStreamResponse({
  headers: {
    "X-Accel-Buffering": "no", // Generic bypass (nginx / some CDNs recognize)
    "Cache-Control": "no-cache",
  },
});

Service Worker

If your app registers a PWA service worker, it may cache or replay POST requests. Explicitly exclude /api/chat:

self.addEventListener("fetch", (event) => {
  if (event.request.url.includes("/api/chat")) {
    return; // Let the browser handle natively, don't go through SW
  }
  // ...
});

Browser connection limits

HTTP/1.1 limits 6 concurrent connections per origin. An SSE stream takes one, and additional XHRs on the same page can easily hit the cap. Deploy over HTTP/2 or HTTP/3 (Vercel / Cloudflare default) to avoid.

Load-balancer idle timeout

AWS ALB / nginx / Cloudflare’s default idle timeout is typically 60s–5min. An agent running a long task (10+ minutes) may be dropped. Either:

• Bump the LB idle timeout
• Or have the server proactively flush a no-op event every 15–30s (e.g. a transient data-heartbeat) to keep the connection alive

Further reading

Other chapters in this section

• Runtime Lifecycle — the 12 callbacks on the timeline
• UI Stream Orchestration — createUIMessageStream / writer / data-* event protocol
• Message Reference Model — the internal model of UIMessage / ModelMessage
• prepareStep Semantics — the deepest per-step hook
• Client Consumption (useChat) — full receive-side API

SDK source anchors

• [email protected] — dist/index.d.ts:2158-2273 (UIMessageChunk full union definition)
• [email protected] — dist/index.d.ts:2150-2156 (DataUIMessageChunk + transient)
• [email protected] — dist/index.js:5101-5198 (createUIMessageStreamResponse SSE wrapping)
• @ai-sdk/[email protected] — dist/index.js (AbstractChat stream consumption logic)

External references

• MDN — Server-Sent Events (SSE protocol spec)
• Vercel AI SDK Resumable Streams — official resume guide
• nginx SSE config — reverse-proxy buffering settings