workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/cookbook/agent-patterns/agent-cancellation.mdx

@@ -1,15 +1,23 @@
 ---
 title: Agent Cancellation
-description: Cancel a running agent from the outside using AbortSignal — a hook fires the abort, the agent step bails out of the model stream, and the client gets a clean stop notification.
+description: Cancel a running agent from the outside using AbortSignal. A hook fires the abort, the agent step bails out of the model stream, and the client gets a clean stop notification.
 type: guide
 summary: Cancel a running agent cooperatively with AbortController. A stop hook fires controller.abort(), the signal propagates into the agent step to cancel the model stream, and a data-stopped part is emitted to streaming clients before the workflow returns.
 ---
 
-Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback.
+<CopyPrompt
+  text="Add cancellation to this durable AI agent. For hard cancellation, expose a server route that receives `runId` and calls `getRun(runId).cancel()` from `workflow/api`. For graceful stop, define `stopHook` with `defineHook()` from `workflow`, create it with a stable token such as the workflow run ID, and race the agent loop against the stop hook using `Promise.race`. Use `getWritable<UIMessageChunk>()` to emit a final stopped/canceled message before returning. Wire the UI Stop button to the route that resumes the hook or falls back to `getRun(runId).cancel()`. Verify active model/tool work stops, cleanup runs for graceful stop, and stale run IDs are handled."
+/>
+
+Cancel a running agent from the outside through a **Stop** button in a chat user interface (UI), an admin cancellation endpoint, or a timeout fallback.
+
+<Callout type="warn">
+This recipe uses the deprecated `DurableAgent` API. For new agents, use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and follow the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The cancellation patterns here (`run.cancel()`, stop-signal hook + `Promise.race`, `AbortController`) apply to either API.
+</Callout>
 
 ## Pattern
 
-Create an `AbortController` in the workflow and race the agent (passing its signal) against a stop hook. When the hook fires, `controller.abort()` is called — the signal propagates into the agent step and cancels the underlying model stream. Before returning, a `data-stopped` part is written to the stream so any streaming clients can render a clean end state.
+Create an `AbortController` in the workflow and race the agent (passing its signal) against a stop hook. When the hook fires, `controller.abort()` is called: the signal propagates into the agent step and cancels the underlying model stream. Before returning, a `data-stopped` part is written to the stream so any streaming clients can render a clean end state.
 
 ```typescript lineNumbers
 import { DurableAgent } from "@workflow/ai/agent";
@@ -90,7 +98,7 @@ export async function stoppableAgent(messages: ModelMessage[]) {
 }
 ```
 
-### API Route to Trigger Stop
+### API route to trigger stop
 
 ```typescript lineNumbers
 import { stopHook } from "@/workflows/stoppable-agent";
@@ -110,7 +118,7 @@ export async function POST(
 }
 ```
 
