workflow 5.0.0-beta.30 → 5.0.0-beta.32

package/docs/api-reference/workflow/index.mdx

@@ -47,8 +47,8 @@ Workflow SDK contains the following functions you can use inside your workflow f
     <Card href="/docs/api-reference/workflow/get-writable" title="getWritable()">
         Access the current workflow run's default stream.
     </Card>
-    <Card href="/docs/api-reference/workflow/experimental-set-attributes" title="experimental_setAttributes()">
-        Attach experimental string metadata to the current workflow run.
+    <Card href="/docs/api-reference/workflow/set-attributes" title="setAttributes()">
+        Attach string metadata to the current workflow run.
     </Card>
 </Cards>
 

package/docs/api-reference/workflow/{experimental-set-attributes.mdx → set-attributes.mdx}

@@ -1,8 +1,8 @@
 ---
-title: experimental_setAttributes
+title: setAttributes
 description: Attach string metadata to workflow run for observability.
 type: reference
-summary: Use experimental_setAttributes inside a workflow or step function to set run attributes.
+summary: Use setAttributes inside a workflow or step function to set run attributes.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
@@ -12,17 +12,13 @@ related:
 
 Attaches string metadata to the current workflow run.
 
-<Callout>
-This API is experimental and may change before the stable attributes API is released.
-</Callout>
-
 ```typescript lineNumbers
-import { experimental_setAttributes } from "workflow"
+import { setAttributes } from "workflow"
 
 export async function orderWorkflow(orderId: string) {
   "use workflow"
 
-  await experimental_setAttributes({
+  await setAttributes({
     phase: "received",
     orderId,
   })
@@ -35,24 +31,24 @@ export async function orderWorkflow(orderId: string) {
 
 <TSDoc
 definition={`
-import { experimental_setAttributes } from "workflow";
-export default experimental_setAttributes;`}
+import { setAttributes } from "workflow";
+export default setAttributes;`}
 showSections={['parameters']}
 />
 
 ## Usage
 
-Call `experimental_setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
+Call `setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
 
 Attribute values must be strings. Pass `undefined` to remove an attribute:
 
 ```typescript lineNumbers
-import { experimental_setAttributes } from "workflow"
+import { setAttributes } from "workflow"
 
 export async function cleanupAttributes() {
   "use workflow"
 
-  await experimental_setAttributes({ staleKey: undefined })
+  await setAttributes({ staleKey: undefined })
 }
 ```
 
@@ -62,4 +58,8 @@ Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error)
 
 Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
 
-Native attributes require spec version 4 or later. Step-body storage errors throw from `experimental_setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.
+Native attributes require spec version 4 or later. Step-body storage errors throw from `setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.
+
+<Callout>
+This function was previously exported as `experimental_setAttributes`. The old name still works as a deprecated alias — update imports to `setAttributes`.
+</Callout>

package/docs/api-reference/workflow-api/start.mdx

@@ -59,7 +59,7 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * Each call to `start()` creates a new workflow run. If retried requests must route to one active workflow, have the workflow create a deterministic hook token and use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) to reuse an already-registered active hook. The lookup is not atomic with `start()`, so concurrent callers can still create extra runs before the hook is registered; handle that race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work — on a conflict it resolves with the run that owns the token, so the duplicate can return the active owner to the caller. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Idempotency](/docs/foundations/idempotency#run-idempotency).
 * All arguments must be [serializable](/docs/foundations/serialization).
 * When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
-* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) option of the same name.
+* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`setAttributes`](/docs/api-reference/workflow/set-attributes) option of the same name.
 
 <Callout type="info">
 If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).

package/docs/cookbook/advanced/child-workflows.mdx

@@ -7,6 +7,10 @@ related:
   - /docs/api-reference/workflow-api/start
 ---
 
+<CopyPrompt
+  text="Refactor this workflow to use child workflows. Keep the parent as an exported `&quot;use workflow&quot;` function. Move independent units of durable work into separate exported child workflow functions. From the parent, call `start(childWorkflow, [args])` from `workflow/api` or the documented `startAndWait`/hook pattern where completion must resume the parent. Pass only serializable state to children. For fan-out, start children in parallel with `Promise.all` or bounded batches, collect run IDs, handle partial failures with `Promise.allSettled`, and use `getRun(runId)` when status, cancellation, streams, or return values are needed. Verify child start, completion, failure, and parent resume behavior."
+/>
+
 Use child workflows when a single workflow needs to orchestrate many independent units of work. Each child runs as its own workflow with a separate event log, retry boundary, and failure scope -- if one child fails, it doesn't take down the parent or siblings.
 
 ## When to use child workflows

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -5,6 +5,10 @@ type: guide
 summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
 ---
 
+<CopyPrompt
+  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build assigns stable workflow IDs and replay can resolve functions after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, stable IDs across deployments, and replay safety."
+/>
+
 import { File, Folder, Files } from "fumadocs-ui/components/files";
 
 <Callout>

package/docs/cookbook/advanced/serializable-steps.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps#step-functions
 ---
 
