workflow 4.2.0-beta.75 → 4.2.0-beta.76

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

@@ -1,223 +0,0 @@
----
-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

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

@@ -1,216 +0,0 @@
----
-title: world.steps
-description: List and inspect workflow step execution data with input/output hydration.
-type: reference
-summary: "Methods: get(), list(). Query step metadata, hydrate serialized I/O, calculate durations."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/world/runs
-  - /docs/api-reference/workflow-api/world/observability
-keywords:
-  - world.steps
-  - world.steps.get
-  - world.steps.list
-  - Step
-  - step input output
-  - hydrateResourceIO
-  - step duration
-  - resolveData
-  - parseStepName
-  - devalue serialization
----
-
-The `world.steps` interface provides access to individual step execution data within workflow runs. Use it to list steps, inspect their input/output, and build progress dashboards.
-
-## Import
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const steps = world.steps; // [!code highlight]
-```
-
-## Methods
-
-### get()
-
-Retrieve a single step by run ID and step ID.
-
-```typescript lineNumbers
-const step = await world.steps.get(runId, stepId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID |
-| `stepId` | `string` | The step ID |
-| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data. Default: `'all'` |
-
-**Returns:** `Step`
-
-### list()
-
-List steps with cursor pagination.
-
-```typescript lineNumbers
-const result = await world.steps.list({ // [!code highlight]
-  runId,
-  pagination: { cursor },
-}); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `params.runId` | `string` | Filter steps by run ID |
-| `params.pagination.cursor` | `string` | Cursor for the next page |
-| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data |
-
-**Returns:** `{ data: Step[], cursor?: string }`
-
-## Types
-
-### Step
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `runId` | `string` | Parent workflow run ID |
-| `stepId` | `string` | Unique step identifier |
-| `stepName` | `string` | Machine-readable step identifier |
-| `status` | `string` | Step status: `'running'`, `'completed'`, `'failed'` |
-| `input` | `any` | Step input data (when `resolveData: 'all'`) |
-| `output` | `any` | Step output data (when `resolveData: 'all'`) |
-| `error` | `any` | Error data if the step failed |
-| `attempt` | `number` | Current retry attempt number |
-| `startedAt` | `string` | ISO timestamp when the step started |
-| `completedAt` | `string \| null` | ISO timestamp when the step completed |
-| `retryAfter` | `string \| null` | ISO timestamp for next retry attempt |
-
-<Callout type="info">
-  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [Observability Utilities](/docs/api-reference/workflow-api/world/observability).
-</Callout>
-
-## Examples
-
-### List Steps for a Run without Data
-
-Use `resolveData: 'none'` to efficiently get step metadata for progress dashboards:
-
-```typescript lineNumbers
-// app/api/workflow-steps/route.ts
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "workflow/observability"; // [!code highlight]
-
-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 steps = await world.steps.list({ // [!code highlight]
-    runId,
-    resolveData: "none", // Skip I/O for performance // [!code highlight]
-  }); // [!code highlight]
-
-  const progress = steps.data.map((step) => {
-    const parsed = parseStepName(step.stepName); // [!code highlight]
-    return {
-      stepId: step.stepId,
-      displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
-      module: parsed?.moduleSpecifier,
-      status: step.status,
-      startedAt: step.startedAt,
-      completedAt: step.completedAt,
-    };
-  });
-
-  return Response.json({ progress, cursor: steps.cursor });
-}
-```
-
-### Get Step with Hydrated Input and Output Data
-
-Retrieve a step with its full serialized data and hydrate it for display:
-
-```typescript lineNumbers
-// app/api/workflow-steps/[stepId]/route.ts
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "workflow/observability";
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!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); // [!code highlight]
-
-  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-  const parsed = parseStepName(step.stepName);
-
-  return Response.json({
-    stepId: hydrated.stepId,
-    displayName: parsed?.shortName ?? step.stepName,
-    status: hydrated.status,
-    attempt: hydrated.attempt,
-    input: hydrated.input, // [!code highlight]
-    output: hydrated.output, // [!code highlight]
-  });
-}
-```
-
-### Calculate Step Duration from Timestamps
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const steps = await world.steps.list({ runId });
-
-for (const step of steps.data) {
-  if (step.completedAt) {
-    const start = new Date(step.startedAt).getTime();
-    const end = new Date(step.completedAt).getTime();
-    const durationMs = end - start; // [!code highlight]
-    console.log(`${step.stepName}: ${durationMs}ms`);
-  }
-}
-```
-
-### Parse Step Display Name from Machine-Readable ID
-
-The `stepName` field contains a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` to extract display-friendly names:
-
-```typescript lineNumbers
-import { parseStepName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseStepName(step.stepName); // [!code highlight]
-// parsed.shortName → "processPayment"
-// parsed.moduleSpecifier → "./src/workflows/order"
-```
-
-<Callout type="warn">
-  The `stepName` field is a machine-readable identifier, not a display name. Always use `parseStepName()` from `workflow/observability` to extract the `shortName` for UI display.
-</Callout>
-
-## Related
-
-- [world.runs](/docs/api-reference/workflow-api/world/runs) — List and inspect workflow runs
-- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Hydrate step I/O and parse display names
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Core concepts for steps