workflow 5.0.0-beta.9 → 5.0.1

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";
@@ -237,7 +199,7 @@ async function weatherAgentWorkflow(userQuery: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getWeather: {
         description: "Get current weather for a location",
@@ -260,7 +222,7 @@ async function weatherAgentWorkflow(userQuery: string) {
 }
 ```
 
-### Multiple Tools
+### Multiple tools
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -282,7 +244,7 @@ async function multiToolAgentWorkflow(userQuery: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getWeather: {
         description: "Get weather for a location",
@@ -309,7 +271,7 @@ async function multiToolAgentWorkflow(userQuery: string) {
 }
 ```
 
-### Multi-turn Conversation
+### Multi-turn conversation
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -327,7 +289,7 @@ async function multiTurnAgentWorkflow() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       searchProducts: {
         description: "Search for products",
@@ -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 }
   });
@@ -406,7 +368,7 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       scheduleTask: {
         description: "Pause the workflow for the specified number of seconds",
@@ -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:
 
@@ -443,7 +405,7 @@ async function agentWithPrepareStep(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "openai/gpt-4.1-mini", // Default model
+    model: "spacexai/grok-4.6", // Default model
     instructions: "You are a helpful assistant.",
   });
 
@@ -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:
 
@@ -497,7 +459,7 @@ async function agentWithMessageQueue(initialMessage: string) {
   });
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     instructions: "You are a helpful assistant.",
   });
 
@@ -524,7 +486,7 @@ async function agentWithMessageQueue(initialMessage: string) {
 }
 ```
 
-### Generation Settings
+### Generation settings
 
 Configure model generation parameters at the constructor or stream level:
 
@@ -538,7 +500,7 @@ async function agentWithGenerationSettings() {
 
   // Set default generation settings in constructor
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     temperature: 0.7,
     maxOutputTokens: 2000,
     topP: 0.9,
@@ -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:
 
@@ -586,7 +548,7 @@ async function multiStepAgent() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       searchWeb: {
         description: "Search the web for information",
@@ -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:
 
@@ -626,7 +588,7 @@ async function agentWithCallbacks() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   await agent.stream({
@@ -654,7 +616,7 @@ async function agentWithCallbacks() {
 }
 ```
 
-### Structured Output
+### Structured output
 
 Parse structured data from the LLM response using `Output.object`:
 
@@ -668,7 +630,7 @@ async function agentWithStructuredOutput() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   const result = await agent.stream({
@@ -689,7 +651,7 @@ async function agentWithStructuredOutput() {
 }
 ```
 
-### Tool Choice Control
+### Tool choice control
 
 Control when and which tools the model can use:
 
@@ -703,7 +665,7 @@ async function agentWithToolChoice() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       calculator: {
         description: "Perform calculations",
@@ -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:
 
@@ -771,7 +733,7 @@ async function agentWithContext(userId: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getUserData: {
         description: "Get user data",
@@ -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:
 
@@ -809,7 +771,7 @@ async function agentWithUIMessages(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     instructions: "You are a helpful assistant.",
   });
 
@@ -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:
 
@@ -857,7 +819,7 @@ async function agentWithToolInspection(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       checkOrderStatus: {
         description: "Check order status",
@@ -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:
 
@@ -912,7 +874,7 @@ async function agentWithTimeout(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   await agent.stream({
@@ -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

@@ -1,21 +1,21 @@
 ---
 title: "@workflow/ai"
-description: Helpers for building AI-powered workflows with the AI SDK.
+description: Deprecated AI integration APIs kept for existing Workflow applications.
 type: overview
-summary: Explore helpers for integrating AI SDK to build durable AI-powered workflows.
+summary: Migrate legacy @workflow/ai APIs to AI SDK's WorkflowAgent and WorkflowChatTransport.
 related:
   - /docs/ai
 ---
 
-Helpers for integrating AI SDK for building AI-powered workflows.
+The `@workflow/ai` package is deprecated in Workflow 5 and remains documented for existing applications. Build new agents with [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and [`WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) from `@ai-sdk/workflow`.
 
 ## 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`