+<CopyPrompt
+  text="Make this non-serializable dependency usable inside a durable workflow with the step-as-factory pattern. Instead of passing the object (AI SDK model, cloud SDK client) into the workflow, export a factory that returns an async callback marked with &quot;use step&quot; which constructs and returns the object at execution time, for example `export function openai(...args) { return async () => { &quot;use step&quot;; return openaiProvider(...args); }; }`. Pass the factory across the workflow boundary — the compiler serializes the function reference, not the instance — and invoke it inside steps where full Node.js access is available. Keep the factory's constructor arguments serializable. Verify the workflow builds, replays deterministically, and the dependency is only instantiated during step execution."
+/>
+
 <Callout>
 This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
 </Callout>

package/docs/cookbook/advanced/upgrading-workflows.mdx

@@ -10,6 +10,10 @@ related:
   - /docs/foundations/hooks
 ---
 
+<CopyPrompt
+  text="Add a safe self-upgrade point to this long-running workflow. Identify the loop boundary where no step is mid-side-effect. Define a serializable state object that contains all progress needed to continue. At the boundary, call `start(self, [state], { deploymentId: &quot;latest&quot; })` or the documented replacement workflow with the carried state, then return from the old run. If upgrades should be manual, add a `defineHook()` upgrade signal and resume it from an API route with `resumeHook()` from `workflow/api`. Make the handoff idempotent so retries do not start duplicate successor runs, and verify old-to-new handoff plus duplicate prevention."
+/>
+
 Workflows that block on external events for days, weeks, or months can outlive many deployments. **The key is to identify a clean upgrade point in the workflow** — a moment where it's safe to checkpoint state and start fresh — and then call [`start()`](/docs/api-reference/workflow-api/start) with `deploymentId: "latest"` to spawn a new run carrying that state forward. The current run ends; the next run begins on whatever deployment is live at that moment, so shipped fixes apply immediately without ever migrating an in-flight run.
 
 <Callout type="info">

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

@@ -5,6 +5,10 @@ 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.
 ---
 
+<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/cancelled 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 — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback.
 
 <Callout type="warn">

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

@@ -5,6 +5,10 @@ type: guide
 summary: Build durable, resumable AI agents with AI SDK v7's WorkflowAgent.
 ---
 
+<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."
+/>
+
 ## WorkflowAgent from AI SDK v7
 
 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.

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

@@ -5,6 +5,10 @@ type: guide
 summary: Use defineHook with the tool call ID to suspend an agent for human approval, with an optional timeout.
 ---
 
+<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>

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

@@ -5,6 +5,10 @@ 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

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

@@ -5,6 +5,10 @@ type: guide
 summary: Use step IDs for retry-safe external calls, and use deterministic hook tokens when duplicate requests must route to one active workflow.
 ---
 
+<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

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

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

@@ -5,6 +5,10 @@ type: guide
 summary: Run a sequence of steps where each registers a compensation. If any step throws a FatalError, compensations execute in reverse order to restore consistency.
 ---
 
+<CopyPrompt
+  text="Implement a saga-style workflow. Import `FatalError` from `workflow`. In the exported &quot;use workflow&quot; function, keep a compensation stack such as `const compensations: Array<() => Promise<void>> = []`. For each forward side effect, create a &quot;use step&quot; helper, await it, then push the matching compensation &quot;use step&quot; helper onto the stack. Throw `FatalError` for permanent business failures and normal errors for retryable failures. In the workflow catch block, run compensations in reverse order with `for (const compensate of compensations.reverse()) await compensate()`, then rethrow or return a failed status. Make each compensation idempotent. Verify successful completion, a fatal failure after multiple steps, and a replay/retry during rollback."
+/>
+
 Use the saga pattern when a business transaction spans multiple services and you need automatic rollback if any step fails. Each forward step registers a compensation, and on failure the workflow unwinds them in reverse order.
 
 ## When to use this

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

@@ -5,6 +5,10 @@ type: guide
 summary: Schedule future actions with durable sleep that survives cold starts, and race sleeps against hooks to let external events cancel the workflow early.
 ---
 
+<CopyPrompt
+  text="Create an interruptible scheduled workflow. Import `defineHook` and `sleep` from `workflow`. Define a cancellation hook such as `export const cancelDrip = defineHook<{ reason?: string }>()`. In an exported workflow function with &quot;use workflow&quot;, create the hook once, send the first message in a &quot;use step&quot; helper, then `await Promise.race([sleep(&quot;2d&quot;).then(() => false), cancelHook.then(() => true)])` before each delayed action. If the hook wins, return a cancelled status; if sleep wins, continue to the next step. Add an API route that calls `cancelDrip.resume(runIdOrToken, { reason })` or `resumeHook()` from `workflow/api`. Verify scheduled delivery, cancellation before sleep completes, and resume after server restart."
+/>
+
 Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
 
 <Callout type="info">

package/docs/cookbook/common-patterns/sequential-and-parallel.mdx

@@ -9,6 +9,10 @@ related:
   - /cookbook/common-patterns/scheduling
 ---
 
+<CopyPrompt
+  text="Compose these workflow steps with standard async/await patterns. In the exported &quot;use workflow&quot; function, chain dependent &quot;use step&quot; calls with sequential `await`; run independent steps concurrently by starting them without `await` and awaiting `Promise.all([...])`; and use `Promise.race([...])` to act on whichever promise settles first. These compose with durable primitives — race a step or a webhook from `createWebhook()` against `sleep()` from `workflow` for deadlines. Keep every step input and output serializable, and remember `Promise.race` does not cancel the losing branch — it keeps running — so side-effectful losers need idempotency keys. Verify sequential ordering, parallel execution, and both race outcomes."
+/>
+
 Workflows are written in plain async/await — there's no new control-flow API to learn. Sequential awaits chain steps that depend on each other, `Promise.all` runs independent steps in parallel, and `Promise.race` returns whichever finishes first. These compose with workflow primitives like [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) since those are also just promises.
 
 ## When to use this

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

