workflow 4.2.0-beta.73 → 4.2.0-beta.75

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

@@ -0,0 +1,289 @@
+---
+title: Observability Utilities
+description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
+type: reference
+summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/steps
+  - /docs/api-reference/workflow-api/world/runs
+keywords:
+  - workflow/observability
+  - hydrateResourceIO
+  - observabilityRevivers
+  - parseStepName
+  - parseWorkflowName
+  - parseClassName
+  - getEncryptionKeyForRun
+  - hydrateResourceIOWithKey
+  - data hydration
+  - devalue deserialization
+  - encryption decryption
+  - display name parsing
+---
+
+The `workflow/observability` module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.
+
+## Import
+
+```typescript lineNumbers
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  parseStepName, // [!code highlight]
+  parseWorkflowName, // [!code highlight]
+  parseClassName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+```
+
+## Data Hydration
+
+### hydrateResourceIO()
+
+Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. This is required to display step input/output in your UI.
+
+```typescript lineNumbers
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const step = await world.steps.get(runId, stepId);
+
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input); // Deserialized input data
+console.log(hydrated.output); // Deserialized output data
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
+
+**Returns:** The resource with hydrated `input` and `output` fields.
+
+### observabilityRevivers
+
+A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
+
+```typescript lineNumbers
+import { observabilityRevivers } from "workflow/observability";
+```
+
+## Name Parsing
+
+Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names.
+
+### parseStepName()
+
+Parse a machine-readable step name into its components.
+
+```typescript lineNumbers
+import { parseStepName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
+// parsed.shortName → "processPayment"
+// parsed.moduleSpecifier → "./src/workflows/order"
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `stepName` | `string` | The machine-readable step name |
+
+**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
+
+### parseWorkflowName()
+
+Parse a machine-readable workflow name into its components.
+
+```typescript lineNumbers
+import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
+// parsed.shortName → "processOrder"
+// parsed.moduleSpecifier → "./src/workflows/order"
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workflowName` | `string` | The machine-readable workflow name |
+
+**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
+
+### parseClassName()
+
+Parse a machine-readable class name into its components.
+
+```typescript lineNumbers
+import { parseClassName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
+// parsed.shortName → "User"
+// parsed.moduleSpecifier → "./src/models"
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `className` | `string` | The machine-readable class name |
+
+**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
+
+## Encryption
+
+For workflows with encrypted step data, use these utilities to decrypt before hydrating.
+
+### getEncryptionKeyForRun()
+
+Retrieve the encryption key used for a specific workflow run.
+
+{/* @expect-error:2305 */}
+```typescript lineNumbers
+import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
+
+const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** Encryption key for the run
+
+### hydrateResourceIOWithKey()
+
+Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
+
+{/* @expect-error:2305,2724 */}
+```typescript lineNumbers
+import { // [!code highlight]
+  getEncryptionKeyForRun, // [!code highlight]
+  hydrateResourceIOWithKey, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
+| `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
+
+**Returns:** The resource with decrypted and hydrated `input` and `output` fields.
+
+## Examples
+
+### Hydrate Step Input and Output Data
+
+```typescript lineNumbers
+// app/api/workflow-steps/hydrate/route.ts
+import { getWorld } from "workflow/runtime";
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  parseStepName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+  const stepId = url.searchParams.get("stepId");
+
+  if (!runId || !stepId) {
+    return Response.json({ error: "runId and stepId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const step = await world.steps.get(runId, stepId);
+
+  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+  const parsed = parseStepName(step.stepName);
+
+  return Response.json({
+    displayName: parsed?.shortName ?? step.stepName,
+    input: hydrated.input, // [!code highlight]
+    output: hydrated.output, // [!code highlight]
+  });
+}
+```
+
+### Decrypt and Hydrate Encrypted Step Data
+
+For teams with encryption enabled, step data must be decrypted before hydration:
+
+{/* @expect-error:2305,2724 */}
+```typescript lineNumbers
+// app/api/workflow-steps/decrypt/route.ts
+import { getWorld } from "workflow/runtime";
+import { // [!code highlight]
+  getEncryptionKeyForRun, // [!code highlight]
+  hydrateResourceIOWithKey, // [!code highlight]
+  parseStepName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+  const stepId = url.searchParams.get("stepId");
+
+  if (!runId || !stepId) {
+    return Response.json({ error: "runId and stepId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const step = await world.steps.get(runId, stepId);
+
+  // Decrypt then hydrate // [!code highlight]
+  const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+  const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
+
+  const parsed = parseStepName(step.stepName);
+
+  return Response.json({
+    displayName: parsed?.shortName ?? step.stepName,
+    input: hydrated.input,
+    output: hydrated.output,
+  });
+}
+```
+
+### Parse Display Names for a Run's Steps
+
+Build a progress dashboard with human-readable step names:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const world = getWorld();
+
+// Parse workflow name
+const run = await world.runs.get(runId, { resolveData: "none" });
+const workflowDisplay = parseWorkflowName(run.workflowName); // [!code highlight]
+console.log("Workflow:", workflowDisplay?.shortName); // [!code highlight]
+
+// Parse step names
+const steps = await world.steps.list({ runId, resolveData: "none" });
+for (const step of steps.data) {
+  const stepDisplay = parseStepName(step.stepName); // [!code highlight]
+  console.log(`  ${stepDisplay?.shortName}: ${step.status}`); // [!code highlight]
+}
+```
+
+## Related
+
+- [world.steps](/docs/api-reference/workflow-api/world/steps) — Query step data to hydrate
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — Query run data to hydrate
+- [Serialization](/docs/foundations/serialization) — How workflow data is serialized

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

@@ -0,0 +1,127 @@
+---
+title: world.queue
+description: Enqueue workflow runs and create queue handlers for background processing.
+type: reference
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Manage workflow run queuing and processing."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/starting-workflows
+keywords:
+  - world.queue
+  - getDeploymentId
+  - queue
+  - createQueueHandler
+  - background processing
+  - enqueue workflow
+  - ValidQueueName
+---
+
+The `world.queue` interface provides access to workflow run queuing and processing. Use it to enqueue runs for background execution and create handlers to process queued items.
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const queue = world.queue; // [!code highlight]
+```
+
+## Methods
+
+### getDeploymentId()
+
+Get the current deployment ID. Useful for routing queue messages to the correct deployment.
+
+```typescript lineNumbers
+const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
+```
+
+**Returns:** `string` — The current deployment ID
+
+### queue()
+
+Enqueue a workflow run for background processing.
+
+```typescript lineNumbers
+const messageId = await world.queue.queue(name, message, opts); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `ValidQueueName` | The queue name |
+| `message` | `object` | The message payload to enqueue |
+| `opts` | `object` | Optional configuration |
+
+**Returns:** `MessageId`
+
+### createQueueHandler()
+
+Create a handler function for processing queued messages.
+
+```typescript lineNumbers
+const handler = world.queue.createQueueHandler(prefix, callback); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prefix` | `string` | Queue name prefix to match |
+| `callback` | `function` | Handler function called for each queued message |
+
+**Returns:** Queue handler function
+
+## Examples
+
+### Enqueue a Workflow Run for Background Processing
+
+```typescript lineNumbers
+// app/api/workflow-queue/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function POST(req: Request) {
+  const { workflowName, input } = await req.json();
+
+  const world = getWorld();
+  const messageId = await world.queue.queue(workflowName, { // [!code highlight]
+    input,
+    priority: "normal",
+  }); // [!code highlight]
+
+  return Response.json({ messageId });
+}
+```
+
+### Create a Queue Handler for Processing
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+
+const handler = world.queue.createQueueHandler("my-workflows", async (message) => { // [!code highlight]
+  console.log("Processing:", message);
+  // Handle the queued workflow message
+}); // [!code highlight]
+```
+
+### Get Current Deployment ID
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
+console.log("Running on deployment:", deploymentId);
+```
+
+## Related
+
+- [start()](/docs/api-reference/workflow-api/start) — Higher-level API for starting workflow runs
+- [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — Inspect queued and running workflows

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

@@ -0,0 +1,223 @@
+---
+title: world.runs
+description: List, filter, and inspect workflow runs with cursor pagination and status filtering.
+type: reference
+summary: "Methods: get(), list(). Query workflow runs by status, paginate results, and inspect run metadata."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/steps
+  - /docs/api-reference/workflow-api/world/events
+  - /docs/api-reference/workflow-api/get-run
+keywords:
+  - world.runs
+  - world.runs.get
+  - world.runs.list
+  - WorkflowRun
+  - cursor pagination
+  - run status
+  - resolveData
+  - parseWorkflowName
+  - list workflow runs
+  - filter runs
+---
+
+The `world.runs` interface provides direct access to workflow run data. Use it to list runs with pagination, filter by status, and inspect individual run metadata.
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const runs = world.runs; // [!code highlight]
+```
+
+## Methods
+
+### get()
+
+Retrieve a single workflow run by ID.
+
+```typescript lineNumbers
+const run = await world.runs.get(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data. Default: `'all'` |
+
+**Returns:** `WorkflowRun`
+
+### list()
+
+List workflow runs with cursor pagination.
+
+```typescript lineNumbers
+const result = await world.runs.list({ // [!code highlight]
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data |
+
+**Returns:** `{ data: WorkflowRun[], cursor?: string }`
+
+### cancel()
+
+Cancel a running workflow. This is a convenience method that creates a `run_cancelled` event.
+
+```typescript lineNumbers
+const run = await world.runs.cancel(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID to cancel |
+
+**Returns:** `WorkflowRun`
+
+<Callout type="info">
+  Cancellation works by creating an event with `eventType: 'run_cancelled'`. See [world.events](/docs/api-reference/workflow-api/world/events) for the full event creation API.
+</Callout>
+
+## Types
+
+### WorkflowRun
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `runId` | `string` | Unique run identifier |
+| `status` | `string` | Run status: `'running'`, `'completed'`, `'failed'`, `'cancelled'` |
+| `workflowName` | `string` | Machine-readable workflow identifier |
+| `input` | `any` | Workflow input data (when `resolveData: 'all'`) |
+| `output` | `any` | Workflow output data (when `resolveData: 'all'`) |
+| `error` | `any` | Error data if the run failed |
+| `startedAt` | `string` | ISO timestamp when the run started |
+| `completedAt` | `string \| null` | ISO timestamp when the run completed |
+| `specVersion` | `number` | Workflow spec version |
+
+<Callout type="warn">
+  The `workflowName` field contains a machine-readable identifier like `workflow//./src/workflows/order//processOrder`. Use `parseWorkflowName()` from `workflow/observability` to extract a display-friendly name.
+</Callout>
+
+## Examples
+
+### List Workflow Runs with Cursor Pagination
+
+```typescript lineNumbers
+// app/api/workflow-runs/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+
+  const world = getWorld(); // [!code highlight]
+  const runs = await world.runs.list({ // [!code highlight]
+    pagination: { cursor }, // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json(runs);
+}
+```
+
+### Get a Single Run with Full Data
+
+Use `resolveData: 'all'` (the default) to fetch the complete run including input and output:
+
+```typescript lineNumbers
+// app/api/workflow-runs/[runId]/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+
+  if (!runId) {
+    return Response.json({ error: "runId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const run = await world.runs.get(runId, { // [!code highlight]
+    resolveData: "all", // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({
+    runId: run.runId,
+    status: run.status,
+    input: run.input,
+    output: run.output,
+    startedAt: run.startedAt,
+    completedAt: run.completedAt,
+  });
+}
+```
+
+### Get Run without Data for Lightweight Status Checks
+
+Use `resolveData: 'none'` when you only need status metadata:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const run = await world.runs.get(runId, { // [!code highlight]
+  resolveData: "none", // Skip input/output for performance // [!code highlight]
+}); // [!code highlight]
+
+console.log(run.status); // 'running' | 'completed' | 'failed' | 'cancelled'
+```
+
+### Parse Workflow Display Name from Machine-Readable ID
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const world = getWorld();
+const runs = await world.runs.list({});
+
+for (const run of runs.data) {
+  const parsed = parseWorkflowName(run.workflowName); // [!code highlight]
+  console.log(parsed?.shortName); // e.g., "processOrder" // [!code highlight]
+  console.log(parsed?.moduleSpecifier); // e.g., "./src/workflows/order"
+}
+```
+
+### Cancel a Running Workflow
+
+```typescript lineNumbers
+// app/api/workflow-runs/cancel/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+
+  if (!runId) {
+    return Response.json({ error: "runId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const run = await world.runs.cancel(runId); // [!code highlight]
+
+  return Response.json({ status: run.status });
+}
+```
+
+## Related
+
+- [world.steps](/docs/api-reference/workflow-api/world/steps) — Inspect individual step execution within a run
+- [world.events](/docs/api-reference/workflow-api/world/events) — Query the event log for a run
+- [getRun()](/docs/api-reference/workflow-api/get-run) — Higher-level API for working with individual runs
+- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Parse workflow names and hydrate data