-### Client Stop Button
+### Client stop button
 
 ```tsx lineNumbers
 "use client";
@@ -134,23 +142,23 @@ export function StopButton({ runId }: { runId: string }) {
 
 ## How it works
 
-1. An `AbortController` is created at the start of the workflow
-2. A hook is created with token `stop:${workflowRunId}`
-3. `Promise.race` runs the agent stream and the stop hook concurrently
-4. The agent receives `controller.signal` — when aborted, the underlying model stream is cancelled
-5. When the stop API resumes the hook, `controller.abort()` is called — the race resolves and the workflow exits
-6. `emitStopSignal` writes a `data-stopped` part to the stream so the client renders a clean stop state
+1. The workflow creates an `AbortController` when it starts.
+2. The workflow creates a hook with the token `stop:${workflowRunId}`.
+3. `Promise.race` runs the agent stream and the stop hook concurrently.
+4. The agent receives `controller.signal`. When aborted, the signal cancels the underlying model stream.
+5. When the stop API resumes the hook, the workflow calls `controller.abort()`, resolves the race, and exits.
+6. `emitStopSignal` writes a `data-stopped` part to the stream so the client renders a clean stop state.
 
 ## Adapting this
 
-* **Add a timeout** — race a third `sleep()` promise to auto-stop after a deadline
-* **Audit logging** — include a `reason` field in the stop schema to record who stopped and why
-* **Cross-process** — the hook token is deterministic, so any process can call `stopHook.resume()` with the run ID
-* **Step limits** — combine with `maxSteps` on the agent to cap execution even without manual stop
+- **Add a timeout**: Race a third `sleep()` promise to stop automatically after a deadline.
+- **Audit logging**: Include a `reason` field in the stop schema to record who stopped the agent and why.
+- **Cross-process**: The hook token is deterministic, so any process can call `stopHook.resume()` with the run ID.
+- **Step limits**: Combine the pattern with `maxSteps` on the agent to cap execution without a manual stop.
 
 ## Key APIs
 
-* [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook for the stop signal
-* [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
-* [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream output and the stop notification to the client
-* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that respects the abort signal via its `signal` option
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Defines a type-safe hook for the stop signal.
+- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata): Provides the run ID for deterministic hook tokens.
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): Streams output and the stop notification to the client.
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): AI SDK's durable agent that respects the abort signal and replaces `DurableAgent`.

package/docs/cookbook/agent-patterns/durable-agent.mdx

@@ -1,150 +1,22 @@
 ---
-title: Durable Agent
-description: Replace a stateless AI agent with a durable one that survives crashes, retries tool calls, and streams output.
+title: DurableAgent is now WorkflowAgent
+description: Use AI SDK v7's WorkflowAgent for durable, resumable AI agents.
 type: guide
-summary: Convert an AI SDK Agent into a DurableAgent backed by a workflow, with tools as retryable steps.
+summary: Build durable, resumable AI agents with AI SDK v7's WorkflowAgent.
 ---
 
-Use this pattern to make any AI SDK agent durable. The agent becomes a workflow, tools become steps, and the framework handles retries, streaming, and state persistence automatically.
+<CopyPrompt
+  text="Convert this stateless AI SDK agent to a durable agent with AI SDK v7's `WorkflowAgent`. Install/use `@ai-sdk/workflow` and `workflow`. Replace the manual `streamText` loop with `new WorkflowAgent(...)` from `@ai-sdk/workflow`, run inside an exported function with `&quot;use workflow&quot;`. Mark side-effectful tool `execute` functions with `&quot;use step&quot;` so they run as durable workflow steps with retries and observability. Stream `ModelCallStreamPart` chunks with `getWritable()` from `workflow`, convert the run stream to UI message chunks with `createModelCallToUIChunkTransform()` in the API route, and expose a route that starts or reconnects to the run. If migrating from the deprecated `DurableAgent`, follow the migration guide at https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent. Verify tool retries, stream output, and resume/reconnect behavior."
+/>
 
-## When to use this
+## WorkflowAgent from AI SDK v7
 
-- Any AI agent with tool calls that should survive crashes and restarts
-- Agents where tool calls hit external APIs that need automatic retries
-- Long-running agent sessions where losing progress is unacceptable
-- Agents that need per-step observability in the workflow event log
+Use AI SDK v7's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agent work. It replaces `DurableAgent` and keeps the current agent pattern in the AI SDK package.
 
-## Pattern
+- Import `WorkflowAgent` from `@ai-sdk/workflow` and run it inside a `"use workflow"` function.
+- Stream `ModelCallStreamPart` chunks with `getWritable()`, then convert the run stream to UI message chunks with `createModelCallToUIChunkTransform()` in your route.
+- Mark tool `execute` functions with `"use step"` when they should run as durable workflow steps with retry and observability behavior.
 
-Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
-
-### Workflow
-
-```typescript
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-async function searchFlights({ from, to, date }: {
-  from: string;
-  to: string;
-  date: string;
-}) {
-  "use step"; // [!code highlight]
-  const res = await fetch(
-    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
-  );
-  if (!res.ok) throw new Error(`Search failed: ${res.status}`);
-  return res.json();
-}
-
-async function bookFlight({ flightId, passenger }: {
-  flightId: string;
-  passenger: string;
-}) {
-  "use step"; // [!code highlight]
-  const res = await fetch("https://api.example.com/bookings", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ flightId, passenger }),
-  });
-  if (!res.ok) throw new Error(`Booking failed: ${res.status}`);
-  return res.json();
-}
-
-async function checkWeather({ city }: { city: string }) {
-  "use step"; // [!code highlight]
-  const res = await fetch(`https://api.weather.com/forecast?city=${city}`);
-  return res.json();
-}
-
-export async function flightAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const agent = new DurableAgent({ // [!code highlight]
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a helpful flight booking assistant.",
-    tools: {
-      searchFlights: {
-        description: "Search for available flights between two airports",
-        inputSchema: z.object({
-          from: z.string().describe("Departure airport code"),
-          to: z.string().describe("Arrival airport code"),
-          date: z.string().describe("Travel date (YYYY-MM-DD)"),
-        }),
-        execute: searchFlights,
-      },
-      bookFlight: {
-        description: "Book a specific flight for a passenger",
-        inputSchema: z.object({
-          flightId: z.string().describe("Flight ID from search results"),
-          passenger: z.string().describe("Passenger full name"),
-        }),
-        execute: bookFlight,
-      },
-      checkWeather: {
-        description: "Check the weather forecast for a city",
-        inputSchema: z.object({
-          city: z.string().describe("City name"),
-        }),
-        execute: checkWeather,
-      },
-    },
-  });
-
-  const result = await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(), // [!code highlight]
-    maxSteps: 10,
-  });
-
-  return { messages: result.messages };
-}
-```
-
-### API route
-
-```typescript
-import type { UIMessage } from "ai";
-import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
-import { start } from "workflow/api";
-import { flightAgent } from "@/app/workflows/flight-agent";
-
-export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = await convertToModelMessages(messages); // [!code highlight]
-
-  const run = await start(flightAgent, [modelMessages]); // [!code highlight]
-
-  return createUIMessageStreamResponse({ // [!code highlight]
-    stream: run.readable,
-    headers: {
-      "x-workflow-run-id": run.runId,
-    },
-  });
-}
-```
-
-## How it works
-
-1. **DurableAgent wraps Agent** — same API as AI SDK's `Agent`, but backed by a workflow. If the process crashes, the agent resumes from the last completed step on replay.
-2. **Tools as steps** — each tool's `execute` function uses `"use step"`, giving it automatic retries, full Node.js access, and an entry in the workflow event log.
-3. **Streaming** — `getWritable<UIMessageChunk>()` streams the agent's output (text chunks, tool calls, tool results) to the client in real time via `createUIMessageStreamResponse`.
-4. **maxSteps** — limits the total number of LLM calls the agent can make, preventing runaway tool loops.
-
-## Adapting to your use case
-
-- **Change the model** — replace `"anthropic/claude-haiku-4.5"` with any AI Gateway model string (e.g. `"openai/gpt-4o"`, `"anthropic/claude-sonnet-4-5"`).
-- **Add tools** — define a new `"use step"` function with a Zod schema. Each tool automatically gets retries and persistence.
-- **Workflow-level tools** — if a tool needs workflow primitives like `sleep()` or `createHook()`, omit `"use step"` so it runs in the workflow context instead.
-- **Multi-turn** — pass `result.messages` plus new user messages to subsequent `agent.stream()` calls for multi-turn conversations.
-- **Client integration** — use `useChat()` from `@ai-sdk/react` with `WorkflowChatTransport` from `@workflow/ai` for a full chat UI with reconnection support.
-
-## Key APIs
-
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — declares step functions with retries and full Node.js access
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable wrapper around AI SDK's Agent
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — streams agent output to the client
-- [`start()`](/docs/api-reference/workflow-api/start) — starts a workflow run from an API route
+<Callout type="warn">
+`DurableAgent` is deprecated and remains documented for existing code only. See the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent), or the [`DurableAgent` API reference](/docs/api-reference/workflow-ai/durable-agent) while migrating.
+</Callout>

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -5,14 +5,22 @@ type: guide
 summary: Use defineHook with the tool call ID to suspend an agent for human approval, with an optional timeout.
 ---
 
-Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds.
+<CopyPrompt
+  text="Add a human approval gate to this AI workflow. Define a typed hook with `defineHook()` from `workflow` for approval payloads. At the approval point, create the hook once with a stable token, await it inside the `&quot;use workflow&quot;` function, and branch on approved/rejected input. Add a server route that receives the human decision and calls `resumeHook(token, payload)` from `workflow/api`. If the approval should expire, race the hook against `sleep()` from `workflow`. Update the UI to show the pending approval and call the resume route. Verify approve, reject, timeout, and duplicate resume behavior."
+/>
+
+<Callout type="warn">
+This recipe uses the deprecated `DurableAgent` API. For new agents, use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and follow the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The human-in-the-loop pattern here (hooks, `Promise.race`, approval gating) applies to either API.
+</Callout>
+
+Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds through a user interface (UI) or API.
 
 ## When to use this
 
 - Booking confirmations where users must approve before charges are made
 - Content publishing gates where an editor must sign off
-- Any agent action where the cost of getting it wrong justifies a human check
-- Actions with side effects that can't be easily undone
+- Agent actions where the cost of an error justifies a human check
+- Actions with side effects that are difficult to reverse
 
 ## Pattern
 
@@ -59,7 +67,7 @@ async function confirmBooking({ flightId, passenger }: {
 }
 
 // Stream a custom data part so the client can render the approval UI.
-// This MUST run before the hook suspends the workflow — otherwise
+// This MUST run before the hook suspends the workflow, otherwise
 // the tool-invocation won't appear in the stream until the tool returns,
 // and the client would have no way to show approval buttons.
 async function emitApprovalRequest(details: {
@@ -99,7 +107,7 @@ async function emitApprovalResolved(details: {
   }
 }
 
-// No "use step" — hooks are workflow-level primitives
+// No "use step": hooks are workflow-level primitives
 async function requestBookingApproval(
   { flightId, passenger, price }: {
     flightId: string;
@@ -230,26 +238,26 @@ const approvalResult = messages
 
 ## How it works
 
-1. **`defineHook()` with schema** — creates a typed hook with Zod validation. The approval payload is validated before the workflow receives it.
-2. **`toolCallId` as token** — the approval tool uses the tool call ID as the hook token, naturally linking the hook to the specific tool invocation.
-3. **`emitApprovalRequest` step** — writes a `data-approval-needed` custom data part to the stream *before* the hook suspends. Without this, the client would never see the approval controls because tool invocations don't stream until the tool returns.
-4. **No `"use step"` on the approval tool** — the tool runs at the workflow level because `defineHook().create()` is a workflow primitive. It calls step functions (`emitApprovalRequest`, `emitApprovalResolved`, `confirmBooking`) for I/O.
-5. **`Promise.race` with sleep** — the approval races against a durable timeout. If nobody responds, the workflow continues with an expiration message.
-6. **`emitApprovalResolved` step** — writes the outcome to the stream so the client can update the card immediately, without waiting for the tool-invocation result.
+1. **`defineHook()` with schema**: Creates a typed hook with Zod validation. The approval payload is validated before the workflow receives it.
+2. **`toolCallId` as token**: Uses the tool call ID as the hook token, linking the hook to the specific tool invocation.
+3. **`emitApprovalRequest` step**: Writes a `data-approval-needed` custom data part to the stream *before* the hook suspends. Without this step, the client wouldn't see the approval controls because tool invocations don't stream until the tool returns.
+4. **No `"use step"` on the approval tool**: Runs the tool at the workflow level because `defineHook().create()` is a workflow primitive. The tool calls step functions (`emitApprovalRequest`, `emitApprovalResolved`, and `confirmBooking`) for I/O.
+5. **`Promise.race` with sleep**: Races the approval against a durable timeout. If nobody responds, the workflow continues with an expiration message.
+6. **`emitApprovalResolved` step**: Writes the outcome to the stream so the client can update the card immediately without waiting for the tool-invocation result.
 
 ## Adapting to your use case
 
-- **Change the approval schema** — add fields like `reason`, `amount`, `reviewerEmail` to match your domain.
-- **Multiple approval gates** — the pattern works for any number of tools. Each tool creates its own hook with its own `toolCallId`.
-- **Escalation** — if the first approver doesn't respond, use `sleep()` + another hook to escalate to a backup reviewer.
-- **Adjust timeout** — use `"24h"` for production, shorter durations for demos.
-- **Workflow-level vs step tools** — tools that use `sleep()`, `defineHook()`, or other workflow primitives must NOT use `"use step"`. Tools with only I/O (API calls, DB queries) should use `"use step"` for retries.
+- **Change the approval schema**: Add fields such as `reason`, `amount`, and `reviewerEmail` to match your domain.
+- **Multiple approval gates**: Apply the pattern to any number of tools. Each tool creates its own hook with its own `toolCallId`.
+- **Escalation**: If the first approver doesn't respond, use `sleep()` and another hook to escalate to a backup reviewer.
+- **Adjust the timeout**: Use `"24h"` for production and shorter durations for demos.
+- **Workflow-level versus step tools**: Tools that use `sleep()`, `defineHook()`, or other workflow primitives must not use `"use step"`. Tools with only I/O, such as API calls and database queries, should use `"use step"` for retries.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — declares step functions with retries
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook with schema validation
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream custom data parts from steps
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable agent with tool definitions
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Declares step functions with retries.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Defines a type-safe hook with schema validation.
+- [`sleep()`](/docs/api-reference/workflow/sleep): Provides a durable timeout for approval expiration.
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): Streams custom data parts from steps.
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Provides AI SDK's durable agent and replaces `DurableAgent`.

package/docs/cookbook/common-patterns/batching.mdx

@@ -5,11 +5,15 @@ type: guide
 summary: Split items into fixed-size batches, process each batch concurrently with Promise.allSettled, and pace batches with sleep to avoid overloading downstream services.
 ---
 
+<CopyPrompt
+  text="Implement durable batch processing. Import `sleep` from `workflow`. In an exported &quot;use workflow&quot; function, split the input records into chunks of a fixed `batchSize`. For each batch, call a &quot;use step&quot; helper such as `processRecord(record)` for every record using `Promise.allSettled` so one record failure does not hide the rest. Record successes and failures in a serializable result object. Between batches, `await sleep(&quot;1s&quot;)` or another configured delay to respect downstream rate limits. Make the step idempotent using record IDs or external idempotency keys. Verify all-success, partial-failure, and rate-paced execution paths."
+/>
+
 Use batching when you need to process a large list of items in parallel while controlling concurrency. Items are split into fixed-size batches, each batch runs concurrently, and failures in one batch don't affect others.
 
 ## When to use this
 
-- Bulk data imports (contacts, orders, products from a CSV)
+- Bulk data imports (contacts, orders, or products from a comma-separated values (CSV) file)
 - Processing hundreds or thousands of items against external APIs
 - Calling rate-limited APIs where you need to control concurrency
 - Any fan-out where you want failure isolation between groups
@@ -17,7 +21,7 @@ Use batching when you need to process a large list of items in parallel while co
 ## How it works
 
 1. Records are split into fixed-size batches.
-2. Each batch runs in parallel via `Promise.allSettled` — failures in one record don't affect others.
+2. Each batch runs in parallel through `Promise.allSettled`, so failures in one record don't affect others.
 3. A `sleep()` between batches paces requests to avoid overloading downstream services.
 4. After all batches, a summary is returned with succeeded/failed counts.
 
@@ -41,7 +45,7 @@ export async function batchImport(records: Record[], batchSize: number) {
   for (let i = 0; i < records.length; i += batchSize) {
     const batch = records.slice(i, i + batchSize);
 
-    // Run batch in parallel — failures are isolated per record
+    // Run batch in parallel: failures are isolated per record
     const outcomes = await Promise.allSettled( // [!code highlight]
       batch.map((record) => processRecord(record))
     );
@@ -85,21 +89,21 @@ async function processRecord(record: Record): Promise<string> {
 
 ## Adapting to your use case
 
-- Replace the `Record` type with your actual data shape (orders, images, products, etc.).
-- Replace `processRecord()` with your real import logic — DB upserts, API calls, file processing.
+- Replace the `Record` type with your actual data shape, such as orders, images, or products.
+- Replace `processRecord()` with your import logic, such as database upserts, API calls, or file processing.
 - Tune `batchSize` and the `sleep()` duration to match your downstream rate limits.
-- Add or remove tracking as needed — the pattern works with any item type.
+- Add or remove tracking as needed; the pattern works with any item type.
 
 ## Tips
 
-- **Use `Promise.allSettled` over `Promise.all`** when you want to continue even if some items fail. `Promise.all` rejects on the first failure; `allSettled` waits for everything and tells you what failed.
-- **Tune batch size to your downstream API limits.** If the API allows 10 concurrent requests, use `batchSize: 10`.
-- **Add pacing with `sleep()`** between batches to respect rate limits. The sleep is durable — it survives cold starts.
-- **Each `processRecord` call is an independent step.** If one fails, it retries up to 3 times without affecting other items in the batch.
+- **Use `Promise.allSettled` instead of `Promise.all`**: Use this pattern when you want to continue even if some items fail. `Promise.all` rejects on the first failure, while `allSettled` waits for everything and identifies failures.
+- **Tune batch size to your downstream API limits**: If the API allows 10 concurrent requests, use `batchSize: 10`.
+- **Add pacing with `sleep()`**: Add a delay between batches to respect rate limits. The sleep is durable and survives cold starts.
+- **Treat each `processRecord` call as an independent step**: If one call fails, it retries up to three times without affecting other items in the batch.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
-- [`sleep()`](/docs/api-reference/workflow/sleep) -- pacing delay between batches
-- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) -- runs items in parallel, isolating failures
+- [`"use workflow"`](/docs/foundations/workflows-and-steps): Marks the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps): Marks functions that run with full Node.js access.
+- [`sleep()`](/docs/api-reference/workflow/sleep): Adds a pacing delay between batches.
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled): Runs items in parallel and isolates failures.

package/docs/cookbook/common-patterns/idempotency.mdx

@@ -1,45 +1,29 @@
 ---
 title: Idempotency
-description: Ensure external side effects happen exactly once, even when steps are retried or workflows are replayed.
+description: Make step retries safe and coordinate duplicate workflow starts with hook tokens.
 type: guide
-summary: Use step IDs as idempotency keys for external APIs like Stripe so that retries and replays don't create duplicate charges.
+summary: Use step IDs for retry-safe external calls, and use deterministic hook tokens when duplicate requests must route to one active workflow.
 ---
 
-Workflow steps can be retried (on failure) and replayed (on cold start). If a step calls an external API that isn't idempotent, retries could create duplicate charges, send duplicate emails, or double-process records. Use idempotency keys to make these operations safe.
+<CopyPrompt
+  text="Make this workflow's side effects idempotent. For retry-safe external calls, read the deterministic step ID inside the &quot;use step&quot; function with `getStepMetadata()` from `workflow` and pass `stepId` as the idempotency key to the external API (for example Stripe's `Idempotency-Key` header) so step retries deduplicate. For duplicate workflow starts, derive a deterministic hook token from the domain key (for example `order:${orderId}`): in the API route, look up the active hook with `getHookByToken(token)` from `workflow/api` (catching `HookNotFoundError` from `workflow/errors`) and reuse its `runId`, otherwise call `start(...)`; inside the workflow, create the hook with the same token and check `await hook.getConflict()` before duplicate-sensitive work. Verify retried steps deduplicate, duplicate starts reuse the active run, and conflicts are handled."
+/>
+
+Use idempotency when a retry or duplicate request should not repeat the underlying work. In Workflow, there are two common patterns: use the step ID for retry-safe external calls, and use hook tokens to coordinate duplicate workflow starts.
 
 ## When to use this
 
-- Charging a payment (Stripe, PayPal)
-- Sending transactional emails or SMS
-- Creating records in external systems where duplicates are harmful
-- Any step that has side effects in systems you don't control
+- A step charges a payment, sends an email, enqueues work, or creates an external record.
+- A route may receive duplicate requests that should map to one active workflow run.
 
-## Pattern: Step ID as idempotency key
+## Step idempotency
 
 Every step has a unique, deterministic `stepId` available via `getStepMetadata()`. Pass this as the idempotency key to external APIs:
 
 ```typescript
 import { getStepMetadata } from "workflow";
 
