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

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -1,61 +1,23 @@
 ---
 title: DurableAgent
-description: Create AI agents that maintain state, call tools, and handle interruptions gracefully.
+description: Deprecated DurableAgent API reference; use WorkflowAgent for new durable agents.
 type: reference
-summary: Use DurableAgent to build AI agents that maintain state across steps and survive interruptions.
+summary: "Deprecated: use AI SDK's WorkflowAgent instead of DurableAgent."
 prerequisites:
   - /docs/ai
 related:
   - /docs/ai/defining-tools
 ---
 
-The `DurableAgent` class enables you to create AI-powered agents that can maintain state across workflow steps, call tools, and gracefully handle interruptions and resumptions.
-
-Tool calls can be implemented as workflow steps for automatic retries, or as regular workflow-level logic utilizing core library features such as [`sleep()`](/docs/api-reference/workflow/sleep) and [Hooks](/docs/foundations/hooks).
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { UIMessageChunk } from "ai";
-
-async function getWeather({ city }: { city: string }) {
-  "use step";
-
-  return `Weather in ${city} is sunny`;
-}
-
-async function myAgent() {
-  "use workflow";
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a helpful weather assistant.",
-    temperature: 0.7,
-    tools: {
-      getWeather: {
-        description: "Get weather for a city",
-        inputSchema: z.object({ city: z.string() }),
-        execute: getWeather,
-      },
-    },
-  });
-
-  // The agent will stream its output to the workflow
-  // run's default output stream
-  const writable = getWritable<UIMessageChunk>();
+<Callout type="warn">
+`DurableAgent` is deprecated. Use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agents. See the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent).
+</Callout>
 
-  const result = await agent.stream({
-    messages: [{ role: "user", content: "How is the weather in San Francisco?" }],
-    writable,
-  });
+This reference is kept for existing applications that still import `DurableAgent` from `@workflow/ai/agent`. Do not use `DurableAgent` for new code.
 
-  // result contains messages, steps, and optional structured output
-  console.log(result.messages);
-}
-```
+For current examples and implementation guidance, see AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) docs. For legacy code, the API surface below documents the existing `DurableAgent` exports.
 
-## API Signature
+## API signature
 
 ### Class
 
@@ -163,7 +125,7 @@ import type { StreamTextOnAbortCallback } from "@workflow/ai/agent";
 export default StreamTextOnAbortCallback;`}
 />
 
-### Advanced Types
+### Advanced types
 
 #### ToolCallRepairFunction
 
@@ -195,30 +157,30 @@ import type { OutputSpecification } from "@workflow/ai/agent";
 export default OutputSpecification;`}
 />
 
-## Key Features
+## Key features
 
-- **Durable Execution**: Agents can be interrupted and resumed without losing state
-- **Flexible Tool Implementation**: Tools can be implemented as workflow steps for automatic retries, or as regular workflow-level logic
-- **Stream Processing**: Handles streaming responses and tool calls in a structured way
-- **Workflow Native**: Fully integrated with Workflow SDK for production-grade reliability
-- **AI SDK Parity**: Supports the same options as AI SDK's `streamText` including generation settings, callbacks, and structured output
+- **Durable execution**: Agents can be interrupted and resumed without losing state.
+- **Flexible tool implementation**: Tools can be implemented as workflow steps for automatic retries or as regular workflow-level logic.
+- **Stream processing**: Handles streaming responses and tool calls in a structured way.
+- **Workflow native**: Fully integrated with Workflow SDK for production reliability.
+- **AI SDK parity**: Supports the same options as AI SDK's `streamText`, including generation settings, callbacks, and structured output.
 
-## Good to Know
+## Good to know
 
-- Tools can be implemented as workflow steps (using `"use step"` for automatic retries), or as regular workflow-level logic
-- Tools can use core library features like `sleep()` and Hooks within their `execute` functions
-- The agent processes tool calls iteratively until completion or `maxSteps` is reached
-- **Default `maxSteps` is unlimited** - set a value to limit the number of LLM calls
-- The `stream()` method returns `{ messages, steps, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, step details, tool call details, optional structured output, and optionally accumulated UI messages
-- Use `collectUIMessages: true` to accumulate `UIMessage[]` during streaming, useful for persisting conversation state without re-reading the stream
-- The `prepareStep` callback runs before each step and can modify model, messages, generation settings, tool choice, and context
-- Generation settings (temperature, maxOutputTokens, etc.) can be set on the constructor and overridden per-stream call
-- Use `activeTools` to limit which tools are available for a specific stream call
-- The `onFinish` callback is called when all steps complete; `onAbort` is called if aborted
+- Tools can be implemented as workflow steps (using `"use step"` for automatic retries) or as regular workflow-level logic.
+- Tools can use core library features like `sleep()` and hooks within their `execute` functions.
+- The agent processes tool calls iteratively until completion or until `maxSteps` is reached.
+- **Default `maxSteps` is unlimited**: Set a value to limit the number of large language model (LLM) calls.
+- The `stream()` method returns `{ messages, steps, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, step details, tool call details, optional structured output, and optionally accumulated user interface (UI) messages.
+- Use `collectUIMessages: true` to accumulate `UIMessage[]` during streaming, which is useful for persisting conversation state without re-reading the stream.
+- The `prepareStep` callback runs before each step and can modify the model, messages, generation settings, tool choice, and context.
+- Generation settings (`temperature`, `maxOutputTokens`, and others) can be set on the constructor and overridden per-stream call.
+- Use `activeTools` to limit which tools are available for a specific stream call.
+- The `onFinish` callback is called when all steps complete; `onAbort` is called if aborted.
 
 ## Examples
 
-### Basic Agent with Tools
+### Basic agent with tools
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -260,7 +222,7 @@ async function weatherAgentWorkflow(userQuery: string) {
 }
 ```
 
-### Multiple Tools
+### Multiple tools
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -309,7 +271,7 @@ async function multiToolAgentWorkflow(userQuery: string) {
 }
 ```
 
-### Multi-turn Conversation
+### Multi-turn conversation
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -363,7 +325,7 @@ async function multiTurnAgentWorkflow() {
 }
 ```
 
-### Tools with Workflow Library Features
+### Tools with Workflow library features
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -385,7 +347,7 @@ async function requestApproval({ message }: { message: string }) {
   // Note: No "use step" for this tool call either,
   // since hooks are awaited at the workflow level
 
-  // Utilize a Hook for Human-in-the-loop approval
+  // Use a Hook for Human-in-the-loop approval
   const hook = approvalHook.create({
     metadata: { message }
   });
@@ -430,7 +392,7 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
 }
 ```
 
-### Dynamic Context with prepareStep
+### Dynamic context with prepareStep
 
 Use `prepareStep` to modify settings before each step in the agent loop:
 
@@ -474,7 +436,7 @@ async function agentWithPrepareStep(userMessage: string) {
 }
 ```
 
-### Message Injection with prepareStep
+### Message injection with prepareStep
 
 Inject messages from external sources (like hooks) before each LLM call:
 
@@ -524,7 +486,7 @@ async function agentWithMessageQueue(initialMessage: string) {
 }
 ```
 
-### Generation Settings
+### Generation settings
 
 Configure model generation parameters at the constructor or stream level:
 
@@ -562,7 +524,7 @@ async function agentWithGenerationSettings() {
 }
 ```
 
-### Limiting Steps with maxSteps
+### Limiting steps with maxSteps
 
 By default, the agent loops until completion. Use `maxSteps` to limit the number of LLM calls:
 
@@ -613,7 +575,7 @@ async function multiStepAgent() {
 }
 ```
 
-### Callbacks for Monitoring
+### Callbacks for monitoring
 
 Use callbacks to monitor streaming progress, handle errors, and react to completion:
 
@@ -654,7 +616,7 @@ async function agentWithCallbacks() {
 }
 ```
 
-### Structured Output
+### Structured output
 
 Parse structured data from the LLM response using `Output.object`:
 
@@ -689,7 +651,7 @@ async function agentWithStructuredOutput() {
 }
 ```
 
-### Tool Choice Control
+### Tool choice control
 
 Control when and which tools the model can use:
 
@@ -752,7 +714,7 @@ async function agentWithToolChoice() {
 }
 ```
 
-### Passing Context to Tools
+### Passing context to tools
 
 Use `experimental_context` to pass shared context to tool executions:
 
@@ -796,7 +758,7 @@ async function agentWithContext(userId: string) {
 }
 ```
 
-### Collecting UI Messages
+### Collecting UI messages
 
 Use `collectUIMessages` to accumulate `UIMessage[]` during streaming. This is useful when you need to persist the conversation without re-reading the run's output stream:
 
@@ -838,7 +800,7 @@ async function saveConversation(messages: UIMessage[]) {
 The `uiMessages` property is only available when `collectUIMessages` is set to `true`. When disabled, `uiMessages` is `undefined`.
 </Callout>
 
-### Machine-Readable Tool Results
+### Machine-readable tool results
 
 `stream()` returns tool call information you can inspect programmatically. Compare `toolCalls` with `toolResults` to find unresolved tool calls that need client-side handling:
 
@@ -895,7 +857,7 @@ async function agentWithToolInspection(userMessage: string) {
 `toolCalls` and `toolResults` reflect the *last step* of the agent loop. Tools without an `execute` function will appear in `toolCalls` but not in `toolResults`, which is how you detect calls that need client-side handling.
 </Callout>
 
-### Aborting Long-Running Streams
+### Aborting long-running streams
 
 Use `timeout` to abort a stream automatically after a fixed duration:
 
@@ -923,10 +885,10 @@ async function agentWithTimeout(userMessage: string) {
 }
 ```
 
-## See Also
+## See also
 
-- [Building Durable AI Agents](/docs/ai) - Complete guide to creating durable agents
-- [Queueing User Messages](/docs/ai/message-queueing) - Using prepareStep for message injection
-- [WorkflowChatTransport](/docs/api-reference/workflow-ai/workflow-chat-transport) - Transport layer for AI SDK streams
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow fundamentals
-- [AI SDK Loop Control](https://ai-sdk.dev/docs/agents/loop-control) - AI SDK's agent loop control patterns
+- [Building Durable AI Agents](/docs/ai): Complete guide to creating durable agents
+- [Queueing User Messages](/docs/ai/message-queueing): Using `prepareStep` for message injection
+- [WorkflowChatTransport](/docs/api-reference/workflow-ai/workflow-chat-transport): Transport layer for AI SDK streams
+- [Workflows and Steps](/docs/foundations/workflows-and-steps): Understanding workflow fundamentals
+- [AI SDK Loop Control](https://ai-sdk.dev/docs/agents/loop-control): AI SDK's agent loop control patterns

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

@@ -7,15 +7,15 @@ related:
   - /docs/ai
 ---
 
-Helpers for integrating AI SDK for building AI-powered workflows.
+The `@workflow/ai` package provides helpers for integrating AI SDK into AI-powered workflows.
 
 ## Classes
 
 <Cards>
     <Card title="DurableAgent" href="/docs/api-reference/workflow-ai/durable-agent">
-      A class for building durable AI agents that maintain state across workflow steps and handle tool execution with automatic retries.
+      Deprecated: use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent). Reference kept for existing `@workflow/ai/agent` imports.
     </Card>
     <Card title="WorkflowChatTransport" href="/docs/api-reference/workflow-ai/workflow-chat-transport">
-      A drop-in transport for the AI SDK for automatic reconnection in interrupted streams.
+      Deprecated: use AI SDK's [`WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) from `@ai-sdk/workflow`. Reference kept for existing `@workflow/ai` imports.
     </Card>
 </Cards>

package/docs/api-reference/workflow-ai/workflow-chat-transport.mdx

@@ -9,7 +9,11 @@ related:
   - /docs/ai/resumable-streams
 ---
 
-A chat transport implementation for the AI SDK that provides reliable message streaming with automatic reconnection to interrupted streams. This transport is a drop-in replacement for the default AI SDK transport, enabling seamless recovery from network issues, page refreshes, or Vercel Function timeouts.
+<Callout type="warn">
+`WorkflowChatTransport` from `@workflow/ai` is deprecated. AI SDK ships a 1:1 port, so use [`WorkflowChatTransport` from `@ai-sdk/workflow`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) instead. This reference is kept for existing applications that still import it from `@workflow/ai`.
+</Callout>
+
+`WorkflowChatTransport` is an AI SDK chat transport that automatically reconnects to interrupted streams. It replaces the default AI SDK transport and recovers from network issues, page refreshes, or Vercel Functions timeouts.
 
 <Callout>
 `WorkflowChatTransport` implements the [`ChatTransport`](https://ai-sdk.dev/docs/ai-sdk-ui/transport) interface from the AI SDK and is designed to work with workflow-based chat applications. It requires endpoints that return the `x-workflow-run-id` header to enable stream resumption.
@@ -34,7 +38,7 @@ export default function Chat() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Class
 
@@ -52,27 +56,27 @@ import type { WorkflowChatTransportOptions } from "@workflow/ai";
 export default WorkflowChatTransportOptions;`}
 />
 
-## Key Features
+## Key features
 
-- **Automatic Reconnection**: Automatically recovers from interrupted streams with configurable retry limits
-- **Workflow Integration**: Seamlessly works with workflow-based endpoints that provide the `x-workflow-run-id` header
-- **Customizable Requests**: Allows intercepting and modifying requests via `prepareSendMessagesRequest` and `prepareReconnectToStreamRequest`
-- **Stream Callbacks**: Provides hooks for tracking chat lifecycle via `onChatSendMessage` and `onChatEnd`
-- **Custom Fetch**: Supports custom fetch implementations for advanced use cases
+- **Automatic reconnection**: Recovers from interrupted streams with configurable retry limits.
+- **Workflow integration**: Works with workflow-based endpoints that provide the `x-workflow-run-id` header.
+- **Customizable requests**: Allows intercepting and modifying requests through `prepareSendMessagesRequest` and `prepareReconnectToStreamRequest`.
+- **Stream callbacks**: Provides hooks for tracking the chat lifecycle through `onChatSendMessage` and `onChatEnd`.
+- **Custom fetch**: Supports custom fetch implementations for advanced use cases.
 
-## Good to Know
+## Good to know
 
-- The transport expects chat endpoints to return the `x-workflow-run-id` header in the response to enable stream resumption
-- By default, the transport posts to `/api/chat` and reconnects via `/api/chat/{runId}/stream`
-- The `onChatSendMessage` callback receives the full response object, allowing you to extract and store the workflow run ID for session resumption
-- Stream interruptions are automatically detected when a "finish" chunk is not received in the initial response
-- The `maxConsecutiveErrors` option controls how many reconnection attempts are made before giving up (default: 3)
-- `initialStartIndex` (constructor option) sets the default chunk position for the **first** reconnection attempt (e.g. after a page refresh). Subsequent retries within the same reconnection loop always resume from the last received chunk. Negative values (e.g. `-20`) read from the end of the stream, which is useful for showing only recent output without replaying the full conversation. `startIndex` (per-call option on `reconnectToStream`) overrides `initialStartIndex` for a single reconnection
-- When using a negative `initialStartIndex`, the reconnection endpoint must return the `x-workflow-stream-tail-index` response header (via `readable.getTailIndex()`). The transport reads this header to compute absolute chunk positions for retries. Without it, startIndex is assumed to be 0, replaying the entire stream
+- The transport expects chat endpoints to return the `x-workflow-run-id` header in the response to enable stream resumption.
+- By default, the transport posts to `/api/chat` and reconnects through `/api/chat/{runId}/stream`.
+- The `onChatSendMessage` callback receives the full response object, allowing you to extract and store the workflow run ID for session resumption.
+- Stream interruptions are automatically detected when a `finish` chunk is not received in the initial response.
+- The `maxConsecutiveErrors` option controls how many reconnection attempts are made before giving up (default: 3).
+- `initialStartIndex` (constructor option) sets the default chunk position for the **first** reconnection attempt (for example, after a page refresh). Subsequent retries within the same reconnection loop always resume from the last received chunk. Negative values (for example, `-20`) read from the end of the stream, which is useful for showing only recent output without replaying the full conversation. `startIndex` (per-call option on `reconnectToStream`) overrides `initialStartIndex` for a single reconnection.
+- When using a negative `initialStartIndex`, the reconnection endpoint must return the `x-workflow-stream-tail-index` response header (through `readable.getTailIndex()`). The transport reads this header to compute absolute chunk positions for retries. Without it, `startIndex` is assumed to be `0`, replaying the entire stream.
 
 ## Examples
 
-### Basic Chat Setup
+### Basic chat setup
 
 ```typescript
 "use client";
@@ -115,7 +119,7 @@ export default function BasicChat() {
 }
 ```
 
-### With Session Persistence and Resumption
+### With session persistence and resumption
 
 ```typescript
 "use client";
@@ -183,7 +187,7 @@ export default function ChatWithResumption() {
 }
 ```
 
-### With Custom Request Configuration
+### With custom request configuration
 
 ```typescript
 "use client";
@@ -250,9 +254,48 @@ export default function ChatWithCustomConfig() {
 }
 ```
 
-## See Also
+## Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's user interface (UI) protocol groups chunks into logical parts: a `text-start` opens a text part that subsequent `text-delta`s extend and a `text-end` closes, and the same shape applies to `reasoning-*` and `tool-input-*`. The AI SDK client enforces that grammar: a `reasoning-delta` whose `reasoning-start` was never seen throws and breaks the chat.
+
+A non-zero `startIndex` (in particular a negative `initialStartIndex`) resolves to a chunk offset with no awareness of those part boundaries, so it can land in the middle of an open part. When that happens, `WorkflowChatTransport` will **drop chunks that reference a part it didn't see a start for** and log a one-time warning. The chat keeps working, but any partial part overlapping the resume cursor is discarded. Tool calls are an exception: `tool-input-available` / `tool-input-error` chunks are self-contained (they carry the full input), so a tool call is recovered as soon as one of those chunks appears in the resumed window. Only its streamed input deltas are lost.
+
+To preserve those partial parts, rewind to a step boundary on the server before returning the readable. `start-step` / `finish-step` chunks are the natural seams: no UI part is ever open across them. Sketch:
+
+{/*@skip-typecheck: incomplete code sample*/}
+
+```typescript title="app/api/chat/[id]/stream/route.ts"
+const run = getRun(id);
+const tailIndex = await run.getReadable().getTailIndex();
+
+let resolved = startIndex < 0
+  ? Math.max(0, tailIndex + 1 + startIndex)
+  : startIndex;
+
+if (startIndex !== 0) {
+  // Walk back from `resolved` to the most recent start-step (or chunk 0),
+  // capping the lookback so a single huge step can't trigger an unbounded scan.
+  const LOOKBACK = 200;
+  const probe = run.getReadable({ startIndex: Math.max(0, resolved - LOOKBACK) });
+  let i = Math.max(0, resolved - LOOKBACK);
+  let lastBoundary = i;
+  for await (const chunk of probe as unknown as AsyncIterable<{ type: string }>) {
+    if (i >= resolved) break;
+    if (chunk.type === "start-step") lastBoundary = i;
+    i++;
+  }
+  resolved = lastBoundary;
+}
+
+return createUIMessageStreamResponse({
+  stream: run.getReadable({ startIndex: resolved }),
+  headers: { "x-workflow-stream-tail-index": String(tailIndex) },
+});
+```
+
+## See also
 
-- [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - Building durable AI agents within workflows
-- [AI SDK `useChat` Documentation](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) - Using `useChat` with custom transports
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow fundamentals
-- ["flight-booking-app" Example](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) - An example application which uses `WorkflowChatTransport`
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Build durable, resumable AI agents (replaces `DurableAgent`)
+- [AI SDK `useChat` documentation](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat): Use `useChat` with custom transports
+- [Workflows and Steps](/docs/foundations/workflows-and-steps): Understand workflow fundamentals
+- [`flight-booking-app` example](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app): View an example application that uses `WorkflowChatTransport`

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -5,14 +5,26 @@ type: reference
 summary: Use getHookByToken to look up a hook's metadata and associated workflow run before resuming it.
 prerequisites:
   - /docs/foundations/hooks
+related:
+  - /docs/foundations/idempotency
 ---
 
 Retrieves a hook by its unique token, returning the associated workflow run information and any metadata that was set when the hook was created. This function is useful for inspecting hook details before deciding whether to resume a workflow.
 
+When `experimental_minRetention` is set, this function continues to return the Hook after its workflow ends until retention ends. That Hook cannot be resumed. Use `getRun(hook.runId)` to inspect the finished run.
+
 <Callout type="warn">
 `getHookByToken` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="info">
+`hook.metadata` is a getter that returns a Promise, so `await` it to read the value. Hydrating metadata can add extra network round trips, so that work is deferred to first access and the lookup itself stays a single read. Awaiting it on a hook with no metadata resolves `undefined` and performs no extra work, and repeat reads are free.
+</Callout>
+
+<Callout type="info">
+Looking up a deterministic hook token is useful in hook-based idempotency flows, but it is only an advisory check. If no hook exists yet, another request can still start the same workflow before your `start()` call registers its hook. Use the lookup to avoid obvious duplicate starts, and handle the 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 route the caller to the active owner. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getHookByToken } from "workflow/api";
 
@@ -23,7 +35,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -40,14 +52,14 @@ Returns a `Promise<Hook>` that resolves to:
 
 <TSDoc
 definition={`
-import type { Hook } from "@workflow/world";
+import type { Hook } from "workflow/api";
 export default Hook;`}
 showSections={["returns"]}
 />
 
 ## Examples
 
-### Basic Hook Lookup
+### Basic hook lookup
 
 Retrieve hook information before resuming:
 
@@ -62,7 +74,7 @@ export async function POST(request: Request) {
     const hook = await getHookByToken(token); // [!code highlight]
 
     console.log("Resuming workflow run:", hook.runId);
-    console.log("Hook metadata:", hook.metadata);
+    console.log("Hook metadata:", await hook.metadata); // [!code highlight]
 
     // Then resume the hook with the payload
     await resumeHook(token, data);
@@ -77,7 +89,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Validating Hook Before Resume
+### Validating hook before resume
 
 Use `getHookByToken` to validate hook ownership or metadata before resuming:
 
@@ -89,7 +101,8 @@ export async function POST(request: Request) {
 
   try {
     const hook = await getHookByToken(token); // [!code highlight]
-    const metadata = hook.metadata as { allowedUserId?: string } | undefined;
+    // `metadata` is a Promise, so awaiting it hydrates the stored value.
+    const metadata = (await hook.metadata) as { allowedUserId?: string } | undefined; // [!code highlight]
 
     // Validate that the hook metadata matches the user
     if (metadata?.allowedUserId !== userId) {
@@ -107,7 +120,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Checking Hook Environment
+### Checking hook environment
 
 Verify the hook belongs to the expected environment:
 
@@ -136,7 +149,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Logging Hook Information
+### Logging hook information
 
 Log hook details for debugging or auditing:
 
@@ -173,8 +186,9 @@ export async function POST(request: Request) {
 }
 ```
 
-## Related Functions
+## Related functions
 
-- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload.
-- [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
-- [`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.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Create a hook in a workflow.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts.

package/docs/api-reference/workflow-api/get-run.mdx

@@ -5,19 +5,25 @@ type: reference
 summary: Use getRun to check a workflow run's status and metadata without blocking on completion.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
-Retrieves the workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion, making it ideal for status checking and monitoring.
+Retrieves workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion.
 
 Use this function when you need to check workflow status, get timing information, or access workflow metadata without blocking on workflow completion.
 
+<Callout type="info">
+`getRun()` retrieves a run when you already have its `runId`. It does not look up runs by a business key. For retried requests that should route to one active workflow, use a deterministic hook token and [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). After a hook conflict, `HookConflictError.conflictingRunId` can be passed to `getRun()` to inspect, stream, or return the active owner. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getRun } from "workflow/api";
 
 const run = getRun("my-run-id");
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -41,7 +47,7 @@ showSections={["returns"]}
 
 #### WorkflowReadableStream
 
-`run.getReadable()` returns a `WorkflowReadableStream` — a standard `ReadableStream` extended with a `getTailIndex()` helper:
+`run.getReadable()` returns a `WorkflowReadableStream`, a standard `ReadableStream` extended with a `getTailIndex()` helper:
 
 <TSDoc
 definition={`
@@ -59,6 +65,16 @@ import type { WorkflowReadableStreamOptions } from "workflow/api";
 export default WorkflowReadableStreamOptions;`}
 />
 
+#### WorkflowRunWritableStreamOptions
+
+<TSDoc
+definition={`
+import type { WorkflowRunWritableStreamOptions } from "workflow/api";
+export default WorkflowRunWritableStreamOptions;`}
+/>
+
+Use `run.writable` for the default stream or `run.getWritable(options)` to configure it. See [Writing to another run's stream](/docs/foundations/streaming#writing-to-another-runs-stream) for lifecycle details.
+
 #### StopSleepOptions
 
 <TSDoc
@@ -77,7 +93,7 @@ export default StopSleepResult;`}
 
 ## Examples
 
-### Check if a Run Exists
+### Check if a run exists
 
 Use the `exists` getter to check whether a workflow run exists without throwing when the run is not found:
 
@@ -106,7 +122,7 @@ export async function GET(req: Request) {
 }
 ```
 
-### Basic Status Check
+### Basic status check
 
 Check the current status of a workflow run:
 
@@ -135,7 +151,7 @@ export async function GET(req: Request) {
 }
 ```
 
-### Wake Up a Sleeping Workflow
+### Wake up a sleeping workflow
 
 Interrupt pending `sleep()` calls to resume a workflow early. This is useful for testing workflows or building custom UIs that let users skip wait periods:
 
@@ -164,6 +180,25 @@ const { stoppedCount } = await run.wakeUp({
 });
 ```
 
-## Related Functions
+### Cancel a run
+
+Cancel a workflow run. You can pass an optional free-text `cancelReason` (up to 512 characters) that is recorded on the run's cancellation event and shown in the run detail view:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+  const run = getRun(runId);
+
+  await run.cancel({ cancelReason: "Superseded by a newer submission" }); // [!code highlight]
+
+  return Response.json({ cancelled: true });
+}
+```
+
+The options object is optional: `await run.cancel()` cancels the run without recording a reason.
+
+## Related functions
 
-- [`start()`](/docs/api-reference/workflow-api/start) - Start a new workflow and get its run ID.
+- [`start()`](/docs/api-reference/workflow-api/start): Start a new workflow and get its run ID.