workflow 5.0.0-beta.4 → 5.0.0-beta.5

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/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-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