-declare function createCharge(customerId: string, amount: number): Promise<{ id: string }>; // @setup
-declare function sendReceipt(customerId: string, chargeId: string): Promise<void>; // @setup
-
-export async function chargeCustomer(customerId: string, amount: number) {
-  "use workflow";
-
-  const charge = await createCharge(customerId, amount);
-  await sendReceipt(customerId, charge.id);
-
-  return { customerId, chargeId: charge.id, status: "completed" };
-}
-```
-
-### Step function with idempotency key
-
-```typescript
-import { getStepMetadata } from "workflow";
-
-async function createCharge(
+export async function createCharge(
   customerId: string,
   amount: number
 ): Promise<{ id: string }> {
@@ -69,39 +53,43 @@ async function createCharge(
 
   return charge.json();
 }
-
-async function sendReceipt(customerId: string, chargeId: string): Promise<void> {
-  "use step";
-
-  const { stepId } = getStepMetadata();
-
-  await fetch("https://api.example.com/receipts", {
-    method: "POST",
-    headers: { "Idempotency-Key": stepId },
-    body: JSON.stringify({ customerId, chargeId }),
-  });
-}
 ```
 
-## Race condition caveats
+See [Step Idempotency](/docs/foundations/idempotency#step-idempotency) for why `stepId` is stable across retries and how to think about external API conflicts.
 
-Workflow does not currently provide distributed locking or true exactly-once delivery across concurrent runs. If two workflow runs could process the same entity concurrently:
+## Run idempotency
 
-- **Rely on the external API's idempotency** (like Stripe's `Idempotency-Key`) rather than checking a local flag.
-- **Don't use check-then-act patterns** like "read a flag, then write if not set" -- another run could read the same flag between your read and write.
+For duplicate workflow-start requests, derive a hook token from your domain key. You can avoid obvious duplicate starts by checking whether an active hook already owns that token before calling `start()`:
 
-If your external API doesn't support idempotency keys natively, consider adding a deduplication layer (e.g., a database unique constraint on the operation ID).
+```typescript
+import { getHookByToken, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+  const token = `order:${orderId}`;
+
+  try {
+    const hook = await getHookByToken(token); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
 
-## Tips
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  return Response.json({ runId: run.runId, reused: false });
+}
+```
 
-- **`stepId` is deterministic.** It's the same value across retries and replays of the same step, making it a reliable idempotency key.
-- **Always provide idempotency keys for non-idempotent external calls.** Even if you think a step won't be retried, cold-start replay will re-execute it.
-- **Handle 409/conflict as success.** If an external API returns "already processed," treat that as a successful result, not an error.
-- **Make your own APIs idempotent** where possible. Accept an idempotency key and return the cached result on duplicate requests.
+The workflow should create the deterministic hook and check `await hook.getConflict()` before duplicate-sensitive work: awaiting `getConflict()` suspends the workflow to commit the hook registration and resolves with the conflicting run when another active run already owns the token (or `null` once the hook is registered). See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how to steer an active run with `resumeHook()` and how to handle the current race between `start()` and hook registration.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) -- declares step functions with full Node.js access
-- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
-- [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Declares step functions with full Node.js access.
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata): Provides the deterministic `stepId` for idempotency keys.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Creates a hook with an optional deterministic token.
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): Finds the hook that owns a token.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resumes the active hook when the duplicate request carries data.
+- [`start()`](/docs/api-reference/workflow-api/start): Starts a new workflow run.

package/docs/cookbook/common-patterns/rate-limiting.mdx

@@ -5,6 +5,10 @@ type: guide
 summary: When an external API returns 429, throw RetryableError with the Retry-After value so the workflow runtime automatically reschedules the step after the specified delay.
 ---
 
+<CopyPrompt
+  text="Add durable rate-limit handling to external API steps. Import `RetryableError`, `FatalError`, `getStepMetadata`, and `sleep` from `workflow` as needed. In each HTTP-calling &quot;use step&quot; helper, if the response status is 429, read the `Retry-After` header and throw `new RetryableError(&quot;Rate limited&quot;, { retryAfter })`. For transient 5xx/network failures, throw `RetryableError` with an exponential delay based on `getStepMetadata().attempt`. For permanent 4xx failures, throw `FatalError`. If the dependency is completely down, add a workflow-level circuit breaker that `await sleep(&quot;30s&quot;)` before probing again. Make requests idempotent with stable keys, and verify 429, 5xx, fatal 4xx, and circuit-breaker behavior."
+/>
+
 Use this pattern when calling external APIs that enforce rate limits. Instead of writing manual retry loops, throw `RetryableError` with a `retryAfter` value and let the workflow runtime handle rescheduling.
 
 ## When to use this
@@ -63,7 +67,7 @@ async function upsertToWarehouse(contactId: string, contact: unknown) {
 }
 ```
 
-## Pattern: Exponential backoff
+## Pattern: exponential backoff
 
 Use `getStepMetadata()` to access the current attempt number and calculate increasing delays:
 
@@ -86,7 +90,7 @@ async function callFlakeyApi(endpoint: string) {
 }
 ```
 
-## Pattern: Circuit breaker with sleep
+## Pattern: circuit breaker with sleep
 
 When a dependency is completely down, stop hitting it for a cooldown period using `sleep()`, then probe with a single test request:
 
@@ -134,7 +138,7 @@ async function callService(requestNum: number): Promise<boolean> {
 }
 ```
 
-## Pattern: Custom max retries
+## Pattern: custom max retries
 
 Override the default retry count (3) for steps that need more or fewer attempts:
 
@@ -224,5 +228,5 @@ export async function downloadWithRetry(url: string) {
 - [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
 - [`RetryableError`](/docs/api-reference/workflow/retryable-error) -- signals the runtime to retry after a delay
 - [`FatalError`](/docs/api-reference/workflow/fatal-error) -- signals a permanent failure, skipping retries
-- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the current attempt number and step ID
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the current attempt number and step ID
 - [`sleep()`](/docs/api-reference/workflow/sleep) -- durable pause for circuit breaker cooldowns