workflow 5.0.0-beta.4 → 5.0.0-beta.6

package/dist/api.d.ts

@@ -1,2 +1,6 @@
-export { type Event, getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, type StartOptions, start, type StopSleepOptions, type StopSleepResult, type WorkflowReadableStream, type WorkflowReadableStreamOptions, type WorkflowRun, } from '@workflow/core/runtime';
+import '@workflow/core/runtime/world-init';
+export type { Event, StopSleepOptions, StopSleepResult, WorkflowRun, } from '@workflow/core/runtime';
+export { getHookByToken, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
+export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, } from '@workflow/core/runtime/run';
+export { type StartOptions, start, } from '@workflow/core/runtime/start';
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,cAAc,EACd,MAAM,EACN,GAAG,EACH,UAAU,EACV,aAAa,EACb,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AASA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}

package/dist/api.js

@@ -1,2 +1,14 @@
-export { getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, start, } from '@workflow/core/runtime';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBRUwsY0FBYyxFQUNkLE1BQU0sRUFDTixHQUFHLEVBQ0gsVUFBVSxFQUNWLGFBQWEsRUFDYixPQUFPLEVBRVAsS0FBSyxHQU1OLE1BQU0sd0JBQXdCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQge1xuICB0eXBlIEV2ZW50LFxuICBnZXRIb29rQnlUb2tlbixcbiAgZ2V0UnVuLFxuICBSdW4sXG4gIHJlc3VtZUhvb2ssXG4gIHJlc3VtZVdlYmhvb2ssXG4gIHJ1blN0ZXAsXG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbiAgdHlwZSBTdG9wU2xlZXBPcHRpb25zLFxuICB0eXBlIFN0b3BTbGVlcFJlc3VsdCxcbiAgdHlwZSBXb3JrZmxvd1JlYWRhYmxlU3RyZWFtLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW1PcHRpb25zLFxuICB0eXBlIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbiJdfQ==
+// Side-effect import: ensure `world.ts` is loaded so its module-load
+// `globalThis[GetWorldFnKey] ??= getWorld` registration fires before any
+// host route reaches `getWorldLazy()`. Without this, webpack/turbopack
+// tree-shake `world.ts` out of routes that only use `start` (the most
+// common host-side entry point) and `getWorldLazy()`'s dynamic-import
+// fallback then fails because the bundler inlined `get-world-lazy.js`
+// into the route bundle. Resolved to an empty stub via the `workflow`
+// export condition in VM/step bundles, so this stays host-only.
+// See `@workflow/core/src/runtime/world-init.ts` for the full rationale.
+import '@workflow/core/runtime/world-init';
+export { getHookByToken, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
+export { getRun, Run, } from '@workflow/core/runtime/run';
+export { start, } from '@workflow/core/runtime/start';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLHVFQUF1RTtBQUN2RSxzRUFBc0U7QUFDdEUsc0VBQXNFO0FBQ3RFLHNFQUFzRTtBQUN0RSxzRUFBc0U7QUFDdEUsZ0VBQWdFO0FBQ2hFLHlFQUF5RTtBQUN6RSxPQUFPLG1DQUFtQyxDQUFDO0FBUTNDLE9BQU8sRUFDTCxjQUFjLEVBQ2QsVUFBVSxFQUNWLGFBQWEsR0FDZCxNQUFNLG9DQUFvQyxDQUFDO0FBQzVDLE9BQU8sRUFDTCxNQUFNLEVBQ04sR0FBRyxHQUdKLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUVMLEtBQUssR0FDTixNQUFNLDhCQUE4QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gU2lkZS1lZmZlY3QgaW1wb3J0OiBlbnN1cmUgYHdvcmxkLnRzYCBpcyBsb2FkZWQgc28gaXRzIG1vZHVsZS1sb2FkXG4vLyBgZ2xvYmFsVGhpc1tHZXRXb3JsZEZuS2V5XSA/Pz0gZ2V0V29ybGRgIHJlZ2lzdHJhdGlvbiBmaXJlcyBiZWZvcmUgYW55XG4vLyBob3N0IHJvdXRlIHJlYWNoZXMgYGdldFdvcmxkTGF6eSgpYC4gV2l0aG91dCB0aGlzLCB3ZWJwYWNrL3R1cmJvcGFja1xuLy8gdHJlZS1zaGFrZSBgd29ybGQudHNgIG91dCBvZiByb3V0ZXMgdGhhdCBvbmx5IHVzZSBgc3RhcnRgICh0aGUgbW9zdFxuLy8gY29tbW9uIGhvc3Qtc2lkZSBlbnRyeSBwb2ludCkgYW5kIGBnZXRXb3JsZExhenkoKWAncyBkeW5hbWljLWltcG9ydFxuLy8gZmFsbGJhY2sgdGhlbiBmYWlscyBiZWNhdXNlIHRoZSBidW5kbGVyIGlubGluZWQgYGdldC13b3JsZC1sYXp5LmpzYFxuLy8gaW50byB0aGUgcm91dGUgYnVuZGxlLiBSZXNvbHZlZCB0byBhbiBlbXB0eSBzdHViIHZpYSB0aGUgYHdvcmtmbG93YFxuLy8gZXhwb3J0IGNvbmRpdGlvbiBpbiBWTS9zdGVwIGJ1bmRsZXMsIHNvIHRoaXMgc3RheXMgaG9zdC1vbmx5LlxuLy8gU2VlIGBAd29ya2Zsb3cvY29yZS9zcmMvcnVudGltZS93b3JsZC1pbml0LnRzYCBmb3IgdGhlIGZ1bGwgcmF0aW9uYWxlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgdHlwZSB7XG4gIEV2ZW50LFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbmV4cG9ydCB7XG4gIGdldEhvb2tCeVRva2VuLFxuICByZXN1bWVIb29rLFxuICByZXN1bWVXZWJob29rLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3Jlc3VtZS1ob29rJztcbmV4cG9ydCB7XG4gIGdldFJ1bixcbiAgUnVuLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW0sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7XG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG4iXX0=

package/dist/runtime.d.ts

@@ -1,2 +1,2 @@
-export { createWorld, getWorld, getWorldHandlers, healthCheck, type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, setWorld, stepEntrypoint, workflowEntrypoint, } from '@workflow/core/runtime';
+export { createWorld, getWorld, getWorldHandlers, healthCheck, type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,QAAQ,EACR,cAAc,EACd,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,QAAQ,EACR,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}

package/dist/runtime.js

@@ -1,2 +1,2 @@
-export { createWorld, getWorld, getWorldHandlers, healthCheck, setWorld, stepEntrypoint, workflowEntrypoint, } from '@workflow/core/runtime';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9ydW50aW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFDTCxXQUFXLEVBQ1gsUUFBUSxFQUNSLGdCQUFnQixFQUNoQixXQUFXLEVBSVgsUUFBUSxFQUNSLGNBQWMsRUFDZCxrQkFBa0IsR0FDbkIsTUFBTSx3QkFBd0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB7XG4gIGNyZWF0ZVdvcmxkLFxuICBnZXRXb3JsZCxcbiAgZ2V0V29ybGRIYW5kbGVycyxcbiAgaGVhbHRoQ2hlY2ssXG4gIHR5cGUgSGVhbHRoQ2hlY2tFbmRwb2ludCxcbiAgdHlwZSBIZWFsdGhDaGVja09wdGlvbnMsXG4gIHR5cGUgSGVhbHRoQ2hlY2tSZXN1bHQsXG4gIHNldFdvcmxkLFxuICBzdGVwRW50cnlwb2ludCxcbiAgd29ya2Zsb3dFbnRyeXBvaW50LFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbiJdfQ==
+export { createWorld, getWorld, getWorldHandlers, healthCheck, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9ydW50aW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFDTCxXQUFXLEVBQ1gsUUFBUSxFQUNSLGdCQUFnQixFQUNoQixXQUFXLEVBSVgsUUFBUSxFQUNSLGtCQUFrQixHQUNuQixNQUFNLHdCQUF3QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHtcbiAgY3JlYXRlV29ybGQsXG4gIGdldFdvcmxkLFxuICBnZXRXb3JsZEhhbmRsZXJzLFxuICBoZWFsdGhDaGVjayxcbiAgdHlwZSBIZWFsdGhDaGVja0VuZHBvaW50LFxuICB0eXBlIEhlYWx0aENoZWNrT3B0aW9ucyxcbiAgdHlwZSBIZWFsdGhDaGVja1Jlc3VsdCxcbiAgc2V0V29ybGQsXG4gIHdvcmtmbG93RW50cnlwb2ludCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZSc7XG4iXX0=

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

@@ -2,7 +2,7 @@
 title: start
 description: Start and enqueue a new workflow run.
 type: reference
-summary: Use start to programmatically enqueue a new workflow run from outside a workflow function.
+summary: Use start to programmatically enqueue a new workflow run.
 prerequisites:
   - /docs/foundations/starting-workflows
 ---
@@ -50,7 +50,8 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 
 ## Good to Know
 
-* The `start()` function is used in runtime/non-workflow contexts to programmatically trigger workflow executions.
+* The `start()` function is used in runtime contexts to programmatically trigger workflow executions.
+* In v5, `start()` can also be called directly from a workflow function to spawn a child run or continue work in a new run. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) and [Versioning](/docs/foundations/versioning).
 * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
 * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
 * All arguments must be [serializable](/docs/foundations/serialization).
@@ -84,7 +85,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 +97,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-errors/workflow-run-failed-error.mdx

@@ -11,7 +11,7 @@ related:
 
 `WorkflowRunFailedError` is thrown when awaiting `run.returnValue` on a workflow run whose status is `'failed'`. This indicates that the workflow encountered a fatal error during execution and cannot produce a return value.
 
-The `cause` property contains the underlying error with its message, stack trace, and optional error code.
+The `cause` property holds the original thrown value, hydrated through the workflow serialization pipeline so its type identity (e.g. `FatalError`, `RetryableError`, custom `Error` subclasses), `cause` chain, and custom properties are preserved. Because any JavaScript value can be thrown, `cause` is typed as `unknown` — narrow it with `instanceof Error` (or a more specific check) before accessing fields like `message`. The high-level error classification is exposed as the top-level `errorCode` property.
 
 ```typescript lineNumbers
 import { WorkflowRunFailedError } from "workflow/errors"
@@ -21,9 +21,11 @@ try {
   const result = await run.returnValue;
 } catch (error) {
   if (WorkflowRunFailedError.is(error)) { // [!code highlight]
-    console.error(`Run ${error.runId} failed:`, error.cause.message);
-    if (error.cause.code) {
-      console.error("Error code:", error.cause.code);
+    if (error.cause instanceof Error) {
+      console.error(`Run ${error.runId} failed:`, error.cause.message);
+    }
+    if (error.errorCode) {
+      console.error("Error code:", error.errorCode);
     }
   }
 }
@@ -38,8 +40,16 @@ definition={`
 interface WorkflowRunFailedError {
   /** The ID of the failed run. */
   runId: string;
-  /** The underlying error that caused the failure. */
-  cause: Error & { code?: string };
+  /**
+   * The original thrown value from the failed workflow run, hydrated through
+   * the workflow serialization pipeline. Preserves the original type identity
+   * (Error subclasses, FatalError, custom classes with WORKFLOW_SERIALIZE,
+   * etc.) and custom properties. Typed as \`unknown\` because any value can
+   * be thrown — narrow with \`instanceof Error\` before accessing fields.
+   */
+  cause: unknown;
+  /** The high-level error category (e.g. \`USER_ERROR\`, \`RUNTIME_ERROR\`). */
+  errorCode?: string;
   /** The error message. */
   message: string;
 }

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:
@@ -63,6 +72,7 @@ export default withWorkflow(nextConfig, {
     local: {
       port: 4000,
     },
+    sourcemap: false,
   },
 });
 ```
@@ -71,6 +81,27 @@ export default withWorkflow(nextConfig, {
 | --- | --- | --- | --- |
 | `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
+| `workflows.sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. See [Source maps](#source-maps) below. |
+
+### Source maps
+
+The step bundle and intermediate workflow bundle default to `'inline'` source maps so that stack traces from step errors and workflow VM errors point at your source files. The `sourcemap` option lets you change that:
+
+| Value | Behavior |
+| --- | --- |
+| `true` / `'inline'` | Base64-encode the source map and append it to the bundle (default). |
+| `'linked'` | Write a separate `.map` file and add a `sourceMappingURL` comment. |
+| `'external'` | Write a separate `.map` file without the comment. |
+| `'both'` | Emit both inline and external source maps. |
+| `false` | Omit source maps entirely. |
+
+Setting `sourcemap: false` is the main escape hatch for users hitting the Vercel 250MB function size limit — it drops the inline source map from every bundle and also skips the source-map-support runtime shim on the Vercel step function. The tradeoff is that workflow VM stack traces will reference generated code (e.g. `evalmachine.<anonymous>`) rather than your source files.
+
+<Callout type="info">
+Setting `sourcemap` explicitly affects **all** generated bundles (steps, workflows, webhook). The legacy `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING=1` environment variable is narrower — it only toggles source maps on the final workflow wrapper and webhook bundle (which default to off). It continues to work, but new code should use the `sourcemap` option or the `WORKFLOW_SOURCEMAP` environment variable instead.
+</Callout>
+
+The option can also be set via the `WORKFLOW_SOURCEMAP` environment variable, which accepts the same values plus `'0'` / `'1'` as aliases for `false` / `true`. Precedence is: explicit config > `WORKFLOW_SOURCEMAP` > per-bundle default.
 
 <Callout type="info">
 The `workflows.local` options only affect local development. When deployed to Vercel, the runtime ignores `local` settings and uses the Vercel world automatically.
@@ -78,6 +109,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