workflow 5.0.0-beta.1 → 5.0.0-beta.3

package/docs/cookbook/integrations/ai-sdk.mdx

@@ -0,0 +1,360 @@
+---
+title: AI SDK
+description: Use AI SDK's streamText directly inside durable workflows for lower-level control over model calls and tool execution.
+type: guide
+summary: Use streamText() inside a workflow for full control over model options, stop conditions, and output schemas — while tools remain durable steps.
+related:
+  - /docs/ai
+  - /docs/ai/chat-session-modeling
+  - /docs/ai/defining-tools
+  - /docs/ai/resumable-streams
+  - /docs/api-reference/workflow-ai/durable-agent
+---
+
+[AI SDK](https://ai-sdk.dev/) is Vercel's framework-agnostic TypeScript toolkit for building AI-powered apps and agents — unified provider access, streaming, tool calling, structured output, and UI hooks. Workflow SDK complements it by making those calls durable: the model request, the tool loop, and the multi-turn conversation all survive restarts and timeouts.
+
+For the full AI SDK reference (providers, `streamText`, `generateObject`, `useChat`, tool calling, etc.) see the [AI SDK docs](https://ai-sdk.dev/docs). This page covers the Workflow-specific integration points.
+
+<Callout type="info">
+For most agent use cases, prefer [`DurableAgent`](/cookbook/agent-patterns/durable-agent) which wraps [`streamText`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text) and manages the tool loop automatically. This page covers using `streamText()` directly when you need lower-level control.
+</Callout>
+
+## When to use streamText directly
+
+Use [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text) instead of `DurableAgent` when you need:
+
+* **Custom stop conditions** — [`stopWhen`](https://ai-sdk.dev/docs/ai-sdk-core/agents#stop-conditions), [`prepareStep`](https://ai-sdk.dev/docs/ai-sdk-core/agents#prepare-step), or [`onStepFinish`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#on-step-finish) callbacks
+* **Structured output** — [`Output.object()`](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data) or `Output.array()` alongside tool calling
+* **Step-level callbacks** — `onStepFinish` for logging, metrics, or branching logic
+* **Provider options** — per-step model switching, reasoning budgets, or custom [provider options](https://ai-sdk.dev/docs/ai-sdk-core/provider-options)
+
+## Multi-turn pattern
+
+One workflow run = one full conversation. The workflow suspends between turns on a hook and resumes when the next user message arrives. Conversation state, tool history, and intermediate computation all live inside the run.
+
+<Tabs items={['Workflow', 'API Route', 'Client']}>
+
+<Tab value="Workflow">
+
+```typescript title="workflows/support.ts" lineNumbers
+import { streamText, stepCountIs } from "ai";
+import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
+import type { ModelMessage, UIMessageChunk } from "ai";
+import { z } from "zod";
+
+const MAX_TURNS = 20;
+
+export const turnHook = defineHook({ // [!code highlight]
+  schema: z.object({ message: z.string() }),
+});
+
+async function lookupOrder({ orderId }: { orderId: string }) {
+  "use step";
+  const res = await fetch(`https://api.store.com/orders/${orderId}`);
+  return res.json();
+}
+
+async function processRefund({ orderId, reason }: { orderId: string; reason: string }) {
+  "use step";
+  const res = await fetch("https://api.store.com/refunds", {
+    method: "POST",
+    body: JSON.stringify({ orderId, reason }),
+  });
+  return res.json();
+}
+
+const TOOLS = {
+  lookupOrder: {
+    description: "Look up an order by ID",
+    inputSchema: z.object({ orderId: z.string() }),
+    execute: lookupOrder,
+  },
+  processRefund: {
+    description: "Process a refund",
+    inputSchema: z.object({ orderId: z.string(), reason: z.string() }),
+    execute: processRefund,
+  },
+};
+
+// Per-turn step — streams one agent response to the durable writable // [!code highlight]
+async function runTurn(messages: ModelMessage[]) {
+  "use step";
+
+  const result = streamText({
+    model: "anthropic/claude-haiku-4.5",
+    system: "You are a customer support agent.",
+    messages,
+    tools: TOOLS,
+    stopWhen: stepCountIs(8),
+  });
+
+  const writable = getWritable<UIMessageChunk>();
+  // preventClose keeps the durable writable open so the next turn can  // write to it. Each turn still emits its own start + finish chunks.
+  await result.toUIMessageStream().pipeTo(writable, { preventClose: true }); // [!code highlight]
+
+  const response = await result.response;
+  return { responseMessages: response.messages };
+}
+
+export async function supportWorkflow(initialMessages: ModelMessage[]) {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+  // Create the hook once, outside the loop — same token = HookConflictError // [!code highlight]
+  const hook = turnHook.create({ token: workflowRunId }); // [!code highlight]
+  let allMessages = initialMessages;
+
+  for (let turn = 0; turn < MAX_TURNS; turn++) {
+    const { responseMessages } = await runTurn(allMessages);
+    allMessages = [...allMessages, ...responseMessages];
+
+    const { message } = await hook; // [!code highlight] suspend until next user message
+    if (message === "/done") break;
+
+    allMessages = [...allMessages, { role: "user", content: message }];
+  }
+
+  return { turns: MAX_TURNS };
+}
+```
+
+</Tab>
+
+<Tab value="API Route">
+
+One endpoint handles first turn, follow-ups, and the `/done` exit. The client sends `runId` in the body to distinguish first vs follow-up.
+
+```typescript title="app/api/support/route.ts" lineNumbers
+import type { UIMessage, UIMessageChunk } from "ai";
+import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
+import { start, getRun } from "workflow/api";
+import { supportWorkflow, turnHook } from "@/workflows/support";
+
+// Pump the durable stream until this turn's `finish` chunk, then close  // the HTTP response. The source reader is released (not cancelled) so the
+// workflow's durable stream keeps flowing for the next turn.
+function sliceUntilFinish( // [!code highlight]
+  source: ReadableStream<UIMessageChunk>
+): ReadableStream<UIMessageChunk> {
+  return new ReadableStream<UIMessageChunk>({
+    async start(controller) {
+      const reader = source.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          controller.enqueue(value);
+          if (value.type === "finish") break; // [!code highlight]
+        }
+        controller.close();
+      } catch (e) {
+        controller.error(e);
+      } finally {
+        reader.releaseLock();
+      }
+    },
+  });
+}
+
+// `/done` exits the workflow without emitting chunks. Return a synthetic
+// start+finish so useChat's lifecycle terminates cleanly.
+function emptyTurnStream(): ReadableStream<UIMessageChunk> {
+  return new ReadableStream<UIMessageChunk>({
+    start(controller) {
+      controller.enqueue({ type: "start", messageId: crypto.randomUUID() });
+      controller.enqueue({ type: "finish" });
+      controller.close();
+    },
+  });
+}
+
+export async function POST(req: Request) {
+  const { messages, runId }: { messages: UIMessage[]; runId?: string } =
+    await req.json();
+  const modelMessages = await convertToModelMessages(messages);
+
+  // Follow-up turn: resume hook, return stream starting AFTER the last turn // [!code highlight]
+  if (runId) {
+    try {
+      const run = getRun(runId);
+
+      // Snapshot tail before resuming so our slice only contains this turn // [!code highlight]
+      const probe = run.getReadable();
+      const tailIndex = await probe.getTailIndex();
+      await probe.cancel();
+
+      const lastUser = modelMessages.filter((m) => m.role === "user").at(-1);
+      const text =
+        typeof lastUser?.content === "string"
+          ? lastUser.content
+          : Array.isArray(lastUser?.content)
+            ? lastUser.content
+                .filter((p): p is { type: "text"; text: string } =>
+                  "type" in p && p.type === "text"
+                )
+                .map((p) => p.text)
+                .join("")
+            : "";
+
+      await turnHook.resume(runId, { message: text }); // [!code highlight]
+
+      if (text === "/done") {
+        return createUIMessageStreamResponse({
+          stream: emptyTurnStream(),
+          headers: { "x-workflow-run-id": runId },
+        });
+      }
+
+      const stream = sliceUntilFinish(
+        run.getReadable({ startIndex: tailIndex + 1 }) // [!code highlight]
+      );
+
+      return createUIMessageStreamResponse({
+        stream,
+        headers: { "x-workflow-run-id": runId },
+      });
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message.toLowerCase() : "";
+      if (!msg.includes("not found") && !msg.includes("expired")) throw e;
+      // Stale runId — fall through to start fresh
+    }
+  }
+
+  // First turn: start a new workflow // [!code highlight]
+  const run = await start(supportWorkflow, [modelMessages]);
+  const stream = sliceUntilFinish(run.readable);
+
+  return createUIMessageStreamResponse({
+    stream,
+    headers: { "x-workflow-run-id": run.runId },
+  });
+}
+```
+
+</Tab>
+
+<Tab value="Client">
+
+Store the `runId` in a ref and pass it in the body of every follow-up. `WorkflowChatTransport` forwards it for you.
+
+```tsx title="components/support-chat.tsx" lineNumbers
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { WorkflowChatTransport } from "@workflow/ai";
+import { useMemo, useRef, useState } from "react";
+
+export function SupportChat() {
+  const [input, setInput] = useState("");
+  const runIdRef = useRef<string | null>(null); // [!code highlight]
+
+  const transport = useMemo(
+    () =>
+      new WorkflowChatTransport({
+        api: "/api/support",
+        prepareSendMessagesRequest: ({ messages, body }) => ({
+          body: { ...body, messages, runId: runIdRef.current }, // [!code highlight]
+        }),
+        onChatSendMessage: (response) => {
+          const id = response.headers.get("x-workflow-run-id");
+          if (id) runIdRef.current = id; // [!code highlight]
+        },
+      }),
+    []
+  );
+
+  const { messages, sendMessage, status } = useChat({ transport });
+  const busy = status === "streaming" || status === "submitted";
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        if (busy || !input.trim()) return;
+        sendMessage({ text: input });
+        setInput("");
+      }}
+    >
+      {messages.map((m) => (
+        <div key={m.id}>{m.role}: {m.parts.map((p) => p.type === "text" ? p.text : "").join("")}</div>
+      ))}
+      <input value={input} onChange={(e) => setInput(e.target.value)} disabled={busy} />
+    </form>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
+## How it works
+
+1. **One workflow = one conversation.** The workflow loops on a hook, keeping `allMessages`, tool history, and state alive across turns.
+2. **Hook is created once.** `turnHook.create({ token: workflowRunId })` outside the loop — calling it twice with the same token throws `HookConflictError`.
+3. **`preventClose: true`** on `pipeTo` keeps the durable writable open so the next turn can write to it.
+4. **`sliceUntilFinish`** in the API reads chunks until `type === "finish"`, then closes the HTTP response. The source reader is released — not cancelled — so the workflow stream keeps flowing.
+5. **`startIndex: tailIndex + 1`** gives each follow-up response only the new chunks, avoiding replay of previous turns.
+6. **`/done`** resumes the hook so the workflow exits cleanly, then returns a synthetic `start` + `finish` so `useChat` transitions out of "streaming".
+
+## Pitfalls
+
+Non-obvious correctness details worth knowing before adapting this pattern.
+
+### Snapshot `tailIndex` *before* resuming the hook
+
+{/* @skip-typecheck - fragment referencing variables from the surrounding multi-turn pattern */}
+```typescript
+const tailIndex = await probe.getTailIndex(); // [!code highlight] FIRST
+await probe.cancel();
+await turnHook.resume(runId, { message: text }); // [!code highlight] THEN
+const stream = run.getReadable({ startIndex: tailIndex + 1 });
+```
+
+Reversing the order races the workflow: by the time you read `tailIndex`, the next turn has already written its `start` chunk, and your `startIndex + 1` skips past it.
+
+### Don't call `writable.close()` inside a workflow function
+
+I/O operations like closing streams must happen inside a `"use step"` function. Calling `writable.close()` directly in the workflow body throws `Not supported in workflow functions`. When the workflow returns, the runtime closes the underlying writable for you.
+
+### Don't use `TransformStream.terminate()` to slice the stream
+
+A `TransformStream` with `controller.terminate()` on the `finish` chunk seems like the obvious fit for `sliceUntilFinish`, but throws `Invalid state: TransformStream has been terminated` when late-arriving chunks hit the transform callback. Manual pumping through a custom `ReadableStream` (as shown above) sidesteps the problem entirely.
+
+### Release the source reader, don't cancel it
+
+In `sliceUntilFinish`, use `reader.releaseLock()` in the `finally` block rather than `source.cancel()`. Cancelling propagates upstream and closes the durable writable, breaking the next turn. Releasing the lock just detaches our reader; the durable stream keeps flowing.
+
+### Handle stale `runId` gracefully
+
+Clients can send a `runId` from a long-gone workflow (localStorage, back button, server restart). Wrap the follow-up path in a try/catch for `not found` / `expired` and fall through to the first-turn code path to start a fresh workflow.
+
+## streamText vs DurableAgent
+
+| | `streamText()` | `DurableAgent` |
+|---|---|---|
+| **Tool loop** | AI SDK handles via `stopWhen` | DurableAgent handles internally |
+| **LLM call durability** | Re-executes on replay | Each LLM call is a durable step |
+| **Stop conditions** | `stopWhen`, `prepareStep` | `prepareStep` only |
+| **Structured output** | `Output.object()`, `Output.array()` | Not available |
+| **Step callbacks** | `onStepFinish`, `onChunk` | Not available |
+| **Setup** | Manual stream piping | Automatic |
+
+Use `DurableAgent` for most agent use cases. Use `streamText` when you need the additional control.
+
+## Key APIs
+
+**AI SDK** ([docs](https://ai-sdk.dev/docs))
+
+* [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text) — core streaming function; `toUIMessageStream()` pipes into the durable writable
+* [`tool()` / tool calling](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling) — tools wrap `"use step"` functions so each tool call is replayed from the log, not re-executed
+* [`stepCountIs()` / `stopWhen`](https://ai-sdk.dev/docs/ai-sdk-core/agents#stop-conditions) — bound the agent loop inside each turn
+* [`convertToModelMessages()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/convert-to-model-messages) / [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response) — UI ↔ model message conversion at the API boundary
+* [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) — React hook that consumes the UI message stream on the client
+
+**Workflow SDK**
+
+* [`"use step"`](/docs/api-reference/workflow/use-step) — makes tool executions durable
+* [`defineHook()`](/docs/api-reference/workflow/define-hook) — suspension point for follow-up messages
+* [`getWritable()`](/docs/api-reference/workflow/get-writable) — resumable stream output
+* [`getRun()`](/docs/api-reference/workflow-api/get-run) — `run.getReadable({ startIndex })` for slicing per-turn streams
+* [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport) — passes `runId` between turns

package/docs/cookbook/integrations/chat-sdk.mdx

@@ -0,0 +1,303 @@
+---
+title: Chat SDK
+description: Make Chat SDK bot sessions durable — one workflow run per conversation thread, with hooks bridging inbound platform events into long-running agent logic.
+type: guide
+summary: Chat SDK normalizes Slack, Teams, Discord, Telegram and friends into one thread/message model. Workflow SDK gives each thread a durable run that owns multi-turn state, can sleep for hours, and survives restarts.
+related:
+  - /docs/cookbook/integrations/ai-sdk
+  - /docs/cookbook/integrations/sandbox
+  - /docs/api-reference/workflow/define-hook
+  - /docs/api-reference/workflow-api/start
+  - /docs/api-reference/workflow-api/get-run
+---
+
+[Chat SDK](https://chat-sdk.dev/) is a unified TypeScript SDK for building bots across Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp. Write the bot once, deploy to every platform. It handles webhook verification, event normalization, subscriptions, and cross-platform features like cards and modals.
+
+Workflow SDK complements it by making bot **sessions** durable. Each conversation thread maps to a long-running workflow run that:
+
+- Owns multi-turn state in the durable event log instead of Redis-by-hand bookkeeping
+- Can `sleep()` for hours or days waiting for a user reply, an approval, or a scheduled follow-up
+- Survives deploys, cold starts, and crashes — the session picks up from the last step on replay
+- Receives follow-up messages via hooks, so the bot stays responsive while the workflow is still running
+
+The rest of this page covers the integration pattern. For a full Slack + Next.js + Redis walkthrough, see the [Durable chat sessions guide](https://chat-sdk.dev/docs/guides/durable-chat-sessions-nextjs) on chat-sdk.dev.
+
+## How It Fits Together
+
+Chat SDK owns the edge — webhook verification, event routing, `thread.post()` / `thread.stream()`. Workflow owns the session — state, loops, sleeps, retries. They meet at exactly two points:
+
+```mermaid
+flowchart TD
+    A["Platform webhook"] --> B["Chat SDK event handler<br/>(onNewMention, onSubscribedMessage, …)"]
+    B -->|"no runId in thread state"| C["start(durableChatSession, …)"]
+    B -->|"runId in thread state"| D["resumeHook(runId, { message })"]
+    C --> E["Workflow run (durable)<br/>one per thread; suspends between turns"]
+    D --> E
+    E --> F["&quot;use step&quot; helpers<br/>thread.post(), thread.subscribe(), thread.setState(), …"]
+```
+
+- **Inbound** — Chat SDK handlers decide whether to `start(workflow, [thread, message])` or `resumeHook(runId, { message })`. The `runId` lives in Chat SDK's thread state (Redis, Postgres, or any state adapter).
+- **Outbound** — the workflow calls Chat SDK APIs (`thread.post()`, `thread.subscribe()`, `thread.setState()`) from inside step functions. Never from the top level of a workflow file — adapter packages use Node-only modules that aren't available in the workflow sandbox.
+
+## Why Workflow + Chat SDK
+
+Without Workflow, a long-running bot session usually means one of:
+- Holding a webhook request open while the agent runs (doesn't survive restarts, blows past platform timeouts)
+- Writing session state to Redis manually, plus a scheduler for timeouts and retries, plus custom reconnection logic
+
+Workflow replaces all of that with a single durable function. The bot can:
+
+- Run a tool loop for minutes while the user watches typing indicators
+- Wait for a human approval in another thread before continuing
+- Schedule a follow-up message 24 hours later via `sleep("24h")`
+- Pause on sandbox snapshot, resume when the user sends the next command (see the [Sandbox integration](/docs/cookbook/integrations/sandbox))
+
+Because the session *is* a workflow run, its history is recoverable from the event log — no separate message store to keep in sync.
+
+## The Pattern: One Thread = One Workflow Run
+
+Three files. The bot definition is separate from the workflow so adapter packages stay out of the workflow sandbox.
+
+<Tabs items={['Bot Setup', 'Workflow', 'Event Handlers']}>
+
+<Tab value="Bot Setup">
+
+Register the `Chat` instance as a singleton so step functions can dynamically import it and resolve adapters + state:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const adapters = {
+  slack: createSlackAdapter(),
+};
+
+export interface ThreadState {
+  runId?: string; // [!code highlight]
+}
+
+export const bot = new Chat<typeof adapters, ThreadState>({
+  userName: "durable-bot",
+  adapters,
+  state: createRedisState(),
+  dedupeTtlMs: 600_000,
+}).registerSingleton(); // [!code highlight]
+```
+
+`registerSingleton()` is important: Chat SDK re-hydrates `Thread` objects inside step functions, and it needs a registered singleton to resolve adapters and state for those rehydrated instances.
+
+</Tab>
+
+<Tab value="Workflow">
+
+The workflow is a plain loop over a hook. It receives the serialized thread + first message from the handler, revives them via Chat SDK's standalone `reviver`, and every platform-side effect goes inside a `"use step"` helper:
+
+```typescript title="workflows/durable-chat-session.ts" lineNumbers
+import { Message, reviver, type Thread } from "chat";
+import { defineHook, getWorkflowMetadata } from "workflow";
+import type { ThreadState } from "@/lib/bot";
+
+// Hook payload lives in its own file so the webhook side can import it without
+// pulling in the workflow module.
+import type { ChatTurnPayload } from "@/workflows/chat-turn-hook";
+
+const chatTurnHook = defineHook<ChatTurnPayload>(); // [!code highlight]
+
+async function postAssistantMessage(
+  thread: Thread<ThreadState>,
+  text: string
+) {
+  "use step";
+  // Dynamic import keeps adapter packages out of the workflow sandbox.
+  const { bot } = await import("@/lib/bot"); // [!code highlight]
+  await bot.initialize();
+  await thread.post(text);
+}
+
+async function runTurn(text: string) {
+  "use step";
+  // Your AI SDK call, database lookup, tool loop, etc.
+  return `You said: ${text}`;
+}
+
+async function handleMessage(
+  thread: Thread<ThreadState>,
+  message: Message
+) {
+  const text = message.text.trim();
+  if (text.toLowerCase() === "done") return false;
+
+  const reply = await runTurn(text);
+  await postAssistantMessage(thread, reply);
+  return true;
+}
+
+export async function durableChatSession(payload: string) {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+  const { thread, message } = JSON.parse(payload, reviver) as { // [!code highlight]
+    thread: Thread<ThreadState>;
+    message: Message;
+  };
+
+  const hook = chatTurnHook.create({ token: workflowRunId });
+
+  await postAssistantMessage(thread, "Session started. Reply here; send `done` to stop.");
+
+  if (!(await handleMessage(thread, message))) return;
+
+  // Each hook resumption is one turn. The workflow stays suspended between
+  // messages — zero compute cost while idle.
+  while (true) {
+    const { message: nextRaw } = await hook; // [!code highlight]
+    const next = Message.fromJSON(nextRaw);
+    if (!(await handleMessage(thread, next))) return;
+  }
+}
+```
+
+```typescript title="workflows/chat-turn-hook.ts" lineNumbers
+import type { SerializedMessage } from "chat";
+
+export type ChatTurnPayload = {
+  message: SerializedMessage;
+};
+```
+
+</Tab>
+
+<Tab value="Event Handlers">
+
+Handlers live outside the workflow file so adapter dependencies don't leak in. They decide whether to start a new workflow or resume an existing one, then store the `runId` in thread state:
+
+```typescript title="lib/chat-session-handlers.ts" lineNumbers
+import type { Message, Thread } from "chat";
+import { getRun, resumeHook, start } from "workflow/api";
+import { bot, type ThreadState } from "@/lib/bot";
+import { durableChatSession } from "@/workflows/durable-chat-session";
+import type { ChatTurnPayload } from "@/workflows/chat-turn-hook";
+
+async function startSession(thread: Thread<ThreadState>, message: Message) {
+  const run = await start(durableChatSession, [ // [!code highlight]
+    JSON.stringify({
+      thread: thread.toJSON(),
+      message: message.toJSON(),
+    }),
+  ]);
+  await thread.setState({ runId: run.runId });
+}
+
+async function routeTurn(thread: Thread<ThreadState>, message: Message) {
+  const state = await thread.state;
+
+  // No run yet, or the previous run finished — start fresh.
+  if (!state?.runId || !(await getRun(state.runId).exists)) {
+    await startSession(thread, message);
+    return;
+  }
+
+  try {
+    await resumeHook<ChatTurnPayload>(state.runId, { // [!code highlight]
+      message: message.toJSON(),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message.toLowerCase() : "";
+    if (msg.includes("not found") || msg.includes("expired")) {
+      // Stale runId — start a new session rather than dropping the message.
+      await startSession(thread, message);
+      return;
+    }
+    throw err;
+  }
+}
+
+bot.onNewMention(async (thread, message) => {
+  await thread.subscribe();
+  await routeTurn(thread, message);
+});
+
+bot.onSubscribedMessage(async (thread, message) => {
+  await routeTurn(thread, message);
+});
+```
+
+Wire Chat SDK's webhook handler into a catch-all route. Importing `chat-session-handlers` for side effects registers the event handlers before the first webhook arrives:
+
+```typescript title="app/api/webhooks/[platform]/route.ts" lineNumbers
+import "@/lib/chat-session-handlers";
+import { after } from "next/server";
+import { bot } from "@/lib/bot";
+
+type Platform = keyof typeof bot.webhooks;
+
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ platform: string }> }
+) {
+  const { platform } = await params;
+  const handler = bot.webhooks[platform as Platform];
+  if (!handler) return new Response(`Unknown platform: ${platform}`, { status: 404 });
+
+  return handler(req, { waitUntil: (task) => after(() => task) }); // [!code highlight]
+}
+```
+
+</Tab>
+
+</Tabs>
+
+## How It Works
+
+1. **Thread state stores the `runId`.** Chat SDK's state adapter (Redis, Postgres, memory) holds `{ runId }` per thread. That's the only piece of glue between the two SDKs.
+2. **First mention → `start()`.** Handler serializes `thread` + `message` with `toJSON()`, passes them through `start(durableChatSession, [payload])`, stashes the returned `runId` in thread state.
+3. **Subsequent messages → `resumeHook()`.** Handler looks up the `runId`, serializes the new message, and resumes the workflow's hook. The workflow picks up on the next `await hook` iteration.
+4. **Workflow posts back via steps.** All Chat SDK side effects (`thread.post`, `thread.subscribe`, `thread.setState`) happen inside `"use step"` helpers that dynamically import the bot. This keeps adapter packages outside the workflow sandbox.
+5. **Session ends — two ways.** The workflow returns normally (user said `done`, approval granted, etc.), or the workflow throws. Either way the run completes; the next inbound message with the stale `runId` falls through to `startSession()`.
+
+The workflow is fully durable between turns: `await hook` suspends with zero compute cost, and platform webhooks can fire from anywhere without concern for which server instance handled the previous turn.
+
+## Extending the Pattern
+
+Because the session is just a workflow, everything else from the cookbook composes naturally:
+
+- **Stream AI SDK responses into the thread.** Use the [AI SDK integration](/docs/cookbook/integrations/ai-sdk) pattern inside a step, then pass `result.fullStream` to `thread.post()` — Chat SDK handles platform-specific streaming (Slack edit-in-place, Telegram message-per-chunk, etc.).
+- **Give the bot a sandbox.** Combine with the [Sandbox integration](/docs/cookbook/integrations/sandbox): each thread gets its own persistent sandbox session, snapshots on idle, resumes on the next message. That's effectively a coding-agent bot.
+- **Human-in-the-loop approvals.** `Promise.race([hook, approvalHook])` inside the workflow, post buttons in the thread via [cards](https://chat-sdk.dev/docs/cards), resume `approvalHook` from `bot.onAction(...)`.
+- **Scheduled follow-ups.** `sleep("24h")` before a proactive check-in. Surviving restarts is free.
+
+## Pitfalls
+
+### Don't import the bot at the top of workflow files
+
+Adapter packages (`@chat-adapter/slack`, `@chat-adapter/telegram`, etc.) depend on Node-only modules that aren't available in the workflow bundler's sandbox. Keep `import { bot } from "@/lib/bot"` inside `"use step"` functions with `await import(...)`. Use `reviver` from `chat` for deserialization inside the workflow — it's standalone and has no adapter dependencies.
+
+### Register the bot as a singleton
+
+`new Chat({...}).registerSingleton()`. Chat SDK rehydrates `Thread` objects inside step functions via `reviver`, and it looks up adapters + state from the registered singleton. Without it, thread methods throw when called from step contexts.
+
+### Hook payloads must be JSON-serializable
+
+`Message` and `Thread` have methods, so pass them through `.toJSON()` / `Message.fromJSON()` across the hook boundary. Define a `ChatTurnPayload` type in its own file so both the webhook handler (in the Node bundle) and the workflow (in the workflow sandbox) can share it without dragging in adapter code.
+
+### Handle stale `runId`s
+
+A workflow run ends but its `runId` is still cached in thread state. The next message calls `resumeHook` on a dead run and throws `not found` / `expired`. Gate on `getRun(runId).exists` before resuming, or catch the error and fall through to `startSession`. Either way the user's message must not be dropped.
+
+### Keep the hook outside the loop
+
+One `chatTurnHook.create({ token: workflowRunId })` per workflow run, reused every iteration. Creating a new hook with the same token throws `HookConflictError`. This is the same rule as the [AI SDK](/docs/cookbook/integrations/ai-sdk) and [Sandbox](/docs/cookbook/integrations/sandbox) session patterns.
+
+### Platform timeouts are separate from workflow timeouts
+
+Slack wants a 200 within 3 seconds. The webhook handler returns immediately after `resumeHook` (which is fast) — the workflow then runs in the background and posts back via `thread.post`. Don't try to `await` the whole turn inside the webhook handler; that's what breaks in the naive integration.
+
+## Key APIs
+
+- [`Chat`](https://chat-sdk.dev/docs/api/chat) / [`Thread`](https://chat-sdk.dev/docs/api/thread) / [`Message`](https://chat-sdk.dev/docs/api/message) — Chat SDK primitives. `toJSON()` / `fromJSON()` / `reviver` are the serialization layer.
+- [`start()`](/docs/api-reference/workflow-api/start) — start a new session workflow. Store the returned `runId` in thread state.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) — forward a new platform message to the running workflow.
+- [`getRun()`](/docs/api-reference/workflow-api/get-run) — `run.exists` before resuming, to detect stale `runId`s.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — per-turn suspension point inside the workflow.
+- [`registerSingleton()`](https://chat-sdk.dev/docs/api/chat) — makes the bot resolvable from inside step functions.

package/docs/cookbook/integrations/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Integrations",
+  "pages": ["ai-sdk", "sandbox", "chat-sdk"]
+}