@@ -10,6 +10,10 @@ related:
   - /cookbook/common-patterns/webhooks
 ---
 
+<CopyPrompt
+  text="Add a deadline to this slow workflow operation. Import `sleep` from `workflow`. In the exported &quot;use workflow&quot; function, race the operation against a durable sleep: `await Promise.race([slowStep(...), deadline(&quot;10m&quot;)])`, where `deadline` is a helper that awaits `sleep(duration)` and returns a sentinel value or throws. Branch on the winner: continue normally on success, run the fallback or compensation path on timeout. Use the same pattern to bound hooks and webhooks. `Promise.race` does not cancel the loser — the underlying step keeps running — so pass an `AbortSignal` into the step for cooperative cancellation and make non-idempotent side effects retry-safe with idempotency keys. Verify the fast path, the timeout path, and side-effect safety when the loser completes late."
+/>
+
 A common requirement is bounding how long a workflow waits for something to finish — a slow step, an external webhook, a human approval. Race the operation against a durable `sleep()` with `Promise.race()` — whichever finishes first wins, and the loser keeps running but its result is ignored.
 
 ## When to use this

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

@@ -5,6 +5,10 @@ type: guide
 summary: Create webhook endpoints that your workflow can await, process incoming requests in steps, and respond to the caller — all within durable workflow context.
 ---
 
+<CopyPrompt
+  text="Implement durable webhook handling for this workflow. Use `createWebhook()` from `workflow` inside the &quot;use workflow&quot; function when the workflow needs a generated callback URL. Use `createWebhook({ respondWith: &quot;manual&quot; })` when the workflow must validate the request before sending an HTTP response. Await the webhook request, pass the `RequestWithResponse` into a &quot;use step&quot; function for validation and side effects, and call `request.respondWith(Response.json(...))` on every code path. Race the webhook against `sleep()` for deadlines and throw `FatalError` for permanent timeout/failure paths. For fixed public callbacks or large payloads, use `defineHook()` plus `resumeHook()` from `workflow/api` and pass only a token or blob reference into the hook payload. Verify success response, invalid response, timeout, duplicate callback, and large-payload behavior."
+/>
+
 Use webhooks when external services push events to your application via HTTP callbacks. The workflow creates a webhook URL, suspends with zero compute cost, and resumes when a request arrives.
 
 ## When to use this

package/docs/cookbook/common-patterns/workflow-composition.mdx

@@ -10,6 +10,10 @@ related:
   - /docs/api-reference/workflow-api/get-run
 ---
 
+<CopyPrompt
+  text="Compose these workflows. For direct composition, `await` the child workflow function from the parent &quot;use workflow&quot; function — the child's steps flatten into the parent's event log and run as a single run sharing the parent's lifecycle. For independent background work, spawn the child with `start()` from `workflow/api` called directly in the workflow (in v5, `start()` is step-backed and records a deterministic step boundary) and return `run.runId` so callers can track it with `getRun()`. Choose flattening when the parent needs the child's result; choose background spawn when the child should have its own run, retries, and lifetime. Keep all inputs and outputs serializable. Verify flattened execution, background spawn with a separate runId, and replay determinism."
+/>
+
 Workflows can call other workflows. Choose between two composition modes depending on whether the parent needs the child's result inline (direct await) or wants to fire the child off as an independent run (background spawn). For massive fan-out with hook-based waiting and partial-failure handling, see [Child Workflows](/cookbook/advanced/child-workflows).
 
 ## When to use this

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

@@ -11,6 +11,10 @@ related:
   - /docs/api-reference/workflow-ai/durable-agent
 ---
 
+<CopyPrompt
+  text="Implement the durable AI SDK multi-turn pattern. Use `streamText`, `stepCountIs`, and `createUIMessageStreamResponse` from `ai`; `defineHook`, `getWritable`, and `getWorkflowMetadata` from `workflow`; and `start`/`getRun` from `workflow/api`. Put the model call in a `&quot;use step&quot;` function such as `runTurn(messages)` and pipe `result.toUIMessageStream()` to `getWritable<UIMessageChunk>()` with `{ preventClose: true }`. In the workflow, create one hook with `turnHook.create({ token: workflowRunId })`, loop over turns, and await the hook between user messages. Add an API route that starts a run on first message, stores/returns the run ID in `x-workflow-run-id`, resumes the hook for follow-up messages, reads from `run.getReadable({ startIndex })`, and handles stale run IDs by starting fresh. Wire the client transport to send `runId` with each request and verify first turn, follow-up turn, `/done`, and reconnect behavior."
+/>
+
 [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 the multi-turn loop durable: the conversation state, hooks, and per-turn responses survive restarts and timeouts. Note that in this pattern the durability boundary is the entire turn — individual tool calls inside a turn are **not** durable on their own (see [Pitfalls](#tools-are-not-individually-durable) below).
 
 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.

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

@@ -11,6 +11,10 @@ related:
   - /docs/api-reference/workflow-api/get-run
 ---
 
+<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. 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:

package/docs/cookbook/integrations/sandbox.mdx

@@ -10,6 +10,10 @@ related:
   - /docs/cookbook/agent-patterns/durable-agent
 ---
 
+<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

package/docs/deploying/world/local-world.mdx

@@ -34,7 +34,7 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Testing & Compatibility
 
-<WorldTestingPerformance />
+<WorldTestingPerformance worldId="local" />
 
 ## Configuration
 

package/docs/deploying/world/postgres-world.mdx

@@ -184,7 +184,7 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Testing & Compatibility
 
-<WorldTestingPerformance />
+<WorldTestingPerformance worldId="postgres" />
 
 ## Configuration
 

package/docs/deploying/world/vercel-world.mdx

@@ -85,7 +85,7 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Testing & Compatibility
 
-<WorldTestingPerformance />
+<WorldTestingPerformance worldId="vercel" />
 
 ## Configuration
 

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

@@ -11,6 +11,10 @@ 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
 
 ```

package/docs/errors/fetch-in-workflow.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/api-reference/workflow/fetch
 ---
 
+<CopyPrompt
+  text="Fix `fetch` usage inside workflow functions. Search workflow files for direct global `fetch(...)` calls and libraries such as AI SDK calls that use fetch. For simple HTTP calls inside a `&quot;use workflow&quot;` function, import `{ fetch }` from `workflow` and replace the global call. For SDK/client calls that need normal Node.js or provider behavior, move the call into a helper function with `&quot;use step&quot;` and call that step from the workflow. Keep all step inputs and outputs serializable. Verify the workflow starts and replays without the fetch-in-workflow error."
+/>
+
 This error occurs when you try to use `fetch()` directly in a workflow function, or when a library (like the AI SDK) tries to call `fetch()` under the hood.
 
 ## Error Message

package/docs/errors/hook-conflict.mdx

@@ -10,6 +10,10 @@ related:
   - /docs/api-reference/workflow/define-hook
 ---
 
+<CopyPrompt
+  text="Fix hook token conflicts. Find every `createHook({ token })` or typed hook creation site. If multiple waits can exist at the same time, include a unique stable discriminator in the token such as `${workflowRunId}:approval:${itemId}` or `${orderId}:${attempt}` instead of reusing one global token. If duplicate work should join an existing run, catch `HookConflictError` from `@workflow/errors`, read the conflicting run ID from the error/result if available, and use `getRun(runId)` plus `resumeHook()` from `workflow/api` to deliver the payload to the active run. Keep token generation deterministic across retries so replay does not create new hook identities. Verify two concurrent runs and a duplicate request no longer throw hook-conflict unexpectedly."
+/>
+
 This error occurs when you try to create a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows in your project.
 
 ## Error Message

package/docs/errors/node-js-module-in-workflow.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/how-it-works/understanding-directives
 ---
 
+<CopyPrompt
+  text="Fix Node.js module usage inside workflow functions. Search workflow files for imports or direct usage of Node-only APIs such as `fs`, `path`, `crypto`, `process`, `http`, or SDK clients. Remove those imports from files/functions that execute under `&quot;use workflow&quot;`. Create helper functions with `&quot;use step&quot;` for filesystem, crypto, environment, network, database, or SDK work, and call those helpers from the workflow. Keep the workflow function limited to deterministic orchestration, serializable values, `sleep`, hooks, and step calls. Verify the workflow starts without node-js-module-in-workflow errors."
+/>
+
 This error occurs when you try to import or use Node.js core modules (like `fs`, `http`, `crypto`, `path`, etc.) directly inside a workflow function.
 
 ## Error Message

package/docs/errors/serialization-failed.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="Fix Workflow serialization errors. Find the failing `start()` call, workflow argument, step return value, hook payload, or stream chunk. Replace non-serializable values such as class instances, functions, SDK clients, Response/Request objects, streams, database connections, Dates that need custom handling, Maps/Sets, or circular objects with plain JSON-compatible data, IDs, strings, numbers, booleans, arrays, and objects. Recreate runtime-only clients or objects inside `&quot;use step&quot;` helpers instead of passing them through the workflow log. For external resources, pass a stable ID or URL and load the resource inside the step. Add a test or local route call that serializes the same input/output path successfully."
+/>
+
 This error occurs when you try to pass non-serializable data between execution boundaries in your workflow. All data passed between workflow functions, step functions, and the workflow runtime must be serializable to persist in the event log.
 
 ## Error Message

package/docs/errors/start-invalid-workflow-function.mdx

@@ -11,6 +11,10 @@ related:
   - /docs/api-reference/workflow-next/with-workflow
 ---
 
+<CopyPrompt
+  text="Fix `start()` receiving an invalid workflow function. Find the function passed to `start()` from `workflow/api`. Ensure the target function is directly imported, exported from its workflow file, and contains the literal `&quot;use workflow&quot;` directive at the top of the function body. Do not pass wrapper callbacks like `start(async () => workflowFn())`; call `start(workflowFn, [args])`. Verify the framework integration is configured (`withWorkflow()` in Next.js, `workflow()`/`workflowPlugin()` in Vite/Astro/SvelteKit, `workflow/nitro`, `workflow/nuxt`, or `@workflow/nest` as appropriate) and that the workflow file is inside a transformed directory. Add a local route/test that calls `start(workflowFn, args)` and confirms a run is created."
+/>
+
 This error occurs when `start()` receives a function that does not have Workflow SDK's generated workflow metadata. In practice, that usually means the function is missing `"use workflow"` or the file was never transformed by your framework integration.
 
 ## Error Message

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

@@ -9,6 +9,10 @@ related:
   - /docs/api-reference/workflow/sleep
 ---
 
+<CopyPrompt
+  text="Fix timer usage inside workflow functions. Search `&quot;use workflow&quot;` functions for `setTimeout`, `setInterval`, `timers/promises`, polling loops, or `AbortSignal.timeout()`. Replace workflow delays with `await sleep(&quot;5s&quot;)`, `await sleep(&quot;24h&quot;)`, or `await sleep(date)` from `workflow`. For polling, use a workflow loop that calls a `&quot;use step&quot;` helper to check external state and then `await sleep(...)` between attempts. If a step itself needs a short in-process delay, keep that timer inside the `&quot;use step&quot;` function only. Verify the workflow can replay and resume after the durable sleep."
+/>
+
 This error occurs when you try to use `setTimeout()`, `setInterval()`, or related timing functions directly inside a workflow function.
 
 ## Error Message

package/docs/errors/webhook-response-not-sent.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/api-reference/workflow/create-webhook
 ---
 
+<CopyPrompt
+  text="Fix webhook-response-not-sent errors. Find `createWebhook({ respondWith: &quot;manual&quot; })` usage. In the workflow, await the webhook request and pass the `RequestWithResponse` into a `&quot;use step&quot;` helper for validation and side effects. In every success, validation failure, catch, and early-return branch, call `await request.respondWith(new Response(...))` or `await request.respondWith(Response.json(...))` exactly once before the webhook completes. If manual control is not needed, remove `respondWith: &quot;manual&quot;` or use a static `Response` option. Add tests or local webhook calls for success, invalid input, and thrown-error paths."
+/>
+
 This error occurs when a webhook is configured with `respondWith: "manual"` but the workflow does not send a response using `request.respondWith()` before the webhook execution completes.
 
 ## Error Message

package/docs/getting-started/astro.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Astro app, run `npm i workflow`. In `astro.config.mjs`, import `workflow` from `workflow/astro` and add `integrations: [workflow()]`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `src/workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers. Add `src/pages/api/signup.ts` exporting `POST: APIRoute` that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, returns `Response.json`, and sets `prerender = false`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:4321/api/signup`, and inspect with `npx workflow inspect runs`."
+/>
+
 This guide will walk through setting up your first workflow in an Astro app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 ---

package/docs/getting-started/express.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Express app, run `npm i workflow express nitro rollup` and, if using TypeScript, `npm i -D @types/express`. Create `nitro.config.ts` with `modules: [&quot;workflow/nitro&quot;]`, `vercel: { entryFormat: &quot;node&quot; }`, and `routes: { &quot;/**&quot;: { handler: &quot;./src/index.ts&quot;, format: &quot;node&quot; } }`. Add package scripts `dev: &quot;nitro dev&quot;` and `build: &quot;nitro build&quot;`. Create `workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add `src/index.ts` with Express JSON middleware, POST `/api/signup`, and `start(handleUserSignup, [email])` from `workflow/api`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 This guide will walk through setting up your first workflow in an Express app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 ---

package/docs/getting-started/fastify.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Fastify app, run `npm i workflow fastify nitro rollup` and, if using TypeScript, `npm i -D @types/node typescript`. Create `nitro.config.ts` with `modules: [&quot;workflow/nitro&quot;]`, `vercel: { entryFormat: &quot;node&quot; }`, and `routes: { &quot;/**&quot;: { handler: &quot;./src/index.ts&quot;, format: &quot;node&quot; } }`. Add package scripts `dev: &quot;nitro dev&quot;` and `build: &quot;nitro build&quot;`. Create `workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add `src/index.ts` with a Fastify app, POST `/api/signup`, `start(handleUserSignup, [email])`, `await app.ready()`, and an exported request handler. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow inspect runs --web`."
+/>
+
 This guide will walk through setting up your first workflow in a Fastify app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 ---

package/docs/getting-started/hono.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Hono app, run `npm i workflow nitro rollup`. Create `nitro.config.ts` with `modules: [&quot;workflow/nitro&quot;]` and `routes: { &quot;/**&quot;: &quot;./src/index.ts&quot; }`. Add package scripts `dev: &quot;nitro dev&quot;` and `build: &quot;nitro build&quot;`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `workflows/user-signup.ts` with `handleUserSignup(email)`, `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers. Add `src/index.ts` with a Hono app, POST `/api/signup`, `start(handleUserSignup, [email])` from `workflow/api`, and JSON response. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>

package/docs/getting-started/nestjs.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this NestJS app, run `npm i workflow @workflow/nest` and `npm i -D @swc/cli @swc/core`. Configure `nest-cli.json` with `compilerOptions.builder: &quot;swc&quot;` and `deleteOutDir: true`. Run `npx @workflow/nest init`, add `.swcrc` to `.gitignore`, and set package scripts `prebuild: &quot;npx @workflow/nest init --force&quot;` and `start:dev: &quot;npx @workflow/nest init --force && nest start --watch&quot;`. Import `WorkflowModule.forRoot()` from `@workflow/nest` in `src/app.module.ts` (use `{ moduleType: &quot;commonjs&quot;, distDir: &quot;dist&quot; }` if compiling CommonJS). Create `src/workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add a `POST /signup` controller method that reads `email`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns JSON. Run `npm run start:dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 This guide will walk through setting up your first workflow in a NestJS app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 <Callout>

package/docs/getting-started/next.mdx

@@ -10,6 +10,10 @@ related:
   - /docs/deploying/world/vercel-world
 ---
 
+<CopyPrompt
+  text="In this Next.js app, run `npm i workflow`. Wrap `next.config.ts` with `withWorkflow` from `workflow/next`. If the app has `proxy.ts` or middleware, exclude `.well-known/workflow/` from its matcher. Add `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helper functions that create a user, send a welcome email, and send an onboarding email. Add `app/api/signup/route.ts` with a POST handler that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns JSON. Run `npm run dev`, trigger `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>

package/docs/getting-started/nitro.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Nitro app, run `npm i workflow`. In `nitro.config.ts`, use `defineConfig` from `nitro`, set `serverDir: &quot;./server&quot;`, and add `modules: [&quot;workflow/nitro&quot;]`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `workflows/user-signup.ts` with `handleUserSignup(email)`, `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers. Add `server/api/signup.post.ts` using `defineEventHandler` from `nitro/h3` and `start` from `workflow/api` to start the workflow from `{ email }`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, then inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>

package/docs/getting-started/nuxt.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Nuxt app, run `npm i workflow`. In `nuxt.config.ts`, add `modules: [&quot;workflow/nuxt&quot;]` and keep `compatibilityDate: &quot;latest&quot;`. Create `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers that create a user and send emails. Add `server/api/signup.post.ts` using `defineEventHandler` from `h3` or `nitro/h3` and `start` from `workflow/api` to read `{ email }` and start the workflow. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>

package/docs/getting-started/python.mdx

@@ -10,6 +10,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Python project, run `pip install vercel`. Add `vercel.json` with `experimentalServices.ai_content_workflow.type = &quot;worker&quot;`, `entrypoint = &quot;app/workflows/ai_content_workflow.py&quot;`, and `topics = [&quot;__wkf_*&quot;]`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows()`. Create `app/workflows/ai_content_workflow.py` importing `wf`, define `@wf.workflow async def ai_content_workflow(*, topic: str)`, and call step functions such as `generate_draft` and `summarize_draft`. Mark step functions with `@wf.step`, use `await workflow.sleep(&quot;7 days&quot;)` for durable delays where needed, and use a `workflow.BaseHook` Pydantic model plus `.wait(token=...)` and `.resume(token)` for external approval events. Verify the worker entrypoint and route names match the project."
+/>
+
 <Callout type="warn">
 The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python?language=py).
 </Callout>

package/docs/getting-started/sveltekit.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this SvelteKit app, run `npm i workflow`. In `vite.config.ts`, import `workflowPlugin` from `workflow/sveltekit` and add it to `plugins` with `sveltekit()`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers that create a user and send emails. Add `src/routes/api/signup/+server.ts` with a POST `RequestHandler` that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns `json({ message: &quot;User signup workflow started&quot; })`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:5173/api/signup`, then inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>

package/docs/getting-started/tanstack-start.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this TanStack Start app, run `npm i workflow`. In `vite.config.ts`, import `workflow` from `workflow/vite` and add `workflow()` first in the existing `plugins` array before `tanstackStart()`, `nitro()`, or other plugins. Add `{ &quot;name&quot;: &quot;workflow&quot; }` to `compilerOptions.plugins` in `tsconfig.json` if TypeScript is used. Create `src/workflows/user-signup.ts` with `handleUserSignup(email)`, `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add `src/routes/api/signup.ts` using `createFileRoute(&quot;/api/signup&quot;)`, a POST server handler, `start` from `workflow/api`, and `json` from `@tanstack/react-start`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 This guide will walk through setting up your first workflow in a TanStack Start app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 ---

package/docs/getting-started/vite.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Vite app, run `npm i workflow nitro`. In `vite.config.ts`, import `nitro` from `nitro/vite`, `workflow` from `workflow/vite`, and configure `plugins: [nitro(), workflow()]` plus `nitro: { serverDir: &quot;./&quot; }`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add `api/signup.post.ts` using `defineEventHandler` from `nitro/h3` and `start` from `workflow/api`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 This guide will walk through setting up your first workflow in a Vite app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 ---

package/docs/migration-guides/migrating-from-aws-step-functions.mdx

@@ -14,6 +14,10 @@ related:
   - /docs/deploying/world/vercel-world
 ---
 
+<CopyPrompt
+  text="Replace this AWS Step Functions state machine with Workflow SDK. Run `npm i workflow`. Translate the ASL state machine into an exported async TypeScript function with `&quot;use workflow&quot;`. Move each Lambda/Task side effect into a helper function with `&quot;use step&quot;`. Replace Wait states with `sleep()` from `workflow`. Replace callback tokens with `defineHook()` plus `resumeHook()` from `workflow/api`, or `createWebhook()` for HTTP callbacks. Replace Parallel and Map states with `Promise.all`, bounded batching, or child workflow runs started with `start()`. Replace Retry/Catch rules with normal errors, `RetryableError`, and `FatalError`. Add an API route or server function that starts the workflow with `start(workflowFn, args)` and verify it against the previous state machine behavior."
+/>
+
 Move an AWS Step Functions state machine to the Workflow SDK by replacing JSON state definitions with TypeScript functions. This guide shows the direct mapping between ASL states and Workflow SDK primitives.
 
 <Callout type="info">

package/docs/migration-guides/migrating-from-inngest.mdx

@@ -14,6 +14,10 @@ related:
   - /docs/deploying/world/vercel-world
 ---
 
+<CopyPrompt
+  text="Migrate this Inngest code to Workflow SDK. Run `npm i workflow`. Replace each `inngest.createFunction` handler with an exported async function that contains `&quot;use workflow&quot;`. Replace each `step.run()` callback with a helper function that contains `&quot;use step&quot;`. Replace `step.sleep()` with `sleep()` from `workflow`. Replace event waits with `defineHook()` or `createWebhook()` from `workflow`, and resume them from server routes with `resumeHook()` or webhook requests. Start runs from API routes or server code with `start(workflowFn, args)` from `workflow/api`, and use `getRun(runId)` where callers need status, streams, cancellation, or results. Preserve retries by throwing normal errors for retryable failures and `FatalError` for permanent failures. Add a local test or route call that starts the migrated workflow and verifies the same observable behavior as the Inngest function."
+/>
+
 <Callout type="info">
 Install the Workflow SDK migration skill:
 

package/docs/migration-guides/migrating-from-temporal.mdx

@@ -14,6 +14,10 @@ related:
   - /docs/deploying/world/vercel-world
 ---
 
+<CopyPrompt
+  text="Refactor this Temporal TypeScript code to Workflow SDK. Run `npm i workflow`. Replace Temporal workflow functions with exported async functions containing `&quot;use workflow&quot;`. Replace Activities with helper functions containing `&quot;use step&quot;`. Replace timers with `sleep()` from `workflow`. Replace Signals with `defineHook()` plus `resumeHook()` from `workflow/api`, or `createWebhook()` when an HTTP callback URL is needed. Replace Child Workflows with `start(childWorkflow, args)` and coordinate completion with hooks or `getRun()`. Remove Temporal workers; instead expose API routes or server functions that call `start()` and `getRun()` from `workflow/api`. Preserve idempotency and retries with normal errors, `RetryableError`, and `FatalError`, then add a verification path for each migrated workflow."
+/>
+
 <Callout type="info">
 Install the Workflow SDK migration skill:
 

package/docs/migration-guides/migrating-from-trigger-dev.mdx

@@ -14,6 +14,10 @@ related:
   - /docs/deploying/world/vercel-world
 ---
 
+<CopyPrompt
+  text="Convert this trigger.dev setup to Workflow SDK. Run `npm i workflow`. Replace each `task()` or job entrypoint with an exported async workflow function containing `&quot;use workflow&quot;`. Replace trigger.dev task bodies that do side effects with `&quot;use step&quot;` helper functions. Replace waits/delays with `sleep()` from `workflow`. Replace external triggers or resume points with `defineHook()`/`resumeHook()` or `createWebhook()`. Replace run creation/status calls with `start()` and `getRun()` from `workflow/api`. Replace metadata/progress streaming with `getWritable()` from `workflow` when the UI needs live updates. Preserve retry semantics with normal errors, `RetryableError`, and `FatalError`, then add a local verification that starts the migrated workflow and checks the expected result or stream."
+/>
+
 <Callout type="info">
 Install the Workflow SDK migration skill:
 

package/docs/observability/attributes.mdx

@@ -1,21 +1,17 @@
 ---
 title: Attributes
-description: Attach experimental metadata to workflow runs for observability.
+description: Attach metadata to workflow runs for observability.
 type: reference
 summary: Add string attributes to a workflow run.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/observability
-  - /docs/api-reference/workflow/experimental-set-attributes
+  - /docs/api-reference/workflow/set-attributes
   - /docs/api-reference/workflow-errors/workflow-world-error
 ---
 
-<Callout type="warn">
-This feature is experimental and may change before the stable attributes API is released.
-</Callout>
-
-[`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI.
+[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI.
 In the future, you'll be able to search and filter runs by attributes.
 
 You can also seed any attributes directly when starting a run:
@@ -28,35 +24,35 @@ const run = await start(orderWorkflow, ["ord_123"], {
 ```
 
 ```typescript lineNumbers
-import { experimental_setAttributes } from "workflow"
+import { setAttributes } from "workflow"
 
 export async function orderWorkflow(orderId: string) {
   "use workflow"
 
-  await experimental_setAttributes({ // [!code highlight]
+  await setAttributes({ // [!code highlight]
     phase: "received", // [!code highlight]
     orderId, // [!code highlight]
   }) // [!code highlight]
 
   // ...work...
 
-  await experimental_setAttributes({ phase: "complete" }) // [!code highlight]
+  await setAttributes({ phase: "complete" }) // [!code highlight]
 }
 ```
 
 ## Usage
 
-Call [`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) from a `"use workflow"` function or a `"use step"` function. Plain application code is not supported because there is no active workflow run to attach attributes to.
+Call [`setAttributes`](/docs/api-reference/workflow/set-attributes) from a `"use workflow"` function or a `"use step"` function. Plain application code is not supported because there is no active workflow run to attach attributes to.
 
 Values must be strings. Pass `undefined` to remove a key:
 
 ```typescript lineNumbers
-import { experimental_setAttributes } from "workflow"
+import { setAttributes } from "workflow"
 
 export async function cleanupAttributes() {
   "use workflow"
 
-  await experimental_setAttributes({ staleKey: undefined }) // [!code highlight]
+  await setAttributes({ staleKey: undefined }) // [!code highlight]
 }
 ```
 
@@ -68,7 +64,7 @@ The run details panel in the observability UI shows the run's current attributes
 
 ![Run details panel showing the Attributes card with reserved keys badged](/screenshots/attributes/run-details-attributes.png)
 
-Each `experimental_setAttributes` call appears on the trace timeline as a diamond marker at the moment the attributes were written:
+Each `setAttributes` call appears on the trace timeline as a diamond marker at the moment the attributes were written:
 
 ![Trace timeline with attr_set diamond markers on the run row](/screenshots/attributes/trace-timeline.png)
 
@@ -76,12 +72,10 @@ Expanding an `attr_set` event — in the run sidebar or the Events tab — shows
 
 ![Expanded attr_set events showing changes and the writer](/screenshots/attributes/run-details-attr-set-events.png)
 
-## Experimental Behavior
-
-While attributes are experimental:
+## Behavior
 
 - Attributes require a World implementing spec version 4 or later.
 - Writes from workflow and step bodies append native `attr_set` events and immediately materialize `run.attributes`.
 - Storage errors surface rather than being silently ignored: transient errors on workflow-body writes are retried, and a write the World rejects as invalid (for example, exceeding the per-run attribute cap across multiple calls) fails the run with the validation error.
-- Step-body storage errors throw from `experimental_setAttributes` like any other step-side network write. Catch the error inside the step if the attribute is best-effort.
+- Step-body storage errors throw from `setAttributes` like any other step-side network write. Catch the error inside the step if the attribute is best-effort.
 - Reading and querying attributes is not available yet. A query API is planned.

package/docs/observability/tracing.mdx

@@ -42,6 +42,7 @@ No workflow-specific configuration is required. As soon as a tracer provider and
 | `step.execute <name>` | internal (inline) / consumer + root (queue-delivered) | a step function executes |
 | `http <method>` | client | the SDK calls the workflow backend (event reads/writes) |
 | `workflow.stream.write` | client | a stream chunk (or the stream close) is flushed to the backend |
+| `workflow.stream.flush` | client | a buffered batch of stream writes settles; back-dated to the batch's first `write()`, so its duration is the app-perceived batch latency (buffer dwell + RPC) |
 | `workflow.stream.read.connect` | client | a live stream read opens; the span covers dispatch → response headers (network connect) |
 | `workflow.stream.read` | client | a live stream read receives its first chunk; the span's duration is the end-to-end time-to-first-chunk (see `workflow.stream.read.ttfc_ms`) |
 
@@ -59,8 +60,9 @@ Stream spans are emitted by the SDK's world backend on the client that writes or
 | `workflow.trace.propagated` | Whether the invocation received trace context from the queue message. |
 | `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting — queue dwell plus any cold start. |
 | `workflow.stream.name` | The stream name, on stream write/read spans. |
-| `workflow.stream.operation` | The stream operation: `write`, `write_multi`, `close`, or `read`. |
+| `workflow.stream.operation` | The stream operation: `write`, `write_multi`, `close`, `read`, or `flush`. |
 | `workflow.stream.write.chunk_rtt` | Time between emissions of a chunk to the wire, and receiving the `ack` message for that chunk. |
+| `workflow.stream.flush.buffer_dwell_ms` | On `workflow.stream.flush`: time the batch's first chunk waited in the client-side write buffer (flush timer, run-ready barrier) before the request was dispatched. `workflow.stream.flush.chunks` / `.bytes` carry the batch shape. |
 | `workflow.stream.read.ttfc_ms` | Time between opening a read connection and observing and receiving the first chunk back. |
 
 ## Trace shape: one trace per invocation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.30",
+  "version": "5.0.0-beta.32",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.30",
-    "@workflow/cli": "5.0.0-beta.30",
-    "@workflow/core": "5.0.0-beta.30",
+    "@workflow/astro": "5.0.0-beta.32",
+    "@workflow/cli": "5.0.0-beta.32",
+    "@workflow/core": "5.0.0-beta.32",
     "@workflow/errors": "5.0.0-beta.10",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
     "@workflow/utils": "5.0.0-beta.6",
-    "@workflow/next": "5.0.0-beta.30",
-    "@workflow/nest": "5.0.0-beta.30",
-    "@workflow/nitro": "5.0.0-beta.30",
-    "@workflow/nuxt": "5.0.0-beta.30",
-    "@workflow/sveltekit": "5.0.0-beta.30",
-    "@workflow/rollup": "5.0.0-beta.30"
+    "@workflow/next": "5.0.0-beta.32",
+    "@workflow/nest": "5.0.0-beta.32",
+    "@workflow/nitro": "5.0.0-beta.32",
+    "@workflow/nuxt": "5.0.0-beta.32",
+    "@workflow/sveltekit": "5.0.0-beta.32",
+    "@workflow/rollup": "5.0.0-beta.32"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",