workflow 5.0.0-beta.4 → 5.0.0-beta.41

package/docs/ai/index.mdx

@@ -3,6 +3,7 @@ title: Building Durable AI Agents
 description: Build AI agents that survive crashes, scale across requests, and maintain state with durable LLM tool-call loops.
 type: overview
 summary: Convert a basic AI chat app into a durable, resumable agent using Workflow SDK.
+manualCards: true
 related:
   - /docs/foundations/workflows-and-steps
   - /docs/foundations/streaming
@@ -63,7 +64,7 @@ In order to connect to an LLM, we'll need to set up an API key. The easiest way
 
 <Tab value="Gateway">
 
-Get a Gateway API key from the [Vercel Gateway](https://vercel.com/docs/gateway/api-reference/overview) page.
+Get a Gateway API key from the [Vercel Gateway](https://vercel.com/docs/ai-gateway/authentication) page.
 
 Then add it to your `.env.local` file:
 
@@ -92,7 +93,7 @@ Then modify your API endpoint to use the OpenAI provider:
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript title="app/api/chat/route.ts" lineNumbers
 // ...
-import { openai } from "@workflow/ai/openai"; // [!code highlight]
+import { openai } from "@ai-sdk/openai"; // [!code highlight]
 
 export async function POST(req: Request) {
   // ...
@@ -120,16 +121,17 @@ The core code that makes all of this happen is quite simple. Here's a breakdown
 
 <Tab value="API Route">
 
-Our API route makes a simple call to [AI SDK's `Agent` class](https://ai-sdk.dev/docs/agents/overview), which is a simple wrapper around [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
+Our API route makes a simple call to [AI SDK's `ToolLoopAgent` class](https://ai-sdk.dev/docs/agents/overview), which encapsulates the LLM call, tool execution loop, and stopping conditions on top of [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import { Experimental_Agent as Agent } from "ai";
-import type { LanguageModel } from "ai";
+import { ToolLoopAgent } from "ai";
+import type { UIMessage } from "ai";
+import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const agent = new Agent({ // [!code highlight]
-    model: gateway("bedrock/claude-4-5-haiku-20251001-v1"),
+  const agent = new ToolLoopAgent({ // [!code highlight]
+    model: "bedrock/claude-4-5-haiku-20251001-v1",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
@@ -231,7 +233,7 @@ Now that we have a basic agent using AI SDK, we can modify it to make it durable
 Add the Workflow SDK packages to your project:
 
 ```package-install
-npm i workflow @workflow/ai
+npm i workflow @ai-sdk/workflow
 ```
 
 and extend the Next.js config to transform your workflow code (see [Getting Started](/docs/getting-started/next) for more details).
@@ -257,18 +259,18 @@ Move the agent logic into a separate function, which will serve as our workflow
 
 {/* @skip-typecheck: Shows two mutually exclusive model options */}
 ```typescript title="workflows/chat/workflow.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent"; // [!code highlight]
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow"; // [!code highlight]
 import { getWritable } from "workflow"; // [!code highlight]
 import { tools } from "@/ai/tools";
-import { openai } from "@workflow/ai/openai";
-import type { ModelMessage, UIMessageChunk } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { convertToModelMessages, type UIMessage } from "ai";
 
-export async function chatWorkflow(messages: ModelMessage[]) {
+export async function chatWorkflow(messages: UIMessage[]) {
   "use workflow"; // [!code highlight]
 
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+  const writable = getWritable<ModelCallStreamPart>(); // [!code highlight]
 
-  const agent = new DurableAgent({ // [!code highlight]
+  const agent = new WorkflowAgent({ // [!code highlight]
 
     // If using AI Gateway, just specify the model name as a string:
     model: "bedrock/claude-4-5-haiku-20251001-v1", // [!code highlight]
@@ -280,8 +282,10 @@ export async function chatWorkflow(messages: ModelMessage[]) {
     tools: flightBookingTools,
   });
 
+  const modelMessages = await convertToModelMessages(messages); // [!code highlight]
+
   await agent.stream({ // [!code highlight]
-    messages,
+    messages: modelMessages,
     writable,
   });
 }
@@ -290,8 +294,9 @@ export async function chatWorkflow(messages: ModelMessage[]) {
 Key changes:
 
 - Add the `"use workflow"` directive to mark our Agent as a workflow function
-- Replaced `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`. This ensures that all calls to the LLM are executed as "steps", and results are aggregated within the workflow context (see [Workflows and Steps](/docs/foundations/workflows-and-steps) for more details on how workflows/steps are defined).
-- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output. This stream is persistent, and API endpoints can read from a run's stream at any time.
+- Replace the in-memory agent with [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) from `@ai-sdk/workflow`. This runs the agent loop inside a workflow, persists state across step boundaries, and lets tool executions marked with `"use step"` retry automatically.
+- Convert AI SDK `UIMessage` values to model messages inside the workflow before calling `agent.stream()`.
+- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output. `WorkflowAgent` writes `ModelCallStreamPart` chunks to this persistent stream, and API endpoints can read from a run's stream at any time.
 </Step>
 
 <Step>
@@ -300,19 +305,18 @@ Key changes:
 Remove the agent call that we just extracted, and replace it with a call to `start()` to run the workflow:
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import type { UIMessage } from "ai";
-import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
+import { createModelCallToUIChunkTransform } from "@ai-sdk/workflow";
+import { createUIMessageStreamResponse, type UIMessage } from "ai";
 import { start } from "workflow/api";
 import { chatWorkflow } from "@/workflows/chat/workflow";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = await convertToModelMessages(messages);
 
-  const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
+  const run = await start(chatWorkflow, [messages]); // [!code highlight]
 
   return createUIMessageStreamResponse({
-    stream: run.readable, // [!code highlight]
+    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()), // [!code highlight]
   });
 }
 ```
@@ -320,7 +324,8 @@ export async function POST(req: Request) {
 Key changes:
 
 - Call `start()` to run the workflow function. This returns a `Run` object, which contains the run ID and the readable stream (see [Starting Workflows](/docs/foundations/starting-workflows) for more details on the `Run` object).
-- Pass the `writable` to `agent.stream()` instead of returning a stream directly, ensuring all the Agent output is written to to the run's stream.
+- Pass the `writable` to `agent.stream()` instead of returning a stream directly, ensuring all the Agent output is written to the run's stream.
+- Pipe the readable stream through `createModelCallToUIChunkTransform()` so the raw model-call chunks become AI SDK UI message chunks before they are returned to the client.
 
 </Step>
 
@@ -377,7 +382,7 @@ export async function checkBaggageAllowance(
 
 With `"use step"`:
 
-- The tool execution runs in a separate step with full Node.js access. In production, each step is executed in a separate worker process, which scales automatically with your workload.
+- The tool execution runs as a durable step with full Node.js access. The combined runtime may execute it inline in the flow request or resume it through the workflow queue, and can scale queued work with your workload.
 - Failed tool calls are automatically retried (up to 3 times by default). See [Errors and Retries](/docs/foundations/errors-and-retries) for more details.
 - Each tool execution appears as a discrete step in observability tools. See [Observability](/docs/observability) for more details.
 </Step>
@@ -422,7 +427,7 @@ A complete example that includes all of the above, plus all of the "next steps"
 ## Related Documentation
 
 - [Tools](/docs/ai/defining-tools) - Patterns for defining tools for your agent
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) - AI SDK API for durable, resumable agents
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
 - [Streaming](/docs/foundations/streaming) - In-depth streaming guide
 - [Errors and Retries](/docs/foundations/errors-and-retries) - Error handling patterns

package/docs/ai/message-queueing.mdx

@@ -13,7 +13,7 @@ related:
 
 When using [multi-turn workflows](/docs/ai/chat-session-modeling#multi-turn-workflows), messages typically arrive between agent turns. The workflow waits at a hook, receives a message, then starts a new turn. But sometimes you need to inject messages *during* an agent's turn, before tool calls complete or while the model is reasoning.
 
-`DurableAgent`'s `prepareStep` callback enables this by running before each step in the agent loop, giving you a chance to inject queued messages into the conversation. `prepareStep` also allows you to modify the model choice and existing messages mid-turn, see AI SDK's [prepareStep callback](https://ai-sdk.dev/docs/agents/loop-control#prepare-step) for more details.
+`WorkflowAgent`'s `prepareStep` callback enables this by running before each step in the agent loop, giving you a chance to inject queued messages into the conversation. `prepareStep` also allows you to modify the model choice and existing messages mid-turn, see AI SDK's [prepareStep callback](https://ai-sdk.dev/docs/agents/loop-control#prepare-step) for more details.
 
 ## When to Use This
 
@@ -52,20 +52,20 @@ interface PrepareStepResult {
 Once you have a [multi-turn workflow](/docs/ai/chat-session-modeling#multi-turn-workflows), you can combine a message queue with `prepareStep` to inject messages that arrive during processing:
 
 ```typescript title="workflows/chat/index.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
 import { getWritable, getWorkflowMetadata } from "workflow";
 import { chatMessageHook } from "./hooks/chat-message";
 import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "./steps/tools";
-import type { UIMessageChunk, ModelMessage } from "ai";
+import type { ModelMessage } from "ai";
 
 export async function chat(initialMessages: ModelMessage[]) {
   "use workflow";
 
   const { workflowRunId: runId } = getWorkflowMetadata();
-  const writable = getWritable<UIMessageChunk>();
+  const writable = getWritable<ModelCallStreamPart>();
   const messageQueue: Array<{ role: "user"; content: string }> = []; // [!code highlight]
 
-  const agent = new DurableAgent({
+  const agent = new WorkflowAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
@@ -111,20 +111,20 @@ The `prepareStep` callback receives messages in `ModelMessage[]` format (with co
 You can also combine message queueing with the standard multi-turn pattern:
 
 ```typescript title="workflows/chat/index.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
 import { getWritable, getWorkflowMetadata } from "workflow";
 import { chatMessageHook } from "./hooks/chat-message";
-import type { UIMessageChunk, ModelMessage } from "ai";
+import type { ModelMessage } from "ai";
 
 export async function chat(initialMessages: ModelMessage[]) {
   "use workflow";
 
   const { workflowRunId: runId } = getWorkflowMetadata();
-  const writable = getWritable<UIMessageChunk>();
+  const writable = getWritable<ModelCallStreamPart>();
   const messages: ModelMessage[] = [...initialMessages];
   const messageQueue: Array<{ role: "user"; content: string }> = [];
 
-  const agent = new DurableAgent({ /* ... */ });
+  const agent = new WorkflowAgent({ /* ... */ });
   const hook = chatMessageHook.create({ token: runId });
 
   while (true) {
@@ -173,5 +173,5 @@ export async function chat(initialMessages: ModelMessage[]) {
 
 - [Chat Session Modeling](/docs/ai/chat-session-modeling) - Single-turn vs multi-turn patterns
 - [Building Durable AI Agents](/docs/ai) - Complete guide to creating durable agents
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) - AI SDK API for durable, resumable agents
 - [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook) - Hook configuration options

package/docs/ai/resumable-streams.mdx

@@ -12,6 +12,10 @@ related:
   - /docs/api-reference/workflow-api/get-run
 ---
 
+<Callout type="warn">
+`WorkflowChatTransport` now ships in AI SDK as a 1:1 port — import it from `@ai-sdk/workflow` (the `@workflow/ai` export is deprecated). See [Resumable Streaming with `WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) for the full reference.
+</Callout>
+
 When building chat interfaces, it's common to run into network interruptions, page refreshes, or serverless function timeouts, which can break the connection to an in-progress agent.
 
 Where a standard chat implementation would require the user to resend their message and wait for the entire response again, workflow runs are durable, and so are the streams attached to them. This means a stream can be resumed at any point, optionally only syncing the data that was missed since the last connection.
@@ -109,7 +113,7 @@ Replace the default transport in AI-SDK's `useChat` with [`WorkflowChatTransport
 "use client";
 
 import { useChat } from "@ai-sdk/react";
-import { WorkflowChatTransport } from "@workflow/ai"; // [!code highlight]
+import { WorkflowChatTransport } from "@ai-sdk/workflow"; // [!code highlight]
 import { useMemo, useState } from "react";
 
 export default function ChatPage() {
@@ -194,6 +198,10 @@ This avoids replaying potentially thousands of chunks and lets the UI render fas
 When using a negative `initialStartIndex`, the reconnection endpoint **must** return the `x-workflow-stream-tail-index` header (as shown in [Step 2](#add-a-stream-reconnection-endpoint) above). The transport uses this header to compute absolute chunk positions so that retries after a disconnect resume from the correct position. If the header is missing, the transport falls back to `startIndex: 0` (replaying the entire stream) and logs a warning.
 </Callout>
 
+### Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts (`text-*`, `reasoning-*`, `tool-input-*`) that must be opened with a `*-start` before any `*-delta` or `*-end`. A non-zero `startIndex` can land in the middle of an open part. See [`WorkflowChatTransport` → Mid-part resumes](/docs/api-reference/workflow-ai/workflow-chat-transport#mid-part-resumes) for how this is handled and an example of rewinding to a step boundary on the server.
+
 ## Related Documentation
 
 - [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options

package/docs/api-reference/index.mdx

@@ -17,9 +17,33 @@ All the functions and primitives that come with Workflow SDK by package.
     <Card title="workflow/api" href="/docs/api-reference/workflow-api">
         API reference for runtime functions from the `workflow/api` package.
     </Card>
+    <Card title="workflow/runtime" href="/docs/api-reference/workflow-runtime">
+        Runtime functions for resolving the World instance and the low-level World SDK, including storage and analytics queries.
+    </Card>
+    <Card title="workflow/observability" href="/docs/api-reference/workflow-observability">
+        Utilities to hydrate step I/O, parse display names, and decrypt workflow data.
+    </Card>
     <Card title="workflow/next" href="/docs/api-reference/workflow-next">
         Next.js integration for Workflow SDK that automatically configures bundling and runtime support.
     </Card>
+    <Card title="workflow/nitro" href="/docs/api-reference/workflow-nitro">
+        Nitro module for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/nuxt" href="/docs/api-reference/workflow-nuxt">
+        Nuxt module for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/sveltekit" href="/docs/api-reference/workflow-sveltekit">
+        SvelteKit Vite plugin for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/astro" href="/docs/api-reference/workflow-astro">
+        Astro integration for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/vite" href="/docs/api-reference/workflow-vite">
+        Standalone Vite plugin for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/nest" href="/docs/api-reference/workflow-nest">
+        NestJS module for workflow bundling and runtime support.
+    </Card>
     <Card title="workflow/errors" href="/docs/api-reference/workflow-errors">
         Semantic error types for handling workflow storage backend failures.
     </Card>

package/docs/api-reference/meta.json

@@ -4,7 +4,15 @@
     "workflow-globals",
     "workflow",
     "workflow-api",
+    "workflow-runtime",
+    "workflow-observability",
     "workflow-next",
+    "workflow-nitro",
+    "workflow-nuxt",
+    "workflow-sveltekit",
+    "workflow-astro",
+    "workflow-vite",
+    "workflow-nest",
     "workflow-errors",
     "workflow-serde",
     "workflow-ai",

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

@@ -11,7 +11,6 @@ The `@workflow/vitest` package provides a Vitest plugin and test helpers for run
 
 Returns a Vite plugin array that handles SWC transforms, bundle building, and in-process handler registration automatically.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -22,6 +21,29 @@ export default defineConfig({
 });
 ```
 
+Pass a [`WorkflowTestOptions`](#workflowtestoptions) object when your project uses a non-standard layout — for example, a monorepo where `workflows/` does not live at the Vitest config's directory, or when the default `.workflow-data` / `.workflow-vitest` output locations need to move. The plugin forwards these paths to `buildWorkflowTests()` and `setupWorkflowTests()` through Vitest's per-project provided context, so each Vitest workspace project stays isolated.
+
+
+```typescript
+import { defineConfig } from "vitest/config";
+import { workflow } from "@workflow/vitest";
+
+export default defineConfig({
+  plugins: [
+    workflow({
+      cwd: "./apps/api",
+      rootDir: "./apps/api/test-artifacts",
+    }),
+  ],
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options?` | `WorkflowTestOptions` | Optional configuration |
+
 **Returns:** `Plugin[]`
 
 ## Setup Functions
@@ -30,7 +52,6 @@ export default defineConfig({
 
 Builds workflow and step bundles to disk. Called automatically by the `workflow()` plugin in `globalSetup`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { buildWorkflowTests } from "@workflow/vitest";
@@ -48,11 +69,10 @@ export async function setup() {
 
 ### `setupWorkflowTests()`
 
-Sets up an in-process workflow runtime in each test worker. Imports pre-built bundles, creates a [Local World](/docs/worlds/local) instance with direct handlers, and sets it as the global world. Clears all workflow data on each invocation for full test isolation.
+Sets up an in-process workflow runtime in each test worker. Imports pre-built bundles, creates a [Local World](/worlds/local) instance with direct handlers, and sets it as the global world. Clears all workflow data on each invocation for full test isolation.
 
 Called automatically by the `workflow()` plugin in `setupFiles`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { beforeAll, afterAll } from "vitest";
@@ -83,7 +103,10 @@ Tears down the workflow test world. Clears the global world and closes the Local
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `cwd` | `string` | `process.cwd()` | The working directory of the project (where `workflows/` lives) |
+| `cwd` | `string` | `process.cwd()` | The working directory of the project (where `workflows/` lives). Relative paths resolve against `process.cwd()`. |
+| `rootDir` | `string` | same as `cwd` | Root directory used for default test artifacts. When set, `dataDir` and `outDir` default to `<rootDir>/.workflow-data` and `<rootDir>/.workflow-vitest`. Relative paths resolve against `cwd`. |
+| `dataDir` | `string` | `<rootDir>/.workflow-data` | Directory for workflow runtime data written by the test world. Relative paths resolve against `cwd`. |
+| `outDir` | `string` | `<rootDir>/.workflow-vitest` | Directory for generated workflow and step bundles. Relative paths resolve against `cwd`. |
 
 ## Test Helpers
 
@@ -91,7 +114,6 @@ Tears down the workflow test world. Clears the global world and closes the Local
 
 Polls the event log until the workflow has a pending `sleep()` call — one with a `wait_created` event but no corresponding `wait_completed` event. Returns the correlation ID of the pending sleep, which can be passed to [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to target a specific sleep.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForSleep } from "@workflow/vitest"; // [!code highlight]
@@ -120,7 +142,6 @@ await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlig
 
 Polls the hook list and event log until a hook matching the optional `token` filter exists that hasn't been received yet. Returns the matching hook object.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForHook } from "@workflow/vitest"; // [!code highlight]

package/docs/api-reference/workflow/create-hook.mdx

@@ -8,6 +8,7 @@ prerequisites:
 related:
   - /docs/api-reference/workflow/define-hook
   - /docs/api-reference/workflow/create-webhook
+  - /docs/foundations/idempotency
 ---
 
 Creates a low-level hook primitive that can be used to resume a workflow run with arbitrary payloads.
@@ -65,6 +66,8 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
+Use `hook.getConflict()` to check whether the hook token is already claimed by another hook, including one kept reserved after its run ends, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run).
+
 ## Examples
 
 ### Basic Usage
@@ -112,6 +115,81 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
+### Detecting Token Conflicts
+
+Use `hook.getConflict()` when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+async function processOrder(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({ // [!code highlight]
+    token: `order:${orderId}` // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active workflow run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  await chargeOrder(orderId);
+}
+```
+
+Because `createHook()` alone does not suspend the workflow, awaiting `hook.getConflict()` is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future `resumeHook()` call, await the hook itself or iterate it with `for await...of`.
+
+On a conflict, the resolved value is a `Run` handle for the run that owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
+
+<Callout type="info">
+Custom hook tokens are the recommended way to coordinate active workflow runs. Use a deterministic token from your domain, such as an order ID or conversation ID, create the hook near the beginning of the workflow, and check `await hook.getConflict()` before work that depends on owning the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
+### Keep a Token Unavailable After the Run Ends
+
+By default, another Hook can use the token after its workflow ends. Set `experimental_minRetention` to keep the token unavailable for at least a specific time after `createHook()` runs:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOwnedOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  const hook = createHook({ // [!code highlight]
+    token: `order:${orderId}`, // [!code highlight]
+    experimental_minRetention: "30d", // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict();
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  await processOwnedOrder(orderId);
+  return { status: "processed" as const };
+}
+```
+
+`experimental_minRetention` accepts the same values as [`sleep()`](/docs/api-reference/workflow/sleep): a duration string such as `"30d"`, a number of milliseconds, or an absolute `Date`. Durations start when `createHook()` runs.
+
+The Hook remains active until the workflow ends, even if the configured time passes first. Another Hook can use the token only after both the workflow has ended and the configured time has passed. For example, `"30d"` keeps the token unavailable for 29 more days if the workflow ends after 1 day. A workflow that runs for more than 30 days releases the token when it ends.
+
+After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) can still find the Hook until retention ends, but the Hook cannot be resumed.
+
+<Callout type="warn">
+`using` auto-disposes the Hook at scope exit, which releases the token immediately and defeats `experimental_minRetention`. Declare retained Hooks with `const` and let the runtime clean them up when the run ends.
+</Callout>
+
+<Callout type="warn">
+This option is experimental. Worlds can limit how long tokens are retained; see [World configuration](/docs/configuration/worlds) for each World's limit. If the configured World does not support minimum retention, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
+</Callout>
+
 ### Waiting for Multiple Payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.
@@ -195,3 +273,4 @@ This is equivalent to manually calling `dispose()` but ensures the hook is alway
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Higher-level HTTP webhook abstraction
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts

package/docs/api-reference/workflow/create-webhook.mdx

@@ -55,6 +55,7 @@ The returned `Webhook` object has:
 
 - `url`: The HTTP endpoint URL that external systems can call
 - `token`: The unique token identifying this webhook
+- `getConflict()`: A promise that resolves with the conflicting run if another active hook already owns this token, or `null` once the webhook endpoint has been registered
 - Implements `AsyncIterable<T>` for handling multiple requests, where `T` is `Request` (default) or `RequestWithResponse` (manual mode)
 
 When using `createWebhook({ respondWith: 'manual' })`, the resolved request type is `RequestWithResponse`, which extends the standard `Request` interface with a `respondWith(response: Response): Promise<void>` method for sending custom responses back to the caller.

package/docs/api-reference/workflow/define-hook.mdx

@@ -46,24 +46,21 @@ showSections={['parameters']}
 
 ### Returns
 
+`defineHook()` returns a `TypedHook<TInput, TOutput>`:
+
 <TSDoc
 definition={`
-interface DefineHook<T> {
-  /**
-
-* Creates a new hook with the defined payload type.
-  */
-  create: (options?: HookOptions) => Hook<T>;
-
-  /**
-
-* Resumes a hook by sending a payload with the defined type.
-   */
-  resume: (token: string, payload: T) => Promise<HookEntity | null>;
+interface TypedHook<TInput, TOutput> {
+  /** Creates the hook. Call inside a "use workflow" function. */
+  create(options?: HookOptions): Hook<TOutput>;
+  /** Resumes the hook from runtime code. Resolves to the resumed hook; throws HookNotFoundError if the token does not match an active hook. */
+  resume(token: string, payload: TInput): Promise<HookEntity>;
 }
-export default DefineHook;`}
+export default TypedHook;`}
 />
 
+`create()` is called inside a `"use workflow"` function to create the hook; `resume()` is called from runtime code (an API route or server action). When a `schema` is provided, `resume()` accepts the raw input type (`TInput`) and the workflow receives the validated and possibly transformed output type (`TOutput`); without a schema, `TOutput` defaults to `TInput`. `resume()` throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook — it does not return `null`.
+
 ## Examples
 
 ### Basic Type-Safe Hook Definition
@@ -93,24 +90,29 @@ export async function workflowWithApproval() {
 
 ### Resuming with Type Safety
 
-Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook.
+Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook. `resume()` resolves to the resumed hook and throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook.
 
 ```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors";
+
 // Use the same defined hook to resume
 export async function POST(request: Request) {
   const { token, approved, comment } = await request.json();
 
-  // Type-safe resumption - TypeScript ensures the payload matches
-  const result = await approvalHook.resume(token, { // [!code highlight]
-    approved, // [!code highlight]
-    comment, // [!code highlight]
-  }); // [!code highlight]
-
-  if (!result) {
-    return Response.json({ error: "Hook not found" }, { status: 404 });
+  try {
+    // Type-safe resumption - TypeScript ensures the payload matches
+    const hook = await approvalHook.resume(token, { // [!code highlight]
+      approved, // [!code highlight]
+      comment, // [!code highlight]
+    }); // [!code highlight]
+
+    return Response.json({ success: true, runId: hook.runId });
+  } catch (error) {
+    if (HookNotFoundError.is(error)) { // [!code highlight]
+      return Response.json({ error: "Hook not found" }, { status: 404 });
+    }
+    throw error;
   }
-
-  return Response.json({ success: true, runId: result.runId });
 }
 ```
 

package/docs/api-reference/workflow/fatal-error.mdx

@@ -29,16 +29,38 @@ async function fallibleStep() {
 
 ## API Signature
 
-### Parameters
+### Constructor
+
+`new FatalError(message)`
+
+| Parameter | Type     | Description        |
+| --------- | -------- | ------------------ |
+| `message` | `string` | The error message. |
+
+### Properties
 
 <TSDoc
 definition={`
-interface Error {
-  /**
-
-* The error message.
-   */
+interface FatalError {
+  /** The error message. */
   message: string;
+  /** Always true. Marks the error as non-retryable. */
+  fatal: boolean;
 }
-export default Error;`}
+export default FatalError;`}
 />
+
+### Static Methods
+
+#### `FatalError.is(value)`
+
+Type-safe check for `FatalError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { FatalError } from "workflow"
+declare const error: unknown; // @setup
+
+if (FatalError.is(error)) {
+  // error is typed as FatalError
+}
+```