workflow 5.0.0-beta.9 → 5.0.1

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

@@ -1,8 +1,8 @@
 ---
 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.
+description: Make Chat SDK bot sessions durable, with one workflow run per conversation thread and 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.
+summary: Chat SDK normalizes Slack, Teams, Discord, Telegram, and similar platforms into one thread and 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
@@ -11,13 +11,17 @@ related:
   - /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.
+<CopyPrompt
+  text="Make this Chat SDK bot durable with Workflow SDK. Install/use `workflow`. Create one exported workflow function with &quot;use workflow&quot; per chat thread. Store the Chat SDK thread ID, Workflow run ID, and any serialized conversation state in the project data store. Use `defineHook()` from `workflow` for incoming turns and call `resumeHook()` from `workflow/api` from the Chat SDK webhook or message handler. Put provider calls, database writes, and outbound platform messages in &quot;use step&quot; helper functions. Start a new run with `start(workflowFn, [initialThreadState])` when no run exists, otherwise resume the existing hook. Use `getRun(runId)` for status, cancellation, or stream reads. Verify first message, follow-up message, restart/reconnect, duplicate webhook, and failed-send retry behavior."
+/>
+
+[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. A single bot can support each platform. Chat SDK handles webhook verification, event normalization, subscriptions, and cross-platform features such as 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
+- 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
 
 <Callout type="info">
@@ -26,9 +30,9 @@ One thread mapped to one workflow run also means the thread stays on the deploym
 
 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
+## 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:
+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
@@ -40,8 +44,8 @@ flowchart TD
     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.
+- **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, since adapter packages use Node-only modules that aren't available in the workflow sandbox.
 
 ## Why Workflow + Chat SDK
 
@@ -56,11 +60,11 @@ Workflow replaces all of that with a single durable function. The bot can:
 - 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.
+Because the session *is* a workflow run, its history is recoverable from the event log, so there's no separate message store to keep in sync.
 
-## The Pattern: One Thread = One Workflow Run
+## 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.
+This pattern uses 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']}>
 
@@ -121,7 +125,7 @@ async function postAssistantMessage(
 
 async function runTurn(text: string) {
   "use step";
-  // Your AI SDK call, database lookup, tool loop, etc.
+  // Your AI SDK call, database lookup, tool loop, and other operations.
   return `You said: ${text}`;
 }
 
@@ -153,7 +157,7 @@ export async function durableChatSession(payload: string) {
   if (!(await handleMessage(thread, message))) return;
 
   // Each hook resumption is one turn. The workflow stays suspended between
-  // messages — zero compute cost while idle.
+  // messages: zero compute cost while idle.
   while (true) {
     const { message: nextRaw } = await hook; // [!code highlight]
     const next = Message.fromJSON(nextRaw);
@@ -176,6 +180,10 @@ export type ChatTurnPayload = {
 
 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:
 
+<Callout type="info">
+If the platform can deliver the same first message concurrently, use a deterministic hook token derived from the thread ID so duplicate handlers route to the active chat session hook. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript title="lib/chat-session-handlers.ts" lineNumbers
 import type { Message, Thread } from "chat";
 import { getRun, resumeHook, start } from "workflow/api";
@@ -196,7 +204,7 @@ async function startSession(thread: Thread<ThreadState>, message: Message) {
 async function routeTurn(thread: Thread<ThreadState>, message: Message) {
   const state = await thread.state;
 
-  // No run yet, or the previous run finished — start fresh.
+  // No run yet, or the previous run finished: start fresh.
   if (!state?.runId || !(await getRun(state.runId).exists)) {
     await startSession(thread, message);
     return;
@@ -209,7 +217,7 @@ async function routeTurn(thread: Thread<ThreadState>, message: Message) {
   } 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.
+      // Stale runId: start a new session rather than dropping the message.
       await startSession(thread, message);
       return;
     }
@@ -252,30 +260,30 @@ export async function POST(
 
 </Tabs>
 
-## How It Works
+## 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()`.
+1. **Thread state stores the `runId`**: Chat SDK's state adapter (Redis, Postgres, or memory) holds `{ runId }` per thread. This state connects the two SDKs.
+2. **The first mention calls `start()`**: The handler serializes `thread` and `message` with `toJSON()`, passes them through `start(durableChatSession, [payload])`, and stores the returned `runId` in thread state.
+3. **Subsequent messages call `resumeHook()`**: The handler looks up the `runId`, serializes the new message, and resumes the workflow's hook. The workflow continues on the next `await hook` iteration.
+4. **The workflow posts through steps**: All Chat SDK side effects (`thread.post`, `thread.subscribe`, and `thread.setState`) happen inside `"use step"` helpers that dynamically import the bot. This keeps adapter packages outside the workflow sandbox.
+5. **The session ends in two ways**: The workflow returns normally when the user sends `done` or an approval is granted, 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
+## Extending the pattern
 
-Because the session is just a workflow, everything else from the cookbook composes naturally:
+Because the session is 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.).
+- **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, including Slack edit-in-place and Telegram message-per-chunk.
 - **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.
+- **Scheduled follow-ups.** Call `sleep("24h")` before a proactive check-in. The workflow preserves the timer across restarts.
 
 ## 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.
+Adapter packages such as `@chat-adapter/slack` and `@chat-adapter/telegram` 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
 
@@ -289,19 +297,24 @@ Adapter packages (`@chat-adapter/slack`, `@chat-adapter/telegram`, etc.) depend
 
 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.
 
+### Make first-message routing atomic
+
+Thread state is also the idempotency boundary for starting sessions. Back it with a state adapter or database operation that can atomically claim the thread before `startSession()` runs when duplicate sessions would be harmful.
+
 ### 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.
+Slack requires an HTTP 200 response within 3s. The webhook handler returns after `resumeHook`, then the workflow runs in the background and posts through `thread.post`. Don't `await` the whole turn inside the webhook handler because that synchronous integration exceeds the platform timeout.
 
 ## 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.
+- [`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.
+- [Idempotency](/docs/foundations/idempotency): protect duplicate-sensitive first messages and side effects.

package/docs/cookbook/integrations/sandbox.mdx

@@ -1,8 +1,8 @@
 ---
 title: Sandbox
-description: Model one Vercel Sandbox per workflow run — durable, idle-efficient, and not bound by the 5-hour sandbox hard cap.
+description: Model one Vercel Sandbox per workflow run, durable, idle-efficient, and not bound by the 5-hour sandbox hard cap.
 type: guide
-summary: Own a sandbox for the lifetime of a workflow run. Hibernate on idle via snapshot(), proactively refresh before the sandbox hard cap, and reconnect by runId — so one logical session can run effectively forever.
+summary: Own a sandbox for the lifetime of a workflow run. Hibernate on idle via snapshot(), proactively refresh before the sandbox hard cap, and reconnect by `runId`, so one logical session can run effectively forever.
 related:
   - /docs/ai/defining-tools
   - /docs/foundations/errors-and-retries
@@ -10,34 +10,38 @@ related:
   - /docs/cookbook/agent-patterns/durable-agent
 ---
 
-[Vercel Sandbox](https://vercel.com/docs/sandbox) provides isolated code execution environments. The `@vercel/sandbox` package has first-class support for the Workflow SDK — the `Sandbox` class is serializable, and its methods (`create`, `runCommand`, `stop`, `snapshot`) implicitly run as steps. You can use `Sandbox` directly inside a workflow function without wrapping each call in a separate `"use step"` function.
+<CopyPrompt
+  text="Implement a durable Vercel Sandbox-backed coding-agent workflow. Install the Sandbox package used by this project and `workflow`. Create an exported workflow function with &quot;use workflow&quot; that owns the agent session. Put sandbox creation, command execution, snapshot, refresh, and cleanup into helper functions with &quot;use step&quot;. Persist the sandbox ID, snapshot ID, and workflow run ID in the project data store so clients can reconnect. Use `getWritable()` from `workflow` to stream agent progress and command output. Use `sleep()` to hibernate, refresh, or enforce idle timeouts. Add API routes to start a session, reconnect by run ID, and stop/cleanup. Verify first run, reconnect after reload, snapshot restore, timeout, and cleanup behavior."
+/>
+
+[Vercel Sandbox](https://vercel.com/docs/sandbox) provides isolated code execution environments. The `@vercel/sandbox` package has first-class support for the Workflow SDK: the `Sandbox` class is serializable, and its methods (`create`, `runCommand`, `stop`, `snapshot`) implicitly run as steps. You can use `Sandbox` directly inside a workflow function without wrapping each call in a separate `"use step"` function.
 
 ## Why Workflow + Sandbox
 
-A sandbox alone gets you an isolated VM. A workflow around it gets you a **durable controller** for that VM's entire lifetime:
+A sandbox alone provides an isolated virtual machine (VM). A workflow provides a **durable controller** for that VM's entire lifetime:
 
 - **One workflow run = one sandbox session.** The `runId` is the only state you need to persist on the client. Close the tab, come back a week later, POST the same `runId` and you're back in the same session.
-- **Efficient resource use.** Active sandboxes cost money; hibernated workflows cost nothing. The workflow races a command hook against a `sleep()` timer — when idle, it calls `sandbox.snapshot()` (which also stops the VM) and waits indefinitely. Next command → spin a new sandbox from the snapshot with filesystem, installed packages, and git history intact.
-- **Beyond the 5-hour hard cap.** Every Vercel Sandbox has a maximum lifetime. The workflow tracks that deadline and proactively snapshots + recreates *before* the cap, so the logical session outlives any one VM. Effectively unbounded session duration on top of time-bounded infrastructure.
+- **Efficient resource use.** Active sandboxes cost money; hibernated workflows cost nothing. The workflow races a command hook against a `sleep()` timer. When idle, it calls `sandbox.snapshot()` (which also stops the VM) and waits indefinitely. When the next command arrives, the workflow starts a new sandbox from the snapshot with the filesystem, installed packages, and git history intact.
+- **Beyond the 5-hour hard cap.** Every Vercel Sandbox has a maximum lifetime. The workflow tracks that deadline and proactively creates a snapshot and replacement before the cap, so the logical session outlives any one VM. This provides an effectively unbounded session on time-bounded infrastructure.
 - **Automatic cleanup.** `try/finally` in the workflow guarantees the VM is stopped on failure or destroy.
 
 <Callout type="info">
 An effectively unbounded sandbox session is still one workflow run, so it stays on the deployment that started it. If the controller or agent code should upgrade over time, use an explicit version boundary and pass the serialized state or stream handles forward. See [Versioning](/docs/foundations/versioning).
 </Callout>
 
-## Use Case: Coding Agents
+## Use case: coding agents
 
-This is the pattern [Open Agents](https://open-agents.dev/) uses to spawn coding agents that run "infinitely in the cloud." Each agent session gets its own sandbox — full filesystem, network, and runtime access — and the durable workflow keeps the agent loop resumable across restarts, auto-hibernates when the user walks away, and reconnects instantly when they return.
+This is the pattern [Open Agents](https://open-agents.dev/) uses to spawn coding agents that run "infinitely in the cloud." Each agent session gets its own sandbox (full filesystem, network, and runtime access), and the durable workflow keeps the agent loop resumable across restarts, auto-hibernates when the user walks away, and reconnects instantly when they return.
 
 Most coding-agent workloads look like this:
 
-- User sends a task → agent plans, reads files, runs shell commands, commits.
-- User walks away mid-run → agent keeps going, eventually goes idle waiting for input.
-- User comes back days later → same branch, same filesystem, same conversation history.
+- The user sends a task, and the agent plans, reads files, runs shell commands, and commits.
+- If the user leaves mid-run, the agent continues and eventually waits for input.
+- When the user returns, the same branch, filesystem, and conversation history remain available.
 
-Without durable workflows you'd need a separate state store for the agent loop, a separate job queue for retries, a separate scheduler for idle cleanup, and bespoke reconnection logic. With the pattern below, all of it is one file.
+Without durable workflows, you'd need a separate state store for the agent loop, a job queue for retries, a scheduler for idle cleanup, and custom reconnection logic. The pattern below keeps the workflow controller in one file.
 
-## Quickstart: One-shot Pipeline
+## Quickstart: one-shot pipeline
 
 Before the full session pattern, the simplest shape. Each sandbox method is an implicit step, so the event log records every command and the workflow replays from the last completed call on restart.
 
@@ -70,17 +74,17 @@ export async function sandboxPipeline(input: { commands: string[] }) {
 }
 ```
 
-## Session Pattern: Persistent Sandbox Beyond the Hard Cap
+## Session pattern: persistent sandbox beyond the hard cap
 
 One workflow run owns a sandbox for its whole lifetime. The workflow's loop does two jobs simultaneously:
 
-1. **Command pipeline** — await a hook, run the next user command, stream output, loop.
-2. **Sandbox lifecycle** — race the hook against a `sleep()` timer armed for whichever comes first: the idle deadline or the sandbox's refresh deadline (a safety margin before its hard cap).
+1. **Command pipeline**: await a hook, run the next user command, stream output, loop.
+2. **Sandbox lifecycle**: race the hook against a `sleep()` timer armed for whichever comes first: the idle deadline or the sandbox's refresh deadline (a safety margin before its hard cap).
 
 When the timer wins:
 
-- **Idle** → `sandbox.snapshot()` and wait indefinitely for the next command. No compute while asleep.
-- **Near sandbox hard cap** → `sandbox.snapshot()` and immediately create a new sandbox from the snapshot. The session appears continuous; the underlying VM just rotated.
+- **Idle**: Call `sandbox.snapshot()` and wait indefinitely for the next command. The workflow uses no compute while suspended.
+- **Near the sandbox hard cap**: Call `sandbox.snapshot()` and immediately create a new sandbox from the snapshot. The session remains continuous while the underlying VM rotates.
 
 The only way out is an explicit `/destroy` command.
 
@@ -166,7 +170,7 @@ export async function sandboxSessionWorkflow() {
   "use workflow";
 
   const { workflowRunId } = getWorkflowMetadata();
-  // Create the hook once, outside the loop — reusing the same token from inside // [!code highlight]
+  // Create the hook once, outside the loop: reusing the same token from inside // [!code highlight]
   // the loop would throw HookConflictError. // [!code highlight]
   const hook = commandHook.create({ token: workflowRunId });
 
@@ -201,8 +205,8 @@ export async function sandboxSessionWorkflow() {
   try {
     while (!destroyed) {
       if (hibernated && snapshot) {
-        // While hibernated, the VM is already stopped. Just wait for the next
-        // command — no idle timer, no compute cost.
+        // While hibernated, the VM is already stopped. Wait for the next
+        // command: no idle timer, no compute cost.
         const payload = await hook;
         if (payload.command === "/destroy") { destroyed = true; break; }
 
@@ -227,7 +231,7 @@ export async function sandboxSessionWorkflow() {
         continue;
       }
 
-      // Active — wake at whichever comes first: idle-deadline or refresh-deadline.
+      // Active. Wake at whichever comes first: idle-deadline or refresh-deadline.
       const idleDeadline = lastActivityAt + HIBERNATE_AFTER_MS;
       const refreshDeadline = sandboxExpiresAt - REFRESH_SAFETY_MS;
       const wakeAt = Math.min(idleDeadline, refreshDeadline);
@@ -242,7 +246,7 @@ export async function sandboxSessionWorkflow() {
         const nearExpiry = Date.now() >= refreshDeadline;
 
         if (nearExpiry) {
-          // Proactive refresh — snapshot and immediately recreate so the
+          // Proactive refresh: snapshot and immediately recreate so the
           // session outlives the sandbox hard cap.
           await emit({ type: "status", state: "refreshing", at: Date.now() });
           const snap = await sandbox.snapshot(); // [!code highlight]
@@ -259,7 +263,7 @@ export async function sandboxSessionWorkflow() {
           });
           lastActivityAt = Date.now();
         } else {
-          // Idle — snapshot and hibernate indefinitely.
+          // Idle: snapshot and hibernate indefinitely.
           await emit({ type: "status", state: "hibernating", at: Date.now() });
           snapshot = await sandbox.snapshot(); // [!code highlight]
           hibernated = true;
@@ -298,7 +302,11 @@ export async function sandboxSessionWorkflow() {
 
 <Tab value="API Routes">
 
-Two endpoints. `/start` accepts an optional `{ runId }` — if the run still exists, it replays the event log from index 0 so a returning client fully rehydrates. `/command` resumes the hook and returns immediately; command output lands on the `/start` stream.
+Two endpoints manage the session. `/start` accepts an optional `{ runId }`: if the run still exists, it replays the event log from index 0 so a returning client fully rehydrates. `/command` resumes the hook and returns immediately; command output lands on the `/start` stream.
+
+<Callout type="info">
+This example starts a fresh sandbox session when no `runId` is provided. If your product needs one sandbox session per user, project, or task, use a deterministic hook token derived from that session key and route retries through the active hook. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
 
 ```typescript title="app/api/sandbox/start/route.ts" lineNumbers
 import { start, getRun } from "workflow/api";
@@ -326,7 +334,7 @@ export async function POST(req: Request) {
         },
       });
     }
-    // Stale runId — fall through to start fresh.
+    // Stale runId: fall through to start fresh.
   }
 
   const run = await start(sandboxSessionWorkflow, []);
@@ -375,7 +383,7 @@ export async function POST(req: Request) {
 
 <Tab value="Client">
 
-On mount, if a `runId` is stashed in `localStorage`, reconnect to the existing run. Otherwise start fresh. Commands are POSTed to `/command` — output lands on the `/start` stream.
+On mount, reconnect to the existing run if `localStorage` contains a `runId`. Otherwise, start a new run. Send commands to `/command` with POST requests. Output arrives on the `/start` stream.
 
 ```tsx title="components/sandbox-runner.tsx" lineNumbers
 "use client";
@@ -468,22 +476,22 @@ export function SandboxRunner() {
 
 </Tabs>
 
-## How It Works
+## How it works
 
-1. **One workflow = one session.** The workflow owns a sandbox for its entire lifetime. The `runId` is the only state the client has to remember.
-2. **Hook created once.** `commandHook.create({ token: workflowRunId })` outside the loop. Creating it twice with the same token throws `HookConflictError`.
-3. **Two timer branches.** The active-state race wakes on the earlier of `idleDeadline` and `refreshDeadline`. The hibernated state awaits the hook alone — no timer, no compute.
-4. **Proactive refresh.** `refreshDeadline = sandboxExpiresAt - REFRESH_SAFETY_MS`. Hitting this triggers a snapshot + immediate new sandbox from that snapshot, rolling over the hard cap without user intervention.
-5. **`sandbox.snapshot()` stops the VM.** It's documented as part of the snapshot process — don't call `stop()` separately.
-6. **Resume = new sandbox.** `Sandbox.create({ source: { type: "snapshot", snapshotId } })` creates a fresh VM from the snapshot. The new sandbox has a different `sandboxId`; filesystem, installed packages, and git history are preserved.
-7. **Reconnect by runId.** `getRun(runId).getReadable({ startIndex: 0 })` replays the durable event log to a returning client, who rebuilds UI state from the replay.
-8. **Exit only on `/destroy`.** The workflow loop has no hard deadline of its own. Individual sandboxes time out; the session doesn't.
+1. **One workflow represents one session**: The workflow owns a sandbox for its entire lifetime. The `runId` is the only state the client has to remember.
+2. **Create the hook once**: Call `commandHook.create({ token: workflowRunId })` outside the loop. Creating it twice with the same token throws `HookConflictError`.
+3. **Two timer branches control wake-up**: The active-state race wakes on the earlier of `idleDeadline` and `refreshDeadline`. The hibernated state awaits the hook alone, with no timer or compute.
+4. **Proactive refresh replaces the sandbox**: When `refreshDeadline = sandboxExpiresAt - REFRESH_SAFETY_MS` arrives, the workflow takes a snapshot and immediately creates a new sandbox from it. This rolls over the hard cap without user intervention.
+5. **`sandbox.snapshot()` stops the VM**: The snapshot process stops the VM, so don't call `stop()` separately.
+6. **Resume creates a new sandbox**: `Sandbox.create({ source: { type: "snapshot", snapshotId } })` creates a new VM from the snapshot. The new sandbox has a different `sandboxId`; the filesystem, installed packages, and git history are preserved.
+7. **Reconnect by `runId`**: `getRun(runId).getReadable({ startIndex: 0 })` replays the durable event log to a returning client, which rebuilds UI state from the replay.
+8. **Exit only on `/destroy`**: The workflow loop has no hard deadline of its own. Individual sandboxes time out, but the session doesn't.
 
 ## Pitfalls
 
 ### `sandbox.stop()` is terminal
 
-A stopped sandbox cannot be restarted — you have to create a new one. Hibernation is only possible via `snapshot()` + new-sandbox-from-snapshot. Don't try to "pause" an active sandbox with `stop()` and resume later.
+A stopped sandbox cannot be restarted: you have to create a new one. Hibernation is only possible via `snapshot()` + new-sandbox-from-snapshot. Don't try to "pause" an active sandbox with `stop()` and resume later.
 
 ### `snapshot()` already stops the VM
 
@@ -495,7 +503,7 @@ Both `resuming` (idle → command) and `refreshing` (near-hard-cap rotation) cre
 
 ### Keep the refresh margin generous
 
-`snapshot()` + `Sandbox.create({ source })` takes real time (typically tens of seconds). If `REFRESH_SAFETY_MS` is too small, the old sandbox hits its hard cap mid-snapshot. Leave at least 60–90 seconds; 5 minutes is comfortable.
+`snapshot()` followed by `Sandbox.create({ source })` takes time, typically tens of seconds. If `REFRESH_SAFETY_MS` is too small, the old sandbox hits its hard cap mid-snapshot. Leave at least 60–90 seconds; the example uses 5 minutes.
 
 ### Don't call `writable.close()` inside a workflow function
 
@@ -505,16 +513,21 @@ Stream closure must happen inside a `"use step"` function. Calling `writable.clo
 
 Clients can hold `runId`s from long-gone workflow runs (localStorage, back button, server restart). Gate the reconnect path on `run.exists` and fall through to starting fresh. On `hook.resume`, catch `not found` / `expired` and return 410 so the client clears its state.
 
+### Decide whether `/start` should be idempotent
+
+The sample treats a missing or stale `runId` as a request for a new session. For one-session-per-resource behavior, use a durable resource key, such as `projectId` or `taskId`, to claim or retrieve the run before starting a new one.
+
 ### Keep the hook outside the loop
 
 Each iteration's `hook.then(...)` attaches a listener to the same hook instance. Creating a new hook per iteration with the same token throws `HookConflictError`. One hook, one token (`workflowRunId`), reused every iteration.
 
 ## Key APIs
 
-- [`Sandbox.create`](https://vercel.com/docs/sandbox) — provision a VM (runtime, source, timeout)
-- [`sandbox.runCommand`](https://vercel.com/docs/sandbox) — execute a command; implicit step
-- [`sandbox.snapshot`](https://vercel.com/docs/sandbox) — save state and stop the VM; returns `Snapshot`
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — suspension point for user commands
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable timer that powers both idle hibernation and proactive refresh
-- [`getRun()`](/docs/api-reference/workflow-api/get-run) — look up a run and replay its event log for reconnection
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — resumable NDJSON event stream
+- [`Sandbox.create`](https://vercel.com/docs/sandbox): provision a VM (runtime, source, timeout)
+- [`sandbox.runCommand`](https://vercel.com/docs/sandbox): execute a command; implicit step
+- [`sandbox.snapshot`](https://vercel.com/docs/sandbox): save state and stop the VM; returns `Snapshot`
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): suspension point for user commands
+- [`sleep()`](/docs/api-reference/workflow/sleep): durable timer that powers both idle hibernation and proactive refresh
+- [`getRun()`](/docs/api-reference/workflow-api/get-run): look up a run and replay its event log for reconnection
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): resumable newline-delimited JSON (NDJSON) event stream
+- [Idempotency](/docs/foundations/idempotency): choose when `/start` should reuse an existing run

package/docs/deploying.mdx

@@ -0,0 +1,106 @@
+---
+title: Deploying
+description: Deploy workflows locally, on Vercel, or anywhere using pluggable World adapters.
+type: overview
+summary: Learn how to deploy workflows to different environments using World adapters.
+related:
+  - /worlds/local
+  - /worlds/postgres
+  - /worlds/vercel
+  - /worlds/building-a-world
+---
+
+The same workflow code can run locally during development, on Vercel with zero configuration, or on any infrastructure using **Worlds**, which are pluggable adapters that handle storage, queuing, and communication.
+
+## Local development
+
+During local development, workflows use the **Local World** without configuration. The Local World stores workflow data in a `.workflow-data/` directory and processes steps synchronously for development and testing.
+
+```bash
+# Run your dev server to use workflows locally
+npm run dev
+```
+
+You can inspect local workflow data using the CLI:
+
+```bash
+npx workflow inspect runs
+```
+
+<Callout>
+  Learn more about the [Local World](/worlds/local) configuration and internals.
+</Callout>
+
+## Deploying to Vercel
+
+Deploy workflows to production on Vercel without configuration. Workflows deployed to Vercel use the **Vercel World**.
+
+The Vercel World provides:
+
+- **Durable storage**: Workflow state persists across function invocations
+- **Managed queuing**: The queue processes steps reliably with automatic retries
+- **Automatic scaling**: Workflows scale with your application
+- **Built-in observability**: View workflow runs in the Vercel dashboard
+- **Multi-region**: The region that creates each run also hosts its workflow data, queue, and streams, keeping them close to your users
+
+Deploy your application:
+
+```bash
+vercel deploy
+```
+
+<FluidComputeCallout />
+
+<Callout type="warn">
+  **Enable access to System Environment Variables before deploying.** Workflow
+  recognizes a Vercel deployment by `VERCEL_DEPLOYMENT_ID`, which Vercel exposes
+  to your build and your functions only when the **Enable access to System
+  Environment Variables** checkbox is selected under **Settings**, then
+  **Environment Variables**, in your project. With it cleared, the deployment
+  falls back to the Local World and every run fails on the read-only
+  filesystem. See
+  [System environment variables](/worlds/vercel#system-environment-variables).
+</Callout>
+
+<Callout>
+  Learn more about the [Vercel World](/worlds/vercel) and its capabilities, including [multi-region](/worlds/vercel#multi-region).
+</Callout>
+
+## Self-hosting & other providers
+
+For self-hosting or deploying to other cloud providers, you can use community-maintained Worlds or build your own.
+
+<Cards>
+  <Card title="Explore Worlds" href="/worlds">
+    Browse official and community World implementations with compatibility status and performance benchmarks.
+  </Card>
+  <Card title="Build Your Own" href="/worlds/building-a-world">
+    Learn how to implement a custom World for your infrastructure.
+  </Card>
+</Cards>
+
+### Using a third-party World
+
+To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
+
+```bash
+export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
+# Plus any world-specific configuration
+export DATABASE_URL=postgres://...
+```
+
+Each World may have its own configuration requirements. Refer to that World's documentation for details.
+
+## Observability
+
+The [Observability tools](/docs/observability) work with any World backend. By default, they connect to your local environment, but you can configure them to inspect remote deployments:
+
+```bash
+# Inspect local workflows
+npx workflow inspect runs
+
+# Inspect remote workflows
+npx workflow inspect runs --backend @workflow/world-postgres
+```
+
+Learn more about [Observability](/docs/observability) tools.

package/docs/errors/abort-signal-timeout-in-workflow.mdx

@@ -11,23 +11,27 @@ related:
   - /docs/errors/timeout-in-workflow
 ---
 
+<CopyPrompt
+  text="Replace `AbortSignal.timeout()` inside workflow functions. Find the failing `AbortSignal.timeout(ms)` call in a `&quot;use workflow&quot;` function. Import `sleep` from `workflow`. Create `const controller = new AbortController()`, pass `controller.signal` into the async work that supports cancellation, and start a deterministic timeout with `void sleep(&quot;10s&quot;).then(() => controller.abort())` or a `Promise.race` between the work and `sleep(...)`. Keep actual fetch/SDK side effects inside `&quot;use step&quot;` helpers when they need Node.js APIs. Treat intentional aborts as non-retryable if appropriate by throwing `FatalError`. Verify the operation succeeds before the timeout, aborts after the timeout, and replays without abort-signal-timeout-in-workflow."
+/>
+
 ## Error
 
-```
+```text
 AbortSignal.timeout() is not supported in workflow functions.
 Use sleep() with an AbortController instead.
 ```
 
-## Why This Happens
+## Why this happens
 
-`AbortSignal.timeout()` creates a signal that aborts after a real-time delay using an internal timer. Workflow functions must be [deterministic](/docs/foundations/workflows-and-steps) to support replay — they run the same code multiple times during the workflow's lifecycle, using the [event log](/docs/how-it-works/event-sourcing) to resume execution to the correct point.
+`AbortSignal.timeout()` creates a signal that aborts after a real-time delay using an internal timer. Workflow functions must be [deterministic](/docs/foundations/workflows-and-steps) to support replay: they run the same code multiple times during the workflow's lifecycle, using the [event log](/docs/how-it-works/event-sourcing) to resume execution to the correct point.
 
 Real-time timers break this determinism because:
-- On the first execution, the timer might fire after 10 seconds
-- On replay, the timer would fire again, but the event log may have already advanced past that point
-- The timer's behavior depends on wall-clock time, which varies between executions
+- On the first execution, the timer might fire after 10 seconds.
+- On replay, the timer would fire again, but the event log may have already advanced past that point.
+- The timer's behavior depends on wall-clock time, which varies between executions.
 
-## How to Fix
+## How to fix
 
 Use [`sleep()`](/docs/api-reference/workflow/sleep) with an `AbortController` to create a deterministic timeout that cancels in-flight work:
 
@@ -66,7 +70,7 @@ async function fetchData(signal: AbortSignal) {
 }
 ```
 
-The `sleep()` + `AbortController` pattern is the durable equivalent of `AbortSignal.timeout()`. The sleep is recorded in the event log, so it replays deterministically. If `fetchData` finishes within 10 seconds you get the response; if not, the timer fires `controller.abort()`, `fetch` rejects with an `AbortError`, and the step's failure propagates to the workflow as a `FatalError` (no retries — abort is intentional cancellation).
+The `sleep()` and `AbortController` pattern is the durable equivalent of `AbortSignal.timeout()`. The sleep is recorded in the event log, so it replays deterministically. If `fetchData` finishes within 10 seconds, you get the response. Otherwise, the timer calls `controller.abort()`, `fetch` rejects with an `AbortError`, and the step's failure propagates to the workflow as a `FatalError` (no retries because the abort is intentional cancellation).
 
 <Callout type="info">
 `AbortSignal.timeout()` works normally inside step functions, since steps have full Node.js runtime access and are not replayed.
@@ -74,7 +78,7 @@ The `sleep()` + `AbortController` pattern is the durable equivalent of `AbortSig
 
 ## Related
 
-- [Cancellation](/docs/foundations/cancellation) — Patterns for cancelling in-flight work
-- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) — Durable sleep primitive
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Why workflow functions must be deterministic
-- [`setTimeout` in Workflow](/docs/errors/timeout-in-workflow) — Similar restriction on `setTimeout`
+- [Cancellation](/docs/foundations/cancellation): Patterns for canceling in-flight work
+- [`sleep()` API Reference](/docs/api-reference/workflow/sleep): Durable sleep primitive
+- [Workflows and Steps](/docs/foundations/workflows-and-steps): Why workflow functions must be deterministic
+- [`setTimeout` in Workflow](/docs/errors/timeout-in-workflow): Similar restriction on `setTimeout`