workflow 4.2.0-beta.74 → 4.2.0-beta.75

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

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

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

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

@@ -0,0 +1,152 @@
+---
+title: Streams
+description: Read, write, and manage real-time data streams for workflow runs.
+type: reference
+summary: "Methods: writeToStream(), readFromStream(), closeStream(), listStreamsByRunId(). Stream methods live directly on the world object."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/foundations/streaming
+  - /docs/api-reference/workflow/get-writable
+keywords:
+  - writeToStream
+  - readFromStream
+  - closeStream
+  - listStreamsByRunId
+  - 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.
+
+<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.
+</Callout>
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld(); // [!code highlight]
+// Stream methods are called directly on world — e.g. world.writeToStream()
+```
+
+## Methods
+
+### writeToStream()
+
+Write a data chunk to a named stream for a workflow run.
+
+```typescript lineNumbers
+await world.writeToStream("default", runId, chunk); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+| `chunk` | `string \| Uint8Array` | Data to write to the stream |
+
+### readFromStream()
+
+Read data from a named stream as a `ReadableStream`. Returns a live stream that waits for new chunks in real time.
+
+```typescript lineNumbers
+const readable = await world.readFromStream("default"); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `startIndex` | `number` | Optional starting index for partial reads. Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). |
+
+**Returns:** `ReadableStream<Uint8Array>`
+
+### closeStream()
+
+Close a stream when done writing.
+
+```typescript lineNumbers
+await world.closeStream("default", runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+
+### listStreamsByRunId()
+
+List all stream names associated with a workflow run.
+
+```typescript lineNumbers
+const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** `string[]` — Array of stream names
+
+## Examples
+
+### List All Streams for a Workflow Run
+
+```typescript lineNumbers
+// app/api/workflow-streams/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 streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+
+  return Response.json({ streams: streamNames });
+}
+```
+
+### Read a Stream as a Response
+
+```typescript lineNumbers
+// app/api/workflow-streams/read/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const streamName = url.searchParams.get("name");
+
+  if (!streamName) {
+    return Response.json({ error: "name required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const readable = await world.readFromStream(streamName); // [!code highlight]
+
+  return new Response(readable, {
+    headers: { "Content-Type": "application/octet-stream" },
+  });
+}
+```
+
+## Related
+
+- [Streaming](/docs/foundations/streaming) — Core concepts for streaming data from workflows
+- [getWritable()](/docs/api-reference/workflow/get-writable) — The standard way to write to streams from within steps
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — List runs that may have associated streams

package/docs/foundations/hooks.mdx

@@ -221,6 +221,10 @@ While hooks are powerful, they require you to manually handle HTTP requests and
 
 When using Workflow SDK, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
 
+<Callout type="warn">
+`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. This is convenient for prototypes and a simple developer experience because you can share the webhook URL (endpoint) without creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+</Callout>
+
 <Callout type="info">
 See the full API reference for [`createWebhook()`](/docs/api-reference/workflow/create-webhook) for all available options.
 </Callout>

package/docs/foundations/streaming.mdx

@@ -593,6 +593,7 @@ Stream errors don't trigger automatic retries for the producer step. Design your
 - [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Pause workflow execution for a duration
 - [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows and access the `Run` object
 - [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieve runs and their streams later
+- [world.streams](/docs/api-reference/workflow-api/world/streams) - Low-level stream read/write/close via World SDK
 - [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - AI agents with built-in streaming support
 - [Errors and Retries](/docs/foundations/errors-and-retries) - Understanding error handling and retry behavior
 - [Serialization](/docs/foundations/serialization) - Understanding what data types can be passed in workflows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.0-beta.74",
+  "version": "4.2.0-beta.75",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.48",
-    "@workflow/cli": "4.2.0-beta.74",
-    "@workflow/core": "4.2.0-beta.74",
-    "@workflow/errors": "4.1.0-beta.19",
+    "@workflow/astro": "4.0.0-beta.49",
+    "@workflow/cli": "4.2.0-beta.75",
+    "@workflow/core": "4.2.0-beta.75",
+    "@workflow/errors": "4.1.0-beta.20",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
     "@workflow/utils": "4.1.0-beta.13",
-    "@workflow/next": "4.0.1-beta.70",
-    "@workflow/nest": "0.0.0-beta.23",
-    "@workflow/nitro": "4.0.1-beta.69",
-    "@workflow/nuxt": "4.0.1-beta.58",
-    "@workflow/sveltekit": "4.0.0-beta.63",
-    "@workflow/rollup": "4.0.0-beta.31"
+    "@workflow/next": "4.0.1-beta.71",
+    "@workflow/nest": "0.0.0-beta.24",
+    "@workflow/nitro": "4.0.1-beta.70",
+    "@workflow/nuxt": "4.0.1-beta.59",
+    "@workflow/sveltekit": "4.0.0-beta.64",
+    "@workflow/rollup": "4.0.0-beta.32"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",