workflow 4.2.4 → 4.2.5

package/dist/observability.d.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * ```ts
- * import { getWorld } from 'workflow/api';
+ * import { getWorld } from 'workflow/runtime';
  * import { hydrateResourceIO, observabilityRevivers } from 'workflow/observability';
  *
  * const world = getWorld();

package/dist/observability.js

@@ -6,7 +6,7 @@
  *
  * @example
  * ```ts
- * import { getWorld } from 'workflow/api';
+ * import { getWorld } from 'workflow/runtime';
  * import { hydrateResourceIO, observabilityRevivers } from 'workflow/observability';
  *
  * const world = getWorld();
@@ -17,4 +17,4 @@
  */
 export { hydrateData, hydrateResourceIO, observabilityRevivers, } from '@workflow/core/serialization-format';
 export { parseClassName, parseStepName, parseWorkflowName, } from '@workflow/utils';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib2JzZXJ2YWJpbGl0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9vYnNlcnZhYmlsaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7O0dBZ0JHO0FBQ0gsT0FBTyxFQUNMLFdBQVcsRUFDWCxpQkFBaUIsRUFDakIscUJBQXFCLEdBRXRCLE1BQU0scUNBQXFDLENBQUM7QUFFN0MsT0FBTyxFQUNMLGNBQWMsRUFDZCxhQUFhLEVBQ2IsaUJBQWlCLEdBQ2xCLE1BQU0saUJBQWlCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIE9ic2VydmFiaWxpdHkgdXRpbGl0aWVzIGZvciBoeWRyYXRpbmcgc2VyaWFsaXplZCB3b3JrZmxvdyBkYXRhLlxuICpcbiAqIFVzZSB0aGVzZSB3aGVuIGluc3BlY3Rpbmcgd29ya2Zsb3cgc3RlcCBJL08sIHJ1biBpbnB1dHMvb3V0cHV0cyxcbiAqIG9yIGV2ZW50IGRhdGEgZnJvbSB0aGUgV29ya2Zsb3cgU0RLJ3Mgd29ybGQgQVBJcy5cbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHNcbiAqIGltcG9ydCB7IGdldFdvcmxkIH0gZnJvbSAnd29ya2Zsb3cvYXBpJztcbiAqIGltcG9ydCB7IGh5ZHJhdGVSZXNvdXJjZUlPLCBvYnNlcnZhYmlsaXR5UmV2aXZlcnMgfSBmcm9tICd3b3JrZmxvdy9vYnNlcnZhYmlsaXR5JztcbiAqXG4gKiBjb25zdCB3b3JsZCA9IGdldFdvcmxkKCk7XG4gKiBjb25zdCBzdGVwID0gYXdhaXQgd29ybGQuc3RlcHMuZ2V0KHJ1bklkLCBzdGVwSWQsIHsgcmVzb2x2ZURhdGE6ICdhbGwnIH0pO1xuICogY29uc3QgaHlkcmF0ZWQgPSBoeWRyYXRlUmVzb3VyY2VJTyhzdGVwLCBvYnNlcnZhYmlsaXR5UmV2aXZlcnMpO1xuICogLy8gaHlkcmF0ZWQuaW5wdXQgYW5kIGh5ZHJhdGVkLm91dHB1dCBhcmUgbm93IHBsYWluIEpTIG9iamVjdHNcbiAqIGBgYFxuICovXG5leHBvcnQge1xuICBoeWRyYXRlRGF0YSxcbiAgaHlkcmF0ZVJlc291cmNlSU8sXG4gIG9ic2VydmFiaWxpdHlSZXZpdmVycyxcbiAgdHlwZSBSZXZpdmVycyxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvc2VyaWFsaXphdGlvbi1mb3JtYXQnO1xuXG5leHBvcnQge1xuICBwYXJzZUNsYXNzTmFtZSxcbiAgcGFyc2VTdGVwTmFtZSxcbiAgcGFyc2VXb3JrZmxvd05hbWUsXG59IGZyb20gJ0B3b3JrZmxvdy91dGlscyc7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib2JzZXJ2YWJpbGl0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9vYnNlcnZhYmlsaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7O0dBZ0JHO0FBQ0gsT0FBTyxFQUNMLFdBQVcsRUFDWCxpQkFBaUIsRUFDakIscUJBQXFCLEdBRXRCLE1BQU0scUNBQXFDLENBQUM7QUFFN0MsT0FBTyxFQUNMLGNBQWMsRUFDZCxhQUFhLEVBQ2IsaUJBQWlCLEdBQ2xCLE1BQU0saUJBQWlCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIE9ic2VydmFiaWxpdHkgdXRpbGl0aWVzIGZvciBoeWRyYXRpbmcgc2VyaWFsaXplZCB3b3JrZmxvdyBkYXRhLlxuICpcbiAqIFVzZSB0aGVzZSB3aGVuIGluc3BlY3Rpbmcgd29ya2Zsb3cgc3RlcCBJL08sIHJ1biBpbnB1dHMvb3V0cHV0cyxcbiAqIG9yIGV2ZW50IGRhdGEgZnJvbSB0aGUgV29ya2Zsb3cgU0RLJ3Mgd29ybGQgQVBJcy5cbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHNcbiAqIGltcG9ydCB7IGdldFdvcmxkIH0gZnJvbSAnd29ya2Zsb3cvcnVudGltZSc7XG4gKiBpbXBvcnQgeyBoeWRyYXRlUmVzb3VyY2VJTywgb2JzZXJ2YWJpbGl0eVJldml2ZXJzIH0gZnJvbSAnd29ya2Zsb3cvb2JzZXJ2YWJpbGl0eSc7XG4gKlxuICogY29uc3Qgd29ybGQgPSBnZXRXb3JsZCgpO1xuICogY29uc3Qgc3RlcCA9IGF3YWl0IHdvcmxkLnN0ZXBzLmdldChydW5JZCwgc3RlcElkLCB7IHJlc29sdmVEYXRhOiAnYWxsJyB9KTtcbiAqIGNvbnN0IGh5ZHJhdGVkID0gaHlkcmF0ZVJlc291cmNlSU8oc3RlcCwgb2JzZXJ2YWJpbGl0eVJldml2ZXJzKTtcbiAqIC8vIGh5ZHJhdGVkLmlucHV0IGFuZCBoeWRyYXRlZC5vdXRwdXQgYXJlIG5vdyBwbGFpbiBKUyBvYmplY3RzXG4gKiBgYGBcbiAqL1xuZXhwb3J0IHtcbiAgaHlkcmF0ZURhdGEsXG4gIGh5ZHJhdGVSZXNvdXJjZUlPLFxuICBvYnNlcnZhYmlsaXR5UmV2aXZlcnMsXG4gIHR5cGUgUmV2aXZlcnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3NlcmlhbGl6YXRpb24tZm9ybWF0JztcblxuZXhwb3J0IHtcbiAgcGFyc2VDbGFzc05hbWUsXG4gIHBhcnNlU3RlcE5hbWUsXG4gIHBhcnNlV29ya2Zsb3dOYW1lLFxufSBmcm9tICdAd29ya2Zsb3cvdXRpbHMnO1xuIl19

package/docs/ai/index.mdx

@@ -120,16 +120,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,
   });

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

@@ -22,6 +22,30 @@ 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.
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```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
@@ -83,7 +107,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
 

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

@@ -84,7 +84,7 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 
 ### Using `deploymentId: "latest"`
 
-Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call. For when to use this and how it fits with default run pinning, see [Versioning](/docs/foundations/versioning).
 
 ```typescript
 import { start } from "workflow/api";
@@ -96,7 +96,7 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 ```
 
 <Callout type="info">
-The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+The `deploymentId` option 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 — the same production target for production deployments, or the same git branch for preview deployments.
 </Callout>
 
 <Callout type="warn">

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -27,6 +27,15 @@ const workflowConfig = {}
 export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 ```
 
+<Callout type="warn">
+If a package in `serverExternalPackages` contains workflow code (`"use step"`,
+`"use workflow"`, or serialization classes), `withWorkflow()` automatically
+removes it from `serverExternalPackages` for the current build and prints a
+warning. This ensures the package still gets transformed by the Workflow
+compiler. Remove that package from `serverExternalPackages` in your
+`next.config` to silence the warning.
+</Callout>
+
 ### Monorepos and Workspace Imports
 
 By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as `apps/web` and workspace resolution is not working correctly, you can set `outputFileTracingRoot` as a workaround:
@@ -78,6 +87,7 @@ The `workflows.local` options only affect local development. When deployed to Ve
 
 ## Exporting a Function
 
+
 If you are exporting a function in your `next.config` you will need to ensure you call the function returned from `withWorkflow`.
 
 ```typescript title="next.config.ts" lineNumbers

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

@@ -139,6 +139,8 @@ On Vercel, workflow runs are pegged to the deployment that started them. This me
 
 This ensures long-running workflows complete reliably without being affected by subsequent deployments.
 
+For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).
+
 ## Security
 
 ### Consumer function security

package/docs/foundations/index.mdx

@@ -35,4 +35,7 @@ Workflow programming can be a slight shift from how you traditionally write real
     <Card href="/docs/foundations/idempotency" title="Idempotency">
         Prevent duplicate side effects when retrying operations.
     </Card>
+    <Card href="/docs/foundations/versioning" title="Versioning">
+        Understand how runs stay pinned to deployments and when to opt in to newer code.
+    </Card>
 </Cards>

package/docs/foundations/meta.json

@@ -8,7 +8,8 @@
     "hooks",
     "streaming",
     "serialization",
-    "idempotency"
+    "idempotency",
+    "versioning"
   ],
   "defaultOpen": true
 }

package/docs/foundations/versioning.mdx

@@ -0,0 +1,280 @@
+---
+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
+  - /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 cancelled 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-api/world/observability) 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 a very long time. 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 in Workflow SDK it is just [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 nextRunId = await continueDigest({
+    ...state,
+    lastSentAt: sentAt,
+  });
+
+  return { continuedAs: nextRunId };
+}
+
+async function continueDigest(state: DigestState) {
+  "use step";
+
+  const run = await start(dailyDigest, [state], {
+    deploymentId: "latest", // [!code highlight]
+  });
+
+  return 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`, 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 nextRunId = await continueExportOnLatest(
+    { ...state, page: state.page + 1 },
+    stream
+  );
+
+  return { continuedAs: nextRunId };
+}
+
+async function continueExportOnLatest(
+  state: ExportState,
+  stream: WritableStream<string>
+) {
+  "use step";
+
+  const run = await start(exportReport, [state, stream], {
+    deploymentId: "latest", // [!code highlight]
+  });
+
+  return 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.

package/docs/getting-started/index.mdx

@@ -63,6 +63,12 @@ import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStac
         <span className="font-medium">SvelteKit</span>
      </div>
     </Card>
+    <Card href="/docs/getting-started/tanstack-start" >
+     <div className="flex flex-col items-center justify-center gap-2">
+        <TanStack className="size-16 dark:invert" />
+        <span className="font-medium">TanStack Start</span>
+     </div>
+    </Card>
     <Card className="opacity-50">
       <div className="flex flex-col items-center justify-center gap-2">
         <Nest className="size-16 dark:invert grayscale" />
@@ -70,11 +76,4 @@ import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStac
         <Badge variant="secondary">Coming soon</Badge>
       </div>
     </Card>
-    <Card className="opacity-50">
-      <div className="flex flex-col items-center justify-center gap-2">
-        <TanStack className="size-16 dark:invert grayscale" />
-        <span className="font-medium">TanStack Start</span>
-        <Badge variant="secondary">Coming soon</Badge>
-      </div>
-    </Card>
 </Cards>

package/docs/getting-started/meta.json

@@ -9,6 +9,7 @@
     "nitro",
     "nuxt",
     "sveltekit",
+    "tanstack-start",
     "vite"
   ],
   "defaultOpen": true

package/docs/getting-started/next.mdx

@@ -75,9 +75,9 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 </Accordion>
 
 <Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+  <AccordionItem value="configure-proxy-handler" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Configure Proxy Handler (if applicable)
+      <h3 id="configure-proxy-handler">Configure Proxy Handler (if applicable)</h3>
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
@@ -85,7 +85,9 @@ If your Next.js app has a [proxy handler](https://nextjs.org/docs/app/api-refere
 (formerly known as "middleware"), you'll need to update the matcher pattern to exclude Workflow's
 internal paths to prevent the proxy handler from running on them.
 
-Add `.well-known/workflow/*` to your middleware's exclusion list:
+If you see `[local world] Queue operation failed` with `Cannot perform ArrayBuffer.prototype.slice on a detached ArrayBuffer`, your proxy matcher is still intercepting Workflow's internal `POST /.well-known/workflow/v1/flow` request. This is especially easy to miss in Next.js 16, where `proxy.ts` replaced `middleware.ts`.
+
+Add `.well-known/workflow/*` to your matcher exclusion list:
 
 ```typescript title="proxy.ts" lineNumbers
 import { NextResponse } from "next/server";

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

@@ -0,0 +1,241 @@
+---
+title: TanStack Start
+description: Set up your first durable workflow in a TanStack Start application.
+type: guide
+summary: Set up Workflow SDK in a TanStack Start app.
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/foundations/workflows-and-steps
+---
+
+This guide will walk through setting up your first workflow in a TanStack Start app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
+
+---
+
+<Steps>
+
+<Step>
+## Create Your TanStack Start Project
+
+Start by creating a new TanStack Start project:
+
+```bash
+npm create @tanstack/start@latest my-workflow-app
+```
+
+Enter the newly made directory:
+
+```bash
+cd my-workflow-app
+```
+
+### Install `workflow`
+
+```package-install
+npm i workflow
+```
+
+### Configure TanStack Start
+
+TanStack Start runs on Vite, so the Workflow SDK is wired in via the same `workflow/vite` plugin. Add `workflow()` to your Vite config to enable usage of the `"use workflow"` and `"use step"` directives.
+
+```typescript title="vite.config.ts" lineNumbers
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite";
+
+export default defineConfig({
+  plugins: [
+    workflow(), // [!code highlight]
+    tanstackStart(),
+  ],
+});
+```
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+    <AccordionTrigger className="text-sm">
+      ### Setup IntelliSense for TypeScript (Optional)
+    </AccordionTrigger>
+    <AccordionContent className="[&_p]:my-2">
+
+To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+
+```json title="tsconfig.json" lineNumbers
+{
+  "compilerOptions": {
+    // ... rest of your TypeScript config
+    "plugins": [
+      {
+        "name": "workflow" // [!code highlight]
+      }
+    ]
+  }
+}
+```
+
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+</Step>
+
+<Step>
+
+## Create Your First Workflow
+
+Create a new file for our first workflow:
+
+```typescript title="src/workflows/user-signup.ts" lineNumbers
+import { sleep } from "workflow";
+
+export async function handleUserSignup(email: string) {
+  "use workflow"; // [!code highlight]
+
+  const user = await createUser(email);
+  await sendWelcomeEmail(user);
+
+  await sleep("5s"); // Pause for 5s - doesn't consume any resources
+  await sendOnboardingEmail(user);
+
+  return { userId: user.id, status: "onboarded" };
+}
+```
+
+We'll fill in those functions next, but let's take a look at this code:
+
+* We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
+* The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
+
+## Create Your Workflow Steps
+
+Let's now define those missing functions.
+
+```typescript title="src/workflows/user-signup.ts" lineNumbers
+import { FatalError } from "workflow"
+
+// Our workflow function defined earlier
+
+async function createUser(email: string) {
+  "use step"; // [!code highlight]
+
+  console.log(`Creating user with email: ${email}`);
+
+  // Full Node.js access - database calls, APIs, etc.
+  return { id: crypto.randomUUID(), email };
+}
+
+async function sendWelcomeEmail(user: { id: string; email: string; }) {
+  "use step"; // [!code highlight]
+
+  console.log(`Sending welcome email to user: ${user.id}`);
+
+  if (Math.random() < 0.3) {
+  // By default, steps will be retried for unhandled errors
+   throw new Error("Retryable!");
+  }
+}
+
+async function sendOnboardingEmail(user: { id: string; email: string}) {
+  "use step"; // [!code highlight]
+
+  if (!user.email.includes("@")) {
+    // To skip retrying, throw a FatalError instead
+    throw new FatalError("Invalid Email");
+  }
+
+  console.log(`Sending onboarding email to user: ${user.id}`);
+}
+```
+
+Taking a look at this code:
+
+* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
+* Steps can throw a `FatalError` if an error is intentional and should not be retried.
+
+<Callout>
+We'll dive deeper into workflows, steps, and other ways to suspend or handle events in [Foundations](/docs/foundations).
+</Callout>
+
+</Step>
+
+<Step>
+
+## Create Your Route Handler
+
+To invoke your new workflow, add a server handler at `src/routes/api/signup.ts`:
+
+```typescript title="src/routes/api/signup.ts"
+import { createFileRoute } from "@tanstack/react-router";
+import { json } from "@tanstack/react-start";
+import { start } from "workflow/api";
+import { handleUserSignup } from "../../workflows/user-signup";
+
+export const Route = createFileRoute("/api/signup")({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { email } = await request.json();
+        // Executes asynchronously and doesn't block your app
+        await start(handleUserSignup, [email]);
+        return json({ message: "User signup workflow started" });
+      },
+    },
+  },
+});
+```
+
+This route handler creates a `POST` request endpoint at `/api/signup` that will trigger your workflow.
+
+<Callout>
+Workflows can be triggered from API routes or any server-side code.
+</Callout>
+
+</Step>
+
+</Steps>
+
+## Run in development
+
+To start your development server, run the following command in your terminal in the TanStack Start root directory:
+
+```bash
+npm run dev
+```
+
+Once your development server is running, you can trigger your workflow by running this command in the terminal:
+
+```bash
+curl -X POST --json '{"email":"hello@example.com"}' http://localhost:3000/api/signup
+```
+
+Check the dev server logs to see your workflow execute as well as the steps that are being processed.
+
+Additionally, you can use the [Workflow SDK CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
+
+```bash
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
+npx workflow inspect runs
+```
+
+![Workflow SDK Web UI](/o11y-ui.png)
+
+---
+
+## Deploying to production
+
+Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+
+<FluidComputeCallout />
+
+Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
+
+## Next Steps
+
+* Learn more about the [Foundations](/docs/foundations).
+* Check [Errors](/docs/errors) if you encounter issues.
+* Explore the [API Reference](/docs/api-reference).

package/docs/how-it-works/code-transform.mdx

@@ -320,7 +320,7 @@ The compiler generates stable IDs for workflows and steps based on file paths an
 - **Portable**: Works across different runtimes and deployments
 
 <Callout type="info">
-  Although IDs can change when files are moved or functions are renamed, Workflow SDK function assume atomic versioning in the World. This means changing IDs won't break old workflows from running, but will prevent run from being upgraded and will cause your workflow/step names to change in the observability across deployments.
+  Although IDs can change when files are moved or functions are renamed, Workflow SDK functions assume [atomic versioning](/docs/foundations/versioning) in the World. This means changing IDs won't break old workflows from running, but will prevent runs from being upgraded and will cause your workflow/step names to change in observability across deployments.
 </Callout>
 
 ## Framework Integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.4",
+  "version": "4.2.5",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.4",
-    "@workflow/cli": "4.2.4",
-    "@workflow/core": "4.2.4",
-    "@workflow/errors": "4.1.1",
+    "@workflow/astro": "4.0.5",
+    "@workflow/cli": "4.2.5",
+    "@workflow/core": "4.2.5",
+    "@workflow/errors": "4.1.2",
     "@workflow/typescript-plugin": "4.0.2",
-    "@workflow/utils": "4.1.1",
-    "@workflow/next": "4.0.5",
-    "@workflow/nest": "0.0.4",
-    "@workflow/nitro": "4.0.5",
-    "@workflow/nuxt": "4.0.5",
-    "@workflow/sveltekit": "4.0.4",
-    "@workflow/rollup": "4.0.4"
+    "@workflow/utils": "4.1.2",
+    "@workflow/next": "4.0.6",
+    "@workflow/nest": "0.0.5",
+    "@workflow/nitro": "4.0.6",
+    "@workflow/nuxt": "4.0.6",
+    "@workflow/sveltekit": "4.0.5",
+    "@workflow/rollup": "4.0.5"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",