workflow 5.0.0-beta.0 → 5.0.0-beta.10

package/docs/api-reference/workflow/experimental-set-attributes.mdx

@@ -0,0 +1,63 @@
+---
+title: experimental_setAttributes
+description: Attach string metadata to workflow run for observability.
+type: reference
+summary: Use experimental_setAttributes inside a workflow or step function to set run attributes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/attributes
+  - /docs/api-reference/workflow/fatal-error
+---
+
+Attaches string metadata to the current workflow run.
+
+<Callout>
+This API is experimental and may change before the stable attributes API is released.
+</Callout>
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await experimental_setAttributes({
+    phase: "received",
+    orderId,
+  })
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { experimental_setAttributes } from "workflow";
+export default experimental_setAttributes;`}
+showSections={['parameters']}
+/>
+
+## Usage
+
+Call `experimental_setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
+
+Attribute values must be strings. Pass `undefined` to remove an attribute:
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await experimental_setAttributes({ staleKey: undefined })
+}
+```
+
+Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
+
+Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
+
+When called from a workflow body, the write is recorded through an internal step. When called from a step body, the step posts the attributes directly to the World. Storage errors from step-body calls throw from `experimental_setAttributes`, so catch them inside the step if the write should be best-effort.

package/docs/api-reference/workflow/get-workflow-metadata.mdx

@@ -13,6 +13,7 @@ You may want to use this function when you need to:
 
 * Log workflow run IDs
 * Access timing information of a workflow
+* Detect whether encryption is enabled for the current run
 
 <Callout>
 If you need to access step context, take a look at [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata).
@@ -29,6 +30,66 @@ async function testWorkflow() {
 }
 ```
 
+### Detecting Workflow Runtime
+
+You can use `getWorkflowMetadata` to detect whether your code is running inside a workflow context. This is useful when building shared utilities that need to behave differently inside and outside of workflows.
+
+Since `getWorkflowMetadata` throws when called outside a workflow, you can wrap it in a try-catch:
+
+```typescript lineNumbers
+import { getWorkflowMetadata } from "workflow"
+
+function isInWorkflow(): boolean {
+    try {
+        getWorkflowMetadata()
+        return true
+    } catch {
+        return false
+    }
+}
+```
+
+For example, a logging utility could include the workflow run ID when available:
+
+```typescript lineNumbers
+import { getWorkflowMetadata } from "workflow"
+
+function log(message: string) {
+    try {
+        const { workflowRunId } = getWorkflowMetadata()
+        console.log(`[workflow:${workflowRunId}] ${message}`)
+    } catch {
+        console.log(message)
+    }
+}
+```
+
+### Detecting Encryption
+
+The `features` object indicates which capabilities are active for the current run. Library authors can use `features.encryption` to control whether sensitive data is included in step return values, which are serialized to the event log:
+
+```typescript lineNumbers
+import { getWorkflowMetadata } from "workflow"
+
+declare function getUserProfile(userId: string): Promise<{ name: string; ssn: string }>; // @setup
+
+async function fetchUserProfile(userId: string) {
+    "use step"
+
+    const { features } = getWorkflowMetadata() // [!code highlight]
+    const profile = await getUserProfile(userId)
+
+    if (!features.encryption) { // [!code highlight]
+        // Omit sensitive fields from the return value,
+        // since it will be stored unencrypted in the event log
+        const { ssn, ...safe } = profile
+        return safe
+    }
+
+    return profile
+}
+```
+
 ## API Signature
 
 ### Parameters

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

@@ -47,6 +47,9 @@ Workflow SDK contains the following functions you can use inside your workflow f
     <Card href="/docs/api-reference/workflow/get-writable" title="getWritable()">
         Access the current workflow run's default stream.
     </Card>
+    <Card href="/docs/api-reference/workflow/experimental-set-attributes" title="experimental_setAttributes()">
+        Attach experimental string metadata to the current workflow run.
+    </Card>
 </Cards>
 
 ## Error Classes

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -9,10 +9,6 @@ related:
   - /docs/ai/defining-tools
 ---
 
-<Callout type="warn">
-The `@workflow/ai` package is currently in active development and should be considered experimental.
-</Callout>
-
 The `DurableAgent` class enables you to create AI-powered agents that can maintain state across workflow steps, call tools, and gracefully handle interruptions and resumptions.
 
 Tool calls can be implemented as workflow steps for automatic retries, or as regular workflow-level logic utilizing core library features such as [`sleep()`](/docs/api-reference/workflow/sleep) and [Hooks](/docs/foundations/hooks).

package/docs/api-reference/workflow-ai/index.mdx

@@ -1,6 +1,5 @@
 ---
 title: "@workflow/ai"
-icon: FlaskConical
 description: Helpers for building AI-powered workflows with the AI SDK.
 type: overview
 summary: Explore helpers for integrating AI SDK to build durable AI-powered workflows.
@@ -8,10 +7,6 @@ related:
   - /docs/ai
 ---
 
-<Callout type="warn">
-The `@workflow/ai` package is currently in active development and should be considered experimental.
-</Callout>
-
 Helpers for integrating AI SDK for building AI-powered workflows.
 
 ## Classes

package/docs/api-reference/workflow-ai/workflow-chat-transport.mdx

@@ -9,10 +9,6 @@ related:
   - /docs/ai/resumable-streams
 ---
 
-<Callout type="warn">
-The `@workflow/ai` package is currently in active development and should be considered experimental.
-</Callout>
-
 A chat transport implementation for the AI SDK that provides reliable message streaming with automatic reconnection to interrupted streams. This transport is a drop-in replacement for the default AI SDK transport, enabling seamless recovery from network issues, page refreshes, or Vercel Function timeouts.
 
 <Callout>

package/docs/api-reference/workflow-api/get-world.mdx

@@ -1,20 +1,20 @@
 ---
 title: getWorld
-description: Access the World instance for low-level storage, queuing, and streaming operations.
+description: Async function that resolves the World instance for low-level storage, queuing, and streaming operations.
 type: reference
-summary: Use getWorld to access low-level workflow storage, queuing, and streaming backends directly.
+summary: Async function that resolves the World instance for low-level workflow storage, queuing, and streaming backends.
 prerequisites:
   - /docs/deploying
 ---
 
-Retrieves the World instance for direct access to workflow storage, queuing, and streaming backends. This function returns a `World` which provides low-level access to manage workflow runs, steps, events, and hooks.
+Retrieves the World instance for direct access to workflow storage, queuing, and streaming backends. This async function returns a `Promise<World>` which provides low-level access to manage workflow runs, steps, events, and hooks.
 
 Use this function when you need direct access to the underlying workflow infrastructure, such as listing all runs, querying events, or implementing custom workflow management logic.
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld(); // [!code highlight]
+const world = await getWorld(); // [!code highlight]
 ```
 
 ## API Signature
@@ -25,7 +25,7 @@ This function does not accept any parameters.
 
 ### Returns
 
-Returns a `World` object:
+Returns a `Promise<World>` object:
 
 <TSDoc
 definition={`
@@ -79,7 +79,7 @@ export async function GET(req: Request) {
   const cursor = url.searchParams.get("cursor") ?? undefined;
 
   try {
-    const world = getWorld(); // [!code highlight]
+    const world = await getWorld(); // [!code highlight]
     const runs = await world.runs.list({
       pagination: { cursor },
       resolveData: "none",

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

@@ -28,7 +28,7 @@ The API package is for access and introspection of workflow data to inspect runs
         Get workflow run status and metadata without waiting for completion.
     </Card>
     <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
-        Get direct access to workflow storage, queuing, and streaming backends.
+        Async: resolve the World instance for storage, queuing, and streaming backends.
     </Card>
     <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
         Low-level API for inspecting runs, steps, events, hooks, streams, and queues.

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-api/world/index.mdx

@@ -2,7 +2,7 @@
 title: World SDK
 description: Low-level API for inspecting and managing workflow runs, steps, events, hooks, streams, and queues.
 type: overview
-summary: Access workflow infrastructure directly via getWorld() for building observability dashboards, admin tools, and custom integrations.
+summary: Access workflow infrastructure via await getWorld() for building observability dashboards, admin tools, and custom integrations.
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 keywords:
@@ -19,7 +19,7 @@ The World SDK provides direct access to workflow infrastructure — runs, steps,
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld(); // [!code highlight]
+const world = await getWorld(); // [!code highlight]
 ```
 
 ## Interfaces

package/docs/api-reference/workflow-api/world/observability.mdx

@@ -147,7 +147,7 @@ const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
 import { getWorld } from "workflow/runtime";
 import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
 
-const world = getWorld();
+const world = await getWorld();
 const run = await world.runs.get(runId, { resolveData: "none" });
 console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
 

package/docs/api-reference/workflow-api/world/queue.mdx

@@ -28,7 +28,7 @@ Queue methods live directly on the `world` object (not nested). They dispatch in
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld(); // [!code highlight]
+const world = await getWorld(); // [!code highlight]
 // Queue methods are called directly on world — e.g. world.queue()
 ```
 

package/docs/api-reference/workflow-api/world/storage.mdx

@@ -37,7 +37,7 @@ The World storage interface exposes four sub-interfaces for querying workflow da
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld(); // [!code highlight]
+const world = await getWorld(); // [!code highlight]
 ```
 
 ---
@@ -304,7 +304,7 @@ const result = await world.hooks.list({ // [!code highlight]
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 let cursor: string | undefined;
 
 const runs = await world.runs.list({ // [!code highlight]
@@ -319,7 +319,7 @@ cursor = runs.cursor; // pass to next call for pagination
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 
 // Full data (default) — includes serialized input/output
 const run = await world.runs.get(runId); // [!code highlight]
@@ -336,7 +336,7 @@ const lightweight = await world.runs.get(runId, { // [!code highlight]
 import { getWorld } from "workflow/runtime";
 import { parseStepName } from "workflow/observability"; // [!code highlight]
 
-const world = getWorld();
+const world = await getWorld();
 const steps = await world.steps.list({ // [!code highlight]
   runId,
   resolveData: "none",
@@ -358,7 +358,7 @@ const progress = steps.data.map((step) => {
 import { getWorld } from "workflow/runtime";
 import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
 
-const world = getWorld();
+const world = await getWorld();
 const step = await world.steps.get(runId, stepId); // [!code highlight]
 const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
 console.log(hydrated.input, hydrated.output);
@@ -369,7 +369,7 @@ console.log(hydrated.input, hydrated.output);
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 await world.events.create(runId, { // [!code highlight]
   eventType: "run_cancelled", // [!code highlight]
 }); // [!code highlight]
@@ -380,7 +380,7 @@ await world.events.create(runId, { // [!code highlight]
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 const hook = await world.hooks.getByToken(token); // [!code highlight]
 console.log(hook.runId, hook.metadata); // [!code highlight]
 ```
@@ -390,7 +390,7 @@ console.log(hook.runId, hook.metadata); // [!code highlight]
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 const events = await world.events.list({ runId }); // [!code highlight]
 
 for (const event of events.data) {

package/docs/api-reference/workflow-api/world/streams.mdx

@@ -2,26 +2,26 @@
 title: Streams
 description: Read, write, and manage real-time data streams for workflow runs.
 type: reference
-summary: "Methods: writeToStream(), writeToStreamMulti(), readFromStream(), closeStream(), listStreamsByRunId(), getStreamChunks(), getStreamInfo(). Stream methods live directly on the world object."
+summary: "Methods: streams.write(), streams.writeMulti(), streams.get(), streams.close(), streams.list(), streams.getChunks(), streams.getInfo(). Stream methods live on world.streams."
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 related:
   - /docs/foundations/streaming
   - /docs/api-reference/workflow/get-writable
 keywords:
-  - writeToStream
-  - writeToStreamMulti
-  - readFromStream
-  - closeStream
-  - listStreamsByRunId
-  - getStreamChunks
-  - getStreamInfo
+  - streams.write
+  - streams.writeMulti
+  - streams.get
+  - streams.close
+  - streams.list
+  - streams.getChunks
+  - streams.getInfo
   - Streamer interface
   - real-time streaming
   - stream lifecycle
 ---
 
-Stream methods live directly on the `world` object returned by `getWorld()`. Use them to write chunks, read streams, and manage stream lifecycle outside of the standard `getWritable()` pattern.
+Stream methods live on `world.streams` (the `streams` sub-object of the `World` instance returned by `await getWorld()`). Use them to write chunks, read streams, and manage stream lifecycle outside of the standard `getWritable()` pattern.
 
 <Callout type="info">
   For most streaming use cases, use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside steps. Direct stream methods are for advanced scenarios like building custom stream consumers or managing streams from outside a workflow.
@@ -32,82 +32,83 @@ Stream methods live directly on the `world` object returned by `getWorld()`. Use
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld(); // [!code highlight]
-// Stream methods are called directly on world — e.g. world.writeToStream()
+const world = await getWorld(); // [!code highlight]
+// Stream methods are called on world.streams — e.g. world.streams.write()
 ```
 
 ## Methods
 
-### writeToStream()
+### write()
 
 Write a data chunk to a named stream.
 
 ```typescript lineNumbers
-await world.writeToStream("default", runId, chunk); // [!code highlight]
+await world.streams.write(runId, "default", chunk); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 | `chunk` | `string \| Uint8Array` | Data to write |
 
-### writeToStreamMulti()
+### writeMulti()
 
-Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `writeToStream()` calls if unavailable.
+Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
 
 ```typescript lineNumbers
-await world.writeToStreamMulti?.("default", runId, [chunk1, chunk2]); // [!code highlight]
+await world.streams.writeMulti?.(runId, "default", [chunk1, chunk2]); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 | `chunks` | `(string \| Uint8Array)[]` | Chunks to write, in order |
 
-### readFromStream()
+### get()
 
 Read data from a named stream as a live `ReadableStream` that waits for new chunks in real time.
 
 ```typescript lineNumbers
-const readable = await world.readFromStream("default"); // [!code highlight]
+const readable = await world.streams.get(runId, "default"); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
 | `name` | `string` | The stream name |
 | `startIndex` | `number` | Optional. Positive values skip chunks from the start (0-based). Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). Clamped to 0. |
 
 **Returns:** `ReadableStream<Uint8Array>`
 
-### closeStream()
+### close()
 
 Close a stream when done writing.
 
 ```typescript lineNumbers
-await world.closeStream("default", runId); // [!code highlight]
+await world.streams.close(runId, "default"); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 
-### listStreamsByRunId()
+### list()
 
 List all stream names associated with a workflow run.
 
 ```typescript lineNumbers
-const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+const streamNames = await world.streams.list(runId); // [!code highlight]
 ```
 
 **Parameters:**
@@ -118,12 +119,12 @@ const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
 
 **Returns:** `string[]`
 
-### getStreamChunks()
+### getChunks()
 
-Fetch stream chunks with cursor-based pagination. Unlike `readFromStream()` (which returns a live `ReadableStream`), this returns a snapshot of currently available chunks.
+Fetch stream chunks with cursor-based pagination. Unlike `get()` (which returns a live `ReadableStream`), this returns a snapshot of currently available chunks.
 
 ```typescript lineNumbers
-const result = await world.getStreamChunks("default", runId, { // [!code highlight]
+const result = await world.streams.getChunks(runId, "default", { // [!code highlight]
   limit: 50,
 }); // [!code highlight]
 // result.data: StreamChunk[], result.cursor, result.hasMore, result.done
@@ -133,8 +134,8 @@ const result = await world.getStreamChunks("default", runId, { // [!code highlig
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 | `options.limit` | `number` | Max chunks per page (default: 100, max: 1000) |
 | `options.cursor` | `string` | Cursor from a previous response |
 
@@ -147,12 +148,12 @@ const result = await world.getStreamChunks("default", runId, { // [!code highlig
 | `hasMore` | `boolean` | Whether more pages of already-written chunks exist |
 | `done` | `boolean` | Whether the stream is fully closed. When `false`, new chunks may appear in future requests even after `hasMore` is `false`. |
 
-### getStreamInfo()
+### getInfo()
 
 Retrieve lightweight metadata about a stream without fetching chunks.
 
 ```typescript lineNumbers
-const info = await world.getStreamInfo("default", runId); // [!code highlight]
+const info = await world.streams.getInfo(runId, "default"); // [!code highlight]
 // info.tailIndex: last chunk index (-1 if empty), info.done: whether stream is closed
 ```
 
@@ -160,8 +161,8 @@ const info = await world.getStreamInfo("default", runId); // [!code highlight]
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 
 **Returns:** `StreamInfoResponse`
 
@@ -181,8 +182,9 @@ import { getWorld } from "workflow/runtime";
 export async function GET(req: Request) {
   const url = new URL(req.url);
   const streamName = url.searchParams.get("name") ?? "default";
-  const world = getWorld();
-  const readable = await world.readFromStream(streamName); // [!code highlight]
+  const runId = url.searchParams.get("runId")!;
+  const world = await getWorld();
+  const readable = await world.streams.get(runId, streamName); // [!code highlight]
 
   return new Response(readable, {
     headers: { "Content-Type": "application/octet-stream" },
@@ -195,11 +197,11 @@ export async function GET(req: Request) {
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 let cursor: string | undefined;
 
 do {
-  const result = await world.getStreamChunks("default", runId, { cursor }); // [!code highlight]
+  const result = await world.streams.getChunks(runId, "default", { cursor }); // [!code highlight]
   for (const chunk of result.data) {
     console.log(`Chunk ${chunk.index}:`, chunk.data);
   }

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;
 }