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

package/docs/foundations/streaming.mdx

@@ -1,8 +1,8 @@
 ---
 title: Streaming
-description: Stream data in real-time to clients for progress updates and incremental content delivery.
+description: Stream data in real time to clients for progress updates and incremental content delivery.
 type: conceptual
-summary: Stream real-time data to clients without waiting for workflow completion.
+summary: Stream data to clients in real time without waiting for workflow completion.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
@@ -10,9 +10,9 @@ related:
   - /docs/ai/resumable-streams
 ---
 
-Workflows can stream data in real-time to clients without waiting for the entire workflow to complete. This enables progress updates, AI-generated content, log messages, and other incremental data to be delivered as workflows execute.
+Workflows can stream data to clients in real time without waiting for the entire workflow to complete. Clients can receive progress updates, AI-generated content, log messages, and other incremental data as workflows execute.
 
-## Getting Started with `getWritable()`
+## Getting started with `getWritable()`
 
 Every workflow run has a default writable stream that steps can write to using [`getWritable()`](/docs/api-reference/workflow/get-writable). Data written to this stream becomes immediately available to clients consuming the workflow's output.
 
@@ -38,7 +38,7 @@ export async function simpleStreamingWorkflow() {
 }
 ```
 
-### Consuming the Stream
+### Consuming the stream
 
 Use the `Run` object's `readable` property to consume the stream from your API route:
 
@@ -58,7 +58,31 @@ export async function POST() {
 
 When a client makes a request to this endpoint, they'll receive each message as it's written, without waiting for the workflow to complete.
 
-### Resuming Streams from a Specific Point
+### Avoiding function timeouts after client disconnects
+
+On Vercel, `run.readable` and `run.getReadable()` reconnect to Workflow's stream storage while the workflow is still running. By default, a client disconnect does not terminate the Vercel Function serving the stream. If a user closes the page or stops the request, the function can therefore keep reconnecting until it reaches its maximum duration and fails with `FUNCTION_INVOCATION_TIMEOUT`.
+
+For streaming routes using the Node.js runtime, opt in to [request cancellation](https://vercel.com/docs/functions/functions-api-reference#enable-cancellation) in `vercel.json`:
+
+```json filename="vercel.json"
+{
+  "functions": {
+    "app/api/stream/route.ts": {
+      "supportsCancellation": true
+    }
+  }
+}
+```
+
+Replace the function path with the path or glob for your streaming route. When the downstream client disconnects, Vercel terminates the matching function invocation instead of leaving its stream reader running. The workflow run and its durable stream continue independently, so the client can reconnect through another route invocation later.
+
+<Callout type="warn">
+Cancellation applies to every function matching the configured path or glob, even if the route does not listen to `request.signal`. Any other work in that invocation which is not wrapped in [`waitUntil`](https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#waituntil) or [`after`](https://nextjs.org/docs/app/api-reference/functions/after) can be lost. Only enable it for routes that are safe to terminate when their client disconnects.
+</Callout>
+
+This setting prevents abandoned stream readers from consuming the rest of a function invocation. It does not extend the function's maximum duration. An actively connected streaming response can still reach the configured limit, at which point the client should reconnect to the durable stream.
+
+### Resuming streams from a specific point
 
 Use `run.getReadable({ startIndex })` to resume a stream from a specific position. This is useful for reconnecting after timeouts or network interruptions:
 
@@ -85,7 +109,7 @@ export async function GET(
 }
 ```
 
-This allows clients to reconnect and continue receiving data from where they left off, rather than restarting from the beginning.
+Clients can reconnect and continue receiving data from where they left off instead of restarting from the beginning.
 
 `startIndex` also supports **negative values** to read relative to the end of the stream. For example, `startIndex: -5` starts 5 chunks before the current end. This is useful when you want to show the most recent output without reading the entire stream history.
 
@@ -103,31 +127,32 @@ If the absolute value exceeds the total number of chunks, reading starts from th
 Because streams are live and continue receiving chunks, negative `startIndex` values resolve to different absolute positions on each call. Accurate pagination over a live stream requires cursor-based access, which is not yet supported. Keep this in mind when building clients that paginate over stream data.
 </Callout>
 
-## Streams as Data Types
+## Streams as data types
 
-[`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow SDK makes serializable. These are not custom types - they follow the web standard - but Workflow SDK adds the ability to pass them between functions while maintaining their streaming capabilities.
+[`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow SDK makes serializable. Workflow SDK lets you pass these standard types between functions while maintaining their streaming capabilities.
 
 Unlike regular values that are fully serialized to the [event log](/docs/how-it-works/event-sourcing), streams maintain their streaming capabilities when passed between functions.
 
 **Key properties:**
+
 - Stream references can be passed between workflow and step functions
 - Stream data flows directly without being stored in the event log
 - Streams preserve their state across workflow suspension points
 
 <Callout type="info">
-**How Streams Persist Across Workflow Suspensions**
+**How streams persist across workflow suspensions**
 
-Streams in Workflow SDK are backed by persistent, resumable storage provided by the "world" implementation. This is what enables streams to maintain their state even when workflows suspend and resume:
+Persistent, resumable storage from the World implementation lets Workflow SDK streams maintain their state when workflows suspend and resume:
 
 - **Vercel deployments**: Streams are backed by a performant Redis-based stream
 - **Local development**: Stream chunks are stored in the filesystem
 </Callout>
 
-### Passing Streams as Arguments
+### Passing streams as arguments
 
-Since streams are serializable data types, you don't need to use the special [`getWritable()`](/docs/api-reference/workflow/get-writable). You can even wire your own streams through workflows, passing them as arguments from outside into steps.
+Because streams are serializable data types, you don't need to use [`getWritable()`](/docs/api-reference/workflow/get-writable). You can pass your own streams as arguments from outside a workflow into steps.
 
-Here's an example of passing a request body stream through a workflow to a step that processes it:
+The following example passes a request body stream through a workflow to a step that processes it:
 
 ```typescript title="app/api/upload/route.ts" lineNumbers
 import { start } from "workflow/api";
@@ -167,15 +192,15 @@ async function processInputStream(input: ReadableStream<Uint8Array>) {
 }
 ```
 
-## Important Limitation
+## Important limitation
 
 <Callout type="info">
-**Streams Cannot Be Used Directly in Workflow Context**
+**Streams cannot be used directly in workflow context**
 
 You cannot read from or write to streams directly within a workflow function. All stream operations must happen in step functions.
 </Callout>
 
-Workflow functions must be deterministic to support replay. Since streams bypass the [event log](/docs/how-it-works/event-sourcing) for performance, reading stream data in a workflow would break determinism - each replay could see different data. By requiring all stream operations to happen in steps, the framework ensures consistent behavior.
+Workflow functions must be deterministic to support replay. Streams bypass the [event log](/docs/how-it-works/event-sourcing) for performance, so reading stream data in a workflow would break determinism because each replay could see different data. Requiring all stream operations to happen in steps ensures consistent behavior.
 
 For more on determinism and replay, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
@@ -214,7 +239,7 @@ async function writeToStream(data: string) {
 }
 ```
 
-## Namespaced Streams
+## Namespaced streams
 
 Use `getWritable({ namespace: 'name' })` to create multiple independent streams for different types of data. This is useful when you want to separate logs, metrics, data outputs, or other distinct channels.
 
@@ -264,7 +289,7 @@ export async function multiStreamWorkflow() {
 }
 ```
 
-### Consuming Namespaced Streams
+### Consuming namespaced streams
 
 Use `run.getReadable({ namespace: 'name' })` to access specific streams:
 
@@ -289,9 +314,37 @@ export async function POST(request: Request) {
 }
 ```
 
-## Common Patterns
+## Writing to another run's stream
+
+`getRun(runId).getWritable()` appends to a stream owned by another run. This lets short-lived runs contribute to a long-lived holder run's stream using only its ID.
 
-### Progress Updates for Long-Running Tasks
+```typescript title="workflows/turn.ts" lineNumbers
+import { getRun } from "workflow/api";
+
+type SessionEvent = { turn: number; text: string };
+
+async function runTurn(holderRunId: string, turn: number) {
+  "use step";
+
+  const writable = getRun(holderRunId).getWritable<SessionEvent>(); // [!code highlight]
+  const writer = writable.getWriter();
+
+  await writer.write({ turn, text: "done" });
+  writer.releaseLock(); // [!code highlight]
+}
+```
+
+Pass `{ namespace: "name" }` to target a [namespaced stream](#namespaced-streams). The writable can also be forwarded through `start()` and into steps.
+
+<Callout type="warn">
+Contributors should call `releaseLock()`, which flushes pending writes. Calling `close()` closes the shared stream for every writer.
+</Callout>
+
+The API grants append access, not read access or additional authorization. The owning run controls the stream's lifecycle, and writes to an unknown run fail.
+
+## Common patterns
+
+### Progress updates for long-running tasks
 
 Send incremental progress updates to keep users informed during lengthy workflows:
 
@@ -345,29 +398,19 @@ export async function batchProcessingWorkflow(items: string[]) {
 }
 ```
 
-### Streaming AI Responses with `DurableAgent`
+### Streaming AI responses with `WorkflowAgent`
 
-Stream AI-generated content using [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai`. Tools can also emit progress updates to the same stream using [data chunks](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data#streaming-custom-data) with the [`UIMessageChunk`](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol) type from the AI SDK:
+Stream AI-generated content using AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) from `@ai-sdk/workflow`. The agent writes `ModelCallStreamPart` chunks to the workflow stream, and route handlers convert them to UI message chunks with `createModelCallToUIChunkTransform()` before returning the response:
 
 ```typescript title="workflows/ai-assistant.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
+import { tool } from "ai";
 import { getWritable } from "workflow";
 import { z } from "zod";
-import type { UIMessageChunk } from "ai";
 
 async function searchFlights({ query }: { query: string }) {
   "use step";
 
-  // Tools can emit progress updates to the stream
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-  const writer = writable.getWriter(); // [!code highlight]
-  await writer.write({ // [!code highlight]
-    type: "data-progress", // [!code highlight]
-    data: { message: `Searching flights for ${query}...` }, // [!code highlight]
-    transient: true, // [!code highlight]
-  }); // [!code highlight]
-  writer.releaseLock(); // [!code highlight]
-
   // ... search logic ...
   return { flights: [/* results */] };
 }
@@ -375,27 +418,28 @@ async function searchFlights({ query }: { query: string }) {
 export async function aiAssistantWorkflow(userMessage: string) {
   "use workflow";
 
-  const agent = new DurableAgent({
+  const agent = new WorkflowAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful flight assistant.",
+    instructions: "You are a helpful flight assistant.",
     tools: {
-      searchFlights: {
+      searchFlights: tool({
         description: "Search for flights",
         inputSchema: z.object({ query: z.string() }),
         execute: searchFlights,
-      },
+      }),
     },
   });
 
   // LLM response will be streamed to the run's writable
   await agent.stream({
     messages: [{ role: "user", content: userMessage }],
-    writable: getWritable<UIMessageChunk>(), // [!code highlight]
+    writable: getWritable<ModelCallStreamPart>(), // [!code highlight]
   });
 }
 ```
 
 ```typescript title="app/api/ai-assistant/route.ts" lineNumbers
+import { createModelCallToUIChunkTransform } from "@ai-sdk/workflow";
 import { createUIMessageStreamResponse } from "ai";
 import { start } from "workflow/api";
 import { aiAssistantWorkflow } from "./workflows/ai";
@@ -406,16 +450,16 @@ export async function POST(request: Request) {
   const run = await start(aiAssistantWorkflow, [message]);
 
   return createUIMessageStreamResponse({
-    stream: run.readable,
+    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()), // [!code highlight]
   });
 }
 ```
 
 <Callout type="info">
-For a complete implementation, see the [flight booking example](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) which demonstrates streaming AI responses with tool progress updates.
+For the full agent API and migration notes, see the [`WorkflowAgent` documentation](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent).
 </Callout>
 
-### Streaming Between Steps
+### Streaming between steps
 
 One step produces a stream and another step consumes it:
 
@@ -456,7 +500,7 @@ async function consumeData(readable: ReadableStream<number>) {
 }
 ```
 
-### Processing Large Files Without Memory Overhead
+### Processing large files without memory overhead
 
 Process large files by streaming chunks through transformation steps:
 
@@ -497,7 +541,11 @@ async function uploadResult(stream: ReadableStream<Uint8Array>) {
 }
 ```
 
-## Best Practices
+## Best practices
+
+**Batching and first-chunk latency:**
+
+Writes are flushed immediately by default. The leading chunk of an idle stream dispatches as soon as it is written, and chunks arriving while a flush is in flight coalesce into the next batch. If you write bursts of many tiny chunks and prefer fewer round trips over first-chunk latency, set a group-commit window with the World's `streamFlushIntervalMs` option or the `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable. See [Worlds configuration](/docs/configuration/worlds#streamflushintervalms).
 
 **Release locks properly:**
 
@@ -515,7 +563,7 @@ Stream locks acquired in a step only apply within that step, not across other st
 </Callout>
 
 <Callout type="warn">
-If a lock is not released, the step function's HTTP request cannot terminate. Even though the step returns and the workflow continues, the underlying request will remain active until it times out—wasting compute resources unnecessarily.
+If a lock is not released, the invocation that ran the step cannot terminate. Even though the step returns and the workflow continues, the underlying request remains active until it times out and wastes compute resources.
 </Callout>
 
 **Close streams when done:**
@@ -541,7 +589,7 @@ const writer = writable.getWriter();
 await writer.write({ /* typed data */ });
 ```
 
-## Stream Failures
+## Stream failures
 
 When a step returns a stream, the step is considered successful once it returns, even if the stream later encounters an error. The workflow won't automatically retry the step. The consumer of the stream must handle errors gracefully. For more on retry behavior, see [Errors and Retries](/docs/foundations/errors-and-retries).
 
@@ -584,17 +632,17 @@ export async function streamErrorWorkflow() {
 ```
 
 <Callout type="info">
-Stream errors don't trigger automatic retries for the producer step. Design your stream consumers to handle errors appropriately. Since the stream is already in an errored state, retrying the consumer won't help - use `FatalError` to fail the workflow immediately.
+Stream errors don't trigger automatic retries for the producer step. Design your stream consumers to handle errors. Because the stream is already in an errored state, retrying the consumer won't help. Use `FatalError` to fail the workflow immediately.
 </Callout>
 
-## Related Documentation
-
-- [`getWritable()` API Reference](/docs/api-reference/workflow/get-writable) - Get the workflow's writable stream
-- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Pause workflow execution for a duration
-- [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows and access the `Run` object
-- [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieve runs and their streams later
-- [world.streams](/docs/api-reference/workflow-api/world/streams) - Low-level stream read/write/close via World SDK
-- [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - AI agents with built-in streaming support
-- [Errors and Retries](/docs/foundations/errors-and-retries) - Understanding error handling and retry behavior
-- [Serialization](/docs/foundations/serialization) - Understanding what data types can be passed in workflows
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts of workflow execution
+## Related documentation
+
+- [`getWritable()` API reference](/docs/api-reference/workflow/get-writable): Get the workflow's writable stream
+- [`sleep()` API reference](/docs/api-reference/workflow/sleep): Pause workflow execution for a duration
+- [`start()` API reference](/docs/api-reference/workflow-api/start): Start workflows and access the `Run` object
+- [`getRun()` API reference](/docs/api-reference/workflow-api/get-run): Retrieve runs and their streams later
+- [`world.streams`](/docs/api-reference/workflow-runtime/world/streams): Use low-level stream read, write, and close operations through the World SDK
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Build AI agents with durable, resumable streaming support
+- [Errors and retries](/docs/foundations/errors-and-retries): Understand error handling and retry behavior
+- [Serialization](/docs/foundations/serialization): Understand which data types you can pass in workflows
+- [Workflows and steps](/docs/foundations/workflows-and-steps): Learn the core concepts of workflow execution

package/docs/foundations/versioning.mdx

@@ -0,0 +1,263 @@
+---
+title: Versioning
+description: Understand how workflow runs are pinned to deployments, how to recover runs after a fix, and how to opt in to newer code explicitly.
+type: guide
+summary: Keep in-flight runs stable by default, then choose explicit upgrade boundaries when you need them.
+prerequisites:
+  - /docs/foundations/starting-workflows
+related:
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/cancellation
+  - /cookbook/common-patterns/workflow-composition
+---
+
+Workflow runs are pinned to the deployment that starts them. When a run begins, Workflow SDK records the deployment for that run and continues executing the run on that same copy of your code.
+
+That default is intentional. Durable workflows can pause for minutes, days, or months. If the code underneath a paused run changed every time you deployed, an in-flight run could resume into a different function body, different step names, or different input types than the ones it started with. That can make type safety fragile and can break long-running work in hard-to-debug ways.
+
+With Workflow SDK, you can keep shipping. New runs use new deployments, while existing runs keep the version they already understand.
+
+## Default behavior
+
+Start a workflow normally:
+
+```typescript title="app/api/orders/route.ts" lineNumbers
+import { start } from "workflow/api";
+import { fulfillOrder } from "@/workflows/fulfill-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+
+  const run = await start(fulfillOrder, [orderId]); // [!code highlight]
+
+  return Response.json({ runId: run.runId });
+}
+```
+
+The run is tied to the deployment that handled this request. If you deploy a new version while the workflow is [sleeping](/docs/api-reference/workflow/sleep), [waiting on a hook](/docs/foundations/hooks), [retrying a step](/docs/foundations/errors-and-retries), or processing later queue messages, that existing run still resumes on the original deployment.
+
+```typescript title="workflows/fulfill-order.ts" lineNumbers
+import { sleep } from "workflow";
+
+export async function fulfillOrder(orderId: string) {
+  "use workflow";
+
+  await reserveInventory(orderId);
+  await sleep("2d");
+  await chargeCustomer(orderId);
+  await shipOrder(orderId);
+}
+
+async function reserveInventory(orderId: string) {
+  "use step";
+  // ...
+}
+
+async function chargeCustomer(orderId: string) {
+  "use step";
+  // ...
+}
+
+async function shipOrder(orderId: string) {
+  "use step";
+  // ...
+}
+```
+
+If you deploy a change to `chargeCustomer()` while a run is in the two-day sleep, the existing run does not suddenly resume into the new implementation. It continues on the deployment it started on. The next order starts on the latest deployment and uses the new code from the beginning.
+
+## Fixing in-flight runs
+
+Sometimes you deploy because the old code had a bug. The safest fix is usually explicit:
+
+1. Deploy the fixed code.
+2. Find the affected runs in [observability](/docs/observability) or with the CLI.
+3. Cancel the old runs if they are still running.
+4. Rerun them on the latest deployment with the same inputs.
+
+This keeps the version boundary visible. The old run ends as canceled or failed, and the replacement run starts fresh on the fixed deployment. This is a good fit for one-off, ad-hoc upgrades where you explicitly opt in to moving affected runs onto a new version.
+
+```bash
+# Inspect affected runs and copy the exact workflowName value.
+npx workflow inspect runs \
+  --backend vercel \
+  --status running
+
+# Cancel one run.
+npx workflow cancel <run-id> \
+  --backend vercel
+
+# Or bulk-cancel matching running runs.
+npx workflow cancel \
+  --status running \
+  --workflowName "workflow//./workflows/fulfill-order//fulfillOrder" \
+  --backend vercel
+```
+
+The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-observability/parse-workflow-name) when you need display-friendly names.
+
+In the [observability UI](/docs/observability), use **Rerun on latest** to enqueue the workflow again with the same inputs against the latest deployment.
+
+If you are writing your own recovery route, call `start()` with the same arguments and `deploymentId: "latest"`:
+
+```typescript title="app/api/orders/rerun/route.ts" lineNumbers
+import { start } from "workflow/api";
+import { fulfillOrder } from "@/workflows/fulfill-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+
+  const run = await start(fulfillOrder, [orderId], {
+    deploymentId: "latest", // [!code highlight]
+  });
+
+  return Response.json({ runId: run.runId });
+}
+```
+
+<Callout type="warn">
+`deploymentId: "latest"` is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment. Because the caller and target deployment can be different, keep the [workflow function name and file path](/docs/errors/workflow-not-registered), arguments, and return value backward-compatible across the deployments you plan to bridge.
+</Callout>
+
+## Self upgrading workflows
+
+Some workflows are expected to run for long periods. Scheduled loops, recurring jobs, agents, and chat sessions often should not stay on one deployment forever.
+
+Model those as a sequence of runs. Each run does a bounded piece of work, then starts the next run on the latest deployment and exits. This is similar to `continueAsNew` in other durable execution systems, but Workflow SDK uses [explicit recursion through `start()`](/cookbook/common-patterns/workflow-composition).
+
+```typescript title="workflows/daily-digest.ts" lineNumbers
+import { sleep } from "workflow";
+import { start } from "workflow/api";
+
+type DigestState = {
+  userId: string;
+  lastSentAt?: string;
+};
+
+export async function dailyDigest(state: DigestState) {
+  "use workflow";
+
+  const sentAt = await sendDigest(state.userId);
+  await sleep("1d");
+
+  const run = await start(
+    dailyDigest,
+    [{ ...state, lastSentAt: sentAt }],
+    {
+      deploymentId: "latest", // [!code highlight]
+    }
+  );
+
+  return { continuedAs: run.runId };
+}
+
+async function sendDigest(userId: string) {
+  "use step";
+  // ...
+  return new Date().toISOString();
+}
+```
+
+This pattern gives every run a clear lifecycle:
+
+- The current run stays on its original deployment.
+- The next run starts on the latest deployment.
+- The [serialized `state`](/docs/foundations/serialization) is the migration boundary between versions.
+- Observability can link parent and child runs when a workflow starts another run.
+
+## Carrying context forward
+
+Anything that is [serializable by Workflow SDK](/docs/foundations/serialization) can be passed from one run to the next as an argument. That includes plain state objects, `ReadableStream`, `WritableStream`, `AbortSignal`, and other supported serialized values.
+
+For example, a long export can register its [output stream](/docs/foundations/streaming) once, write progress from each run, and pass the same stream plus updated state into the next run:
+
+```typescript title="workflows/export-report.ts" lineNumbers
+import { getWritable } from "workflow";
+import { start } from "workflow/api";
+
+type ExportState = {
+  exportId: string;
+  page: number;
+};
+
+export async function exportReport(
+  state: ExportState,
+  progress?: WritableStream<string>
+) {
+  "use workflow";
+
+  // Register the stream once. Continuation runs receive this same stream
+  // as an argument and keep writing to it.
+  const stream =
+    progress !== undefined ? progress : getWritable<string>();
+
+  const hasMore = await exportPage(state, stream);
+
+  if (!hasMore) {
+    await writeProgress(stream, { type: "done", totalPages: state.page });
+    return { totalPages: state.page };
+  }
+
+  const run = await start(exportReport, [
+    { ...state, page: state.page + 1 },
+    stream,
+  ], {
+    deploymentId: "latest", // [!code highlight]
+  });
+
+  return { continuedAs: run.runId };
+}
+
+async function exportPage(
+  state: ExportState,
+  stream: WritableStream<string>
+) {
+  "use step";
+
+  // Do work for this version boundary.
+  const hasMore = state.page < 10;
+  const writer = stream.getWriter();
+
+  try {
+    await writer.write(
+      JSON.stringify({ type: "page", page: state.page }) + "\n"
+    );
+    return hasMore;
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+async function writeProgress(
+  stream: WritableStream<string>,
+  event: { type: "done"; totalPages: number }
+) {
+  "use step";
+
+  const writer = stream.getWriter();
+  try {
+    await writer.write(JSON.stringify(event) + "\n");
+  } finally {
+    writer.releaseLock();
+  }
+}
+```
+
+```typescript title="app/api/export/route.ts" lineNumbers
+import { start } from "workflow/api";
+import { exportReport } from "@/workflows/export-report";
+
+export async function POST(request: Request) {
+  const { exportId } = await request.json();
+
+  const run = await start(exportReport, [{ exportId, page: 1 }]);
+
+  // Linked continuation runs keep writing to the stream registered by
+  // the parent run, because that stream is passed forward as an argument.
+  return new Response(run.readable, {
+    headers: { "Content-Type": "application/jsonl" },
+  });
+}
+```
+
+Each run still has one clear version boundary: the current run stays on its original deployment, the next run starts on the latest deployment, and only the explicit state and stream handle are carried forward.