workflow 5.0.0-beta.47 → 5.0.0-beta.48

package/dist/internal/errors.d.ts

@@ -1,2 +1,2 @@
-export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
+export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, StreamError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
 //# sourceMappingURL=errors.d.ts.map

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/dist/internal/errors.js

@@ -1,2 +1,2 @@
-export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ludGVybmFsL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsbUJBQW1CLEVBQ25CLGlCQUFpQixFQUNqQixpQkFBaUIsRUFDakIsdUJBQXVCLEVBQ3ZCLGVBQWUsRUFDZixvQkFBb0IsRUFDcEIsc0JBQXNCLEVBQ3RCLGFBQWEsRUFDYixhQUFhLEVBQ2IsYUFBYSxFQUNiLDBCQUEwQixFQUMxQix5QkFBeUIsRUFDekIsc0JBQXNCLEVBQ3RCLDRCQUE0QixFQUM1Qix3QkFBd0IsRUFDeEIsb0JBQW9CLEVBQ3BCLGtCQUFrQixHQUNuQixNQUFNLGtCQUFrQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHtcbiAgRW50aXR5Q29uZmxpY3RFcnJvcixcbiAgSG9va0NvbmZsaWN0RXJyb3IsXG4gIEhvb2tOb3RGb3VuZEVycm9yLFxuICBQcmVjb25kaXRpb25GYWlsZWRFcnJvcixcbiAgUnVuRXhwaXJlZEVycm9yLFxuICBSdW5Ob3RTdXBwb3J0ZWRFcnJvcixcbiAgU3RlcE5vdFJlZ2lzdGVyZWRFcnJvcixcbiAgVGhyb3R0bGVFcnJvcixcbiAgVG9vRWFybHlFcnJvcixcbiAgV29ya2Zsb3dFcnJvcixcbiAgV29ya2Zsb3dOb3RSZWdpc3RlcmVkRXJyb3IsXG4gIFdvcmtmbG93UnVuQ2FuY2VsbGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuRmFpbGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuTm90Q29tcGxldGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuTm90Rm91bmRFcnJvcixcbiAgV29ya2Zsb3dSdW50aW1lRXJyb3IsXG4gIFdvcmtmbG93V29ybGRFcnJvcixcbn0gZnJvbSAnQHdvcmtmbG93L2Vycm9ycyc7XG4iXX0=
+export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, StreamError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ludGVybmFsL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsbUJBQW1CLEVBQ25CLGlCQUFpQixFQUNqQixpQkFBaUIsRUFDakIsdUJBQXVCLEVBQ3ZCLGVBQWUsRUFDZixvQkFBb0IsRUFDcEIsc0JBQXNCLEVBQ3RCLFdBQVcsRUFDWCxhQUFhLEVBQ2IsYUFBYSxFQUNiLGFBQWEsRUFDYiwwQkFBMEIsRUFDMUIseUJBQXlCLEVBQ3pCLHNCQUFzQixFQUN0Qiw0QkFBNEIsRUFDNUIsd0JBQXdCLEVBQ3hCLG9CQUFvQixFQUNwQixrQkFBa0IsR0FDbkIsTUFBTSxrQkFBa0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB7XG4gIEVudGl0eUNvbmZsaWN0RXJyb3IsXG4gIEhvb2tDb25mbGljdEVycm9yLFxuICBIb29rTm90Rm91bmRFcnJvcixcbiAgUHJlY29uZGl0aW9uRmFpbGVkRXJyb3IsXG4gIFJ1bkV4cGlyZWRFcnJvcixcbiAgUnVuTm90U3VwcG9ydGVkRXJyb3IsXG4gIFN0ZXBOb3RSZWdpc3RlcmVkRXJyb3IsXG4gIFN0cmVhbUVycm9yLFxuICBUaHJvdHRsZUVycm9yLFxuICBUb29FYXJseUVycm9yLFxuICBXb3JrZmxvd0Vycm9yLFxuICBXb3JrZmxvd05vdFJlZ2lzdGVyZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5DYW5jZWxsZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5GYWlsZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5Ob3RDb21wbGV0ZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5Ob3RGb3VuZEVycm9yLFxuICBXb3JrZmxvd1J1bnRpbWVFcnJvcixcbiAgV29ya2Zsb3dXb3JsZEVycm9yLFxufSBmcm9tICdAd29ya2Zsb3cvZXJyb3JzJztcbiJdfQ==

package/docs/api-reference/workflow-runtime/world/analytics.mdx

@@ -2,7 +2,7 @@
 title: Analytics
 description: Metadata-only read APIs for runs, steps, events, hooks, waits, and attributes, backed by the observability pipeline.
 type: reference
-summary: "Interfaces: world.analytics.runs, .attributes, .steps, .events, .hooks, .waits. Metadata-only listings with plan-based lookback windows; filter runs by attribute key=value."
+summary: "Interfaces: world.analytics.runs, .attributes, .steps, .events, .hooks, .waits. Metadata-only listings with plan-based lookback windows; filter runs by attribute key=value. Page limits are 1000 run-scoped, 100 cross-run."
 prerequisites:
   - /docs/api-reference/workflow-runtime/get-world
 related:
@@ -13,7 +13,8 @@ keywords:
   - analytics.runs
   - analytics.attributes
   - attribute filter
-  - listValues
+  - getMany
+  - pagination limit
   - lookback window
   - observability-upgrade-required
   - pageInfo
@@ -22,9 +23,10 @@ keywords:
 
 `world.analytics` is an optional, read-only namespace for observability surfaces: dashboards, command-line interface (CLI) tools, and admin tools that list large numbers of runs without touching payload data.
 
-For observability and inspection listings, prefer this namespace over
-[`world.runs.list()`](/docs/api-reference/workflow-runtime/world/storage#runslist).
-The storage API remains available for operational and payload-bearing reads.
+Prefer this namespace for observability: listing, filtering, and inspecting
+workflow state. Use the [Storage](/docs/api-reference/workflow-runtime/world/storage)
+API for payload-bearing reads, and for anything operational that has to see the
+canonical, up-to-the-moment record.
 
 It differs from [Storage](/docs/api-reference/workflow-runtime/world/storage) in two ways:
 
@@ -108,19 +110,190 @@ for (const { key, runCount, lastSeenAt } of page.data) {
 
 ---
 
-## analytics.steps, analytics.events, analytics.hooks, analytics.waits
+## analytics.steps
 
-Run-scoped listings mirroring their [Storage](/docs/api-reference/workflow-runtime/world/storage) counterparts, minus payload data:
+Run-scoped step listings mirroring their [Storage](/docs/api-reference/workflow-runtime/world/storage) counterparts, minus payload data.
+
+### steps.list()
+
+```typescript lineNumbers
+const steps = await world.analytics.steps.list({
+  runId,
+  pagination: { limit: 200, sortOrder: "asc" },
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list steps for |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 1000 |
+
+**Returns:** `PaginatedResponse<AnalyticsStep>`. Each step includes `stepId`, `stepName`, `status`, `attempt`, lifecycle timestamps, `errorCode`, and the `computeInstanceId` of the latest attempt.
+
+### steps.get()
+
+```typescript lineNumbers
+const step = await world.analytics.steps.get(runId, stepId);
+```
+
+**Returns:** `AnalyticsStep`. A step id is only unique within its run, so both arguments are required.
+
+---
+
+## analytics.events
+
+### events.list()
+
+```typescript lineNumbers
+const events = await world.analytics.events.list({
+  runId,
+  eventType: "step_failed", // [!code highlight]
+  pagination: { limit: 1000 },
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list events for |
+| `params.eventType` | `string` | One event type, for example `run_failed` or `step_retrying` |
+| `params.correlationId` | `string` | Narrow to one entity: a step, hook, wait, or attribute id |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 1000 |
+
+**Returns:** `PaginatedResponse<AnalyticsEvent>`. Each event includes `eventId`, `eventType`, `correlationId`, `stepName`, `createdAt`, and provenance fields (`region`, `requestId`, `computeInstanceId`).
+
+Pass a step id as `correlationId` to build that step's timeline: `step_created` through `step_completed`, `step_failed`, or `step_retrying`.
+
+### events.get()
+
+```typescript lineNumbers
+const event = await world.analytics.events.get(runId, eventId);
+```
+
+**Returns:** `AnalyticsEvent`.
+
+### events.getMany()
+
+Look up a bounded set of event ids in one run with a single request.
+
+```typescript lineNumbers
+const events = await world.analytics.events.getMany(runId, eventIds); // [!code highlight]
+```
+
+**Returns:** `AnalyticsEvent[]` — not paginated, and no `pageInfo`. Duplicate ids are looked up once, and ids with no analytics row yet are **omitted rather than erroring**, since ingestion can trail canonical storage. Compare the returned length against your input to detect that.
+
+---
+
+## analytics.hooks
+
+### hooks.list()
 
 ```typescript lineNumbers
-const steps = await world.analytics.steps.list({ runId });
-const events = await world.analytics.events.list({ runId, eventType: "step_failed" });
-const related = await world.analytics.events.listByCorrelationId({ runId, correlationId });
 const hooks = await world.analytics.hooks.list({ runId });
-const waits = await world.analytics.waits.list({ runId, status: "waiting" });
 ```
 
-Each namespace also has a `get()` for point lookups (`steps.get(runId, stepId)`, `events.get(runId, eventId)`, `hooks.get(hookId)`, `waits.get(runId, waitId)`). Hook listings never include the hook token. Resolve it separately through the runtime APIs if you need to deliver a payload.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list hooks for |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 100 |
+
+**Returns:** `PaginatedResponse<AnalyticsHook>`: `hookId`, `status` (`created`, `received`, `disposed`, or `conflict`), `receivedAt`, `disposedAt`, `isWebhook`, `isSystem`.
+
+### hooks.get()
+
+```typescript lineNumbers
+const hook = await world.analytics.hooks.get(hookId);
+```
+
+Unlike steps and waits, a hook id identifies one hook on its own, so no `runId` is needed. Pass `{ runId }` to scope the lookup when you already know it.
+
+<Callout>
+  Hook listings never include the hook token. Resolve it separately through the
+  runtime APIs if you need to deliver a payload.
+</Callout>
+
+---
+
+## analytics.waits
+
+### waits.list()
+
+```typescript lineNumbers
+const waits = await world.analytics.waits.list({
+  runId,
+  status: "waiting", // [!code highlight]
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list waits for |
+| `params.status` | `string` | `waiting` or `completed` |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 1000 |
+
+**Returns:** `PaginatedResponse<AnalyticsWait>`: `waitId`, `status`, `resumeAt`, `completedAt`.
+
+### waits.get()
+
+```typescript lineNumbers
+const wait = await world.analytics.waits.get(runId, waitId);
+```
+
+**Returns:** `AnalyticsWait`. A wait id is only unique within its run, so both arguments are required.
+
+---
+
+## Limits and validation
+
+Arguments are validated in your process before a request goes out. An
+out-of-range or malformed argument throws a `RangeError` naming the bound it
+broke, rather than reaching the backend and coming back as a 400 — which
+matters because analytics is optional and callers commonly wrap it in a
+`try`/`catch`, where a rejected request is easy to mistake for "no data".
+
+### Page limits
+
+`pagination.limit` defaults to 40 everywhere. The maximum depends on whether
+the listing scans within one run or across runs:
+
+| Method | Max `limit` |
+|--------|-------------|
+| `steps.list()`, `events.list()`, `waits.list()` | 1000 |
+| `runs.list()`, `attributes.list()`, `hooks.list()` | 100 |
+
+`events.getMany()` is not paginated; it accepts 1 to 100 event ids per call.
+
+<Callout type="warn">
+  The two page caps differ by a factor of ten, and `hooks.list()` takes the
+  lower one despite being run-scoped. Reusing one page size across listings is
+  the most common way to trip this.
+</Callout>
+
+### Identifiers
+
+Every id is a prefix plus a ULID, and each is checked before the request:
+
+| Parameter | Shape |
+|-----------|-------|
+| `runId` | `wrun_` |
+| `stepId` | `step_` |
+| `eventId` | `evnt_` |
+| `hookId` | `hook_` |
+| `waitId` | `wait_` |
+| `correlationId` | `step_`, `hook_`, `wait_`, or `attr_` |
+
+Step, event, and wait ids are only unique **within** their run, so the methods that take them require a `runId` too. A hook id stands alone.
+
+### Time windows
+
+`startTime` and `endTime` must be supplied **together** and be parseable ISO 8601 timestamps with `startTime` no later than `endTime`. Passing one without the other throws: it used to be dropped silently, which turned a listing you meant to bound into a scan of the whole retention window that looked like a successful answer.
+
+### Attribute filters
+
+`runs.list({ attributes })` accepts 1 to 8 pairs. Keys are 1 to 256 characters; values are at most 256 UTF-8 bytes. Reserved `$`-prefixed keys are valid in a filter even though user code cannot write them.
+
+### Pagination
+
+`cursor` is an opaque token from the previous response; do not construct or parse one. Branch on `hasMore`, not on `cursor` being non-null, and do not change `sortOrder` mid-walk — the cursor encodes the sort position, so reversing it can skip or repeat rows.
 
 ---
 

package/docs/configuration/cli-and-web-ui.mdx

@@ -94,14 +94,14 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 ### `--sort`
 
 - Environment variable: none
-- Default: `desc`
+- Default: `desc` for time-ordered listings; `workflow inspect attributes` orders keys alphabetically unless you pass this flag
 - Sort order for list commands. Accepts `asc` or `desc`.
 
 ### `--limit`
 
 - Environment variable: none
 - Default: `20`
-- Number of items returned per page for list commands.
+- Number of items returned per page for list commands. `workflow cancel` bounds it separately; see [`--limit` (cancel)](#--limit-cancel).
 
 ### `--cursor`
 
@@ -115,6 +115,63 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 - Default: disabled
 - Enables keyboard-controlled pagination for supported list commands.
 
+## Inspect filtering
+
+Flags for `workflow inspect`. Each list view accepts a different subset, noted
+per flag.
+
+### `--runId` / `-r`
+
+- Command: `workflow inspect`
+- Default: unset
+- Scopes the listing to one run. Required for `steps`, `events`, and `sleeps`; optional for `hooks`. Must be a run ID: `wrun_` followed by a 26-character ULID.
+
+### `--limit` (inspect)
+
+- Command: `workflow inspect`
+- Default: `20`
+- Must be an integer between 1 and 100, the smallest page any inspect listing accepts. Larger pages are reachable by paging: pass `--cursor`, or `--interactive` to walk them.
+
+### `--stepId` / `-s`
+
+- Command: `workflow inspect events`
+- Default: unset
+- Filters events to one step.
+
+### `--hookId`
+
+- Command: `workflow inspect events`
+- Default: unset
+- Filters events to one hook.
+
+### `--attribute`
+
+- Command: `workflow inspect runs`
+- Default: unset
+- Filters runs to those whose [attributes](/docs/observability/attributes) match every `key=value` pair given. Repeatable up to 8 times, and splits on the first `=` so a value may contain one.
+- Requires a backend with the analytics read path; ignored with a warning otherwise.
+- Cannot be combined with `--url` or `--web`, which hand off to the dashboard, or with `--withData`, which reads payloads from storage. Storage carries no attribute index.
+- Use `workflow inspect attributes` to discover which keys exist.
+
+### `--since` / `--until`
+
+- Command: `workflow inspect runs`, `workflow inspect attributes`
+- Default: the backend's own window
+- Bounds the listing to a window. `--since` opens the window and accepts a relative duration (`30m`, `12h`, `7d`, `2w`) or a timestamp. `--until` is optional and defaults to now, so `--until` on its own is rejected.
+- Requires a backend with the analytics read path; ignored with a warning otherwise.
+
+### `--withData` / `-d`
+
+- Command: `workflow inspect`
+- Default: disabled
+- Includes full input and output payloads in list views. Deprecated for list views — use `workflow inspect <resource> <id>` to read one item's payloads. Setting it also moves the read off the analytics path, which carries metadata only.
+
+### `--decrypt`
+
+- Command: `workflow inspect`
+- Default: disabled
+- Decrypts encrypted values. Triggers an audit-logged key retrieval.
+
 ## Bulk cancel
 
 `workflow cancel <run-id>` cancels one run. Given a filter instead, it bulk-cancels a batch; bulk mode requires `--status` or `--workflowName`.
@@ -124,18 +181,20 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 - Command: `workflow cancel`
 - Default: unset
 - Restricts the batch to this status. Only `pending` and `running` are accepted; terminal runs cannot be canceled.
+- Also filters `workflow inspect runs`, which accepts any run status. It does not narrow `workflow inspect attributes`, which indexes keys per tenant rather than per run; passing it there warns and lists every key.
 
 ### `--workflowName` / `-n`
 
 - Command: `workflow cancel`
 - Default: unset
 - Restricts the batch to one workflow. Expects the generated workflow ID from `workflow inspect runs`, not the short function name.
+- Also filters `workflow inspect runs` and `workflow inspect attributes`.
 
 ### `--limit` (cancel)
 
 - Command: `workflow cancel`
 - Default: `50`
-- Maximum runs to cancel in one batch (1–500). Only one batch is canceled per invocation; run the command again to cancel the next batch.
+- Maximum runs to cancel in one batch (1–100), the largest page the run listing serves. Only one batch is canceled per invocation; run the command again to cancel the next batch.
 
 ### `--confirm` / `-y`
 

package/docs/configuration/runtime-tuning.mdx

@@ -185,10 +185,10 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 ### `WORKFLOW_RETAINED_VM`
 
 - Default: enabled
-- Keeps the suspended workflow VM alive across inline steps within one invocation, so each iteration of the inline loop appends only the newly written events instead of replaying the whole event log in a fresh VM.
-- A step-driven suspension can keep the VM retained even when hooks are open or created at the same boundary. Hook-only suspensions park the invocation. Suspensions involving waits or attributes, runs with an open wait, and any replay divergence fall back to a full replay.
+- Node.js VM engine only. Keeps the suspended workflow VM alive across inline steps within one invocation, so each iteration of the inline loop appends only the newly written events instead of replaying the whole event log in a fresh VM. QuickJS manages its own retained inline loop independently of this setting.
+- A step- or attribute-driven suspension can keep the VM retained even when hooks or waits are open or created at the same boundary. Hook- or wait-only suspensions park the invocation because nothing in the current delivery can advance them, with one exception: when the hook's own create is what the workflow is waiting on (a `hook.getConflict()` awaiter, or a create whose token is already claimed), the invocation resumes the retained VM over the committed `hook_created` or `hook_conflict` instead of re-invoking through the queue. Any replay divergence falls back to a full replay.
 - Step inputs made of plain data (objects, arrays, primitives) and standard built-ins (`Map`, `Set`, `Date`, `RegExp`, typed arrays, `ArrayBuffer`, `URL`, `Headers`) keep the VM retained. Patching or polyfilling built-in prototypes doesn't change that because serialization never calls them. A boundary falls back to a full replay only when serializing its arguments runs code the workflow controls, such as a getter, a proxy, or a custom class serializer, or computes an `Error`'s stack trace.
-- Set `0` or `false` to replay from scratch in a fresh VM on every iteration.
+- Set `0` or `false` to replay the Node.js workflow from scratch in a fresh VM on every iteration.
 
 ### `WORKFLOW_INLINE_OWNERSHIP`
 

package/docs/getting-started/python.mdx

@@ -11,23 +11,23 @@ related:
 ---
 
 <CopyPrompt
-  text="In this Python project, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel&quot;]` under `[project]` in `pyproject.toml`. Add `[[tool.vercel.workflows]]` with `entrypoint = &quot;app.workflows:wf&quot;`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows()`. Create `app/workflows/ai_content_workflow.py` importing `wf`, define `@wf.workflow async def ai_content_workflow(*, topic: str)`, and call step functions such as `generate_draft` and `summarize_draft`. Export `wf` from `app/workflows/__init__.py` and import the workflow module so its definitions are registered. Mark step functions with `@wf.step`, use `await workflow.sleep(&quot;7 days&quot;)` for durable delays where needed, and use a `workflow.BaseHook` Pydantic model plus `.wait(token=...)` and `.resume(token)` for external approval events. Verify the workflow entrypoint uses the `module:object` format and points to the exported `Workflows` registry."
+  text="Set up Workflow in this Python project. In `pyproject.toml`, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel-workflow&quot;]` under `[project]`, then add `[[tool.vercel.workflows]]` with `entrypoint = &quot;app.workflows:wf&quot;`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows()`. Create `app/steps/generate_draft.py`, import `wf`, and define async step functions such as `generate_draft` and `summarize_draft`, decorating each with `@wf.step`. Then create `app/workflows/ai_content_workflow.py`, import `wf` and those step functions, and define `@wf.workflow async def ai_content_workflow(*, topic: str)` to orchestrate them and return the result. In `app/workflows/__init__.py`, export `wf` and import the workflow module so its definitions are registered. From server-side code, start it with `await workflow.start(ai_content_workflow, topic=...)`; use the returned `Run` to access its ID, check its status, or await its return value. Where the workflow needs a durable delay, use `await workflow.sleep(timedelta(days=7))` after importing `timedelta` from `datetime`. Where it needs an external approval event, define a Pydantic model that also extends `workflow.BaseHook`, wait with `.wait(token=...)`, and resume it from server-side code with `.resume(token)`."
 />
 
 <Callout type="warn">
-The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflows/python).
+The Python SDK is currently in **beta**. APIs and behavior may change.
 </Callout>
 
-You can build durable workflows in Python using the [`vercel` Python SDK](https://pypi.org/project/vercel/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
+You can build durable workflows in Python using the [`vercel-workflow` SDK](https://pypi.org/project/vercel-workflow/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
 
 ## Getting started
 
-Add the `vercel` package and workflow entrypoint to `pyproject.toml`:
+Add the `vercel-workflow` package and workflow entrypoint to `pyproject.toml`:
 
 ```toml filename="pyproject.toml"
 [project]
 requires-python = ">=3.12"
-dependencies = ["vercel"]
+dependencies = ["vercel-workflow"]
 
 [[tool.vercel.workflows]]
 entrypoint = "app.workflows:wf"
@@ -39,16 +39,17 @@ The workflow `entrypoint` uses the `module:object` format and points to the expo
 
 A workflow is a stateful function that coordinates multi-step logic over time. Create a `Workflows` instance and use the `@wf.workflow` decorator to mark a function as durable:
 
-```python filename="app/workflow.py" {3}
+```python filename="app/workflow.py"
 from vercel import workflow
 
-wf = workflow.Workflows()
+wf = workflow.Workflows()  # [!code highlight]
 ```
 
-```python filename="app/workflows/ai_content_workflow.py" {3}
+```python filename="app/workflows/ai_content_workflow.py"
 from app.workflow import wf
+from app.steps.generate_draft import generate_draft, summarize_draft
 
-@wf.workflow
+@wf.workflow  # [!code highlight]
 async def ai_content_workflow(*, topic: str):
     draft = await generate_draft(topic=topic)
     summary = await summarize_draft(draft=draft)
@@ -74,15 +75,15 @@ Under the hood, the workflow compiles into a route that orchestrates execution.
 
 A step is a stateless function that runs a unit of durable work inside a workflow. Use `@wf.step` to mark a function as a step:
 
-```python filename="app/steps/generate_draft.py" {4,8}
+```python filename="app/steps/generate_draft.py"
 import random
 from app.workflow import wf
 
-@wf.step
+@wf.step  # [!code highlight]
 async def generate_draft(*, topic: str):
     return await ai_generate(prompt=f"Write a blog post about {topic}")
 
-@wf.step
+@wf.step  # [!code highlight]
 async def summarize_draft(*, draft: str):
     summary = await ai_summarize(text=draft)
 
@@ -95,18 +96,42 @@ async def summarize_draft(*, draft: str):
 
 Each step executes separately from the workflow orchestrator. While the step executes, the workflow suspends without consuming resources. When the step completes, the workflow resumes automatically where it left off.
 
+## Starting a workflow
+
+Call `workflow.start()` from server-side code to start a workflow. It returns a `Run` that you can use to identify the run, check its status, and wait for its result:
+
+```python filename="app/api/generate.py"
+from app.workflows.ai_content_workflow import ai_content_workflow
+from vercel import workflow
+
+@app.post("/api/generate")
+async def generate_content(*, topic: str):
+    run = await workflow.start(ai_content_workflow, topic=topic)  # [!code highlight]
+
+    print(run.run_id)
+    print(await run.status())  # [!code highlight]
+
+    # Wait until the workflow completes and return its result.
+    return await run.return_value()  # [!code highlight]
+```
+
+Starting a workflow only waits until the run has been created and queued. Await `return_value()` to wait for the workflow to finish, or save its `run_id` and recreate the handle later with `workflow.Run(run_id)`.
+
 ## Sleep
 
 Sleep pauses a workflow for a specified duration without consuming compute resources:
 
-```python filename="app/workflows/ai_refine.py" {7}
+```python filename="app/workflows/ai_refine.py"
+from datetime import timedelta
+
+from app.workflow import wf
 from vercel import workflow
 
 @wf.workflow
 async def ai_refine_workflow(*, draft_id: str):
     draft = await fetch_draft(draft_id)
 
-    await workflow.sleep("7 days")  # Wait 7 days to gather more signals.
+    await workflow.sleep(timedelta(days=7))  # Wait 7 days to gather more signals.  # [!code highlight]
 
     refined = await refine_draft(draft)
 
@@ -116,7 +141,31 @@ async def ai_refine_workflow(*, draft_id: str):
     }
 ```
 
-The sleep call pauses the workflow and consumes no resources. The workflow resumes automatically when the time expires.
+The parameter accepts four forms:
+
+| Form | Description | Example |
+| --- | --- | --- |
+| `str` | Human-readable duration string | `"2 days"`, `"1w"`, `"1h 30m"` |
+| `int` or `float` | Seconds from now | `5` (5 seconds) |
+| `datetime.timedelta` | Duration from now | `timedelta(days=7)` |
+| `datetime.datetime` | Absolute wake-up time (must be timezone-aware) | `datetime(2025, 1, 1, tzinfo=UTC)` |
+
+The string form accepts one or more `<value><unit>` pairs. Supported units:
+
+| Duration | Unit |
+| --- | --- |
+| Milliseconds | `ms` |
+| Seconds | `s`, `second`, `seconds` |
+| Minutes | `m`, `minute`, `minutes` |
+| Hours | `h`, `hour`, `hours` |
+| Days | `d`, `day`, `days` |
+| Weeks | `w`, `week`, `weeks` |
+
+<Callout>
+`sleep()` must be called from the workflow body, not from inside a step. Calling it from a step raises a `RuntimeError`.
+</Callout>
+
+The sleep consumes no resources. The workflow resumes automatically when the time expires.
 
 ## Hooks
 
@@ -124,13 +173,17 @@ A hook lets a workflow wait for external events such as user actions, webhooks,
 
 Define a hook model with Pydantic and `workflow.BaseHook`:
 
-```python filename="app/workflows/approval.py" {3,14}
+```python filename="app/workflows/approval.py"
+import typing
+
+import pydantic
+from app.workflow import wf
 from vercel import workflow
 
-class Approval(BaseModel, workflow.BaseHook):
+class Approval(pydantic.BaseModel, workflow.BaseHook):  # [!code highlight]
     """Human approval for AI-generated drafts"""
 
-    decision: Literal["approved", "changes"]
+    decision: typing.Literal["approved", "changes"]
     notes: str | None = None
 
 @wf.workflow
@@ -138,7 +191,7 @@ async def ai_approval_workflow(*, topic: str):
     draft = await generate_draft(topic=topic)
 
     # Wait for human approval events
-    async for event in Approval.wait(token="draft-123"):
+    async for event in Approval.wait(token="draft-123"):  # [!code highlight]
         if event.decision == "approved":
             await publish_draft(draft)
             break
@@ -149,20 +202,56 @@ async def ai_approval_workflow(*, topic: str):
 
 Resume the workflow when data arrives:
 
-```python filename="app/api/resume.py" {5}
+```python filename="app/api/resume.py"
+from app.workflows.approval import Approval
+
 @app.post("/api/resume")
-async def resume(approval: Approval):
+async def resume(approval: Approval):  # [!code highlight]
     """Resume the workflow when an approval is received"""
 
-    await approval.resume("draft-123")
+    await approval.resume("draft-123")  # [!code highlight]
     return {"ok": True}
 ```
 
 When a hook receives data, the workflow resumes automatically. You don&apos;t need polling, message queues, or manual state management.
 
-## Learn more
+## Streaming
+
+Steps can stream progress while a workflow is running. Get the run&apos;s writable stream inside a step, write values to it, and close it when no more values will be sent:
+
+```python filename="app/workflows/streaming.py"
+from app.workflow import wf
+from vercel import workflow
+
+@wf.step
+async def write_progress():
+    writable = workflow.get_writable()  # [!code highlight]
+
+    for message in ["Drafting", "Reviewing", "Complete"]:
+        await writable.write(message)  # [!code highlight]
+
+    await writable.close()
+
+@wf.workflow
+async def streaming_workflow():
+    await write_progress()
+```
+
+Read the values from the returned `Run` as they arrive:
+
+```python filename="app/api/stream.py"
+from app.workflows.streaming import streaming_workflow
+from vercel import workflow
+
+@app.post("/api/stream")
+async def stream_progress():
+    run = await workflow.start(streaming_workflow)
+
+    async for message in run.readable():  # [!code highlight]
+        print(message)
+```
 
-For comprehensive documentation, examples, and the latest updates, visit the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflows/python).
+Streams are not closed automatically. Close the writable in the last step that writes to it so readers know when the stream is complete.
 
 ## Next steps
 

package/docs/observability/attributes.mdx

@@ -11,7 +11,7 @@ related:
   - /docs/api-reference/workflow-errors/workflow-world-error
 ---
 
-[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes appear in the Workflow CLI and web UI, and you can use them to search and filter runs through the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
+[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes appear in the Workflow CLI and web UI, and you can search and filter runs by them from either the [CLI](#from-the-cli) or the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
 
 You can also seed any attributes directly when starting a run:
 
@@ -82,6 +82,28 @@ Expanding an `attr_set` event (in the run sidebar or the Events tab) shows the c
 
 ## Searching and filtering by attributes
 
+### From the CLI
+
+`workflow inspect attributes` lists the keys recorded on this project's runs,
+with how many runs carry each and when it was first and last seen:
+
+```bash
+workflow inspect attributes
+```
+
+Pass one or more `--attribute key=value` pairs to `inspect runs` to list the
+runs carrying them. Repeatable up to 8 times:
+
+```bash
+workflow inspect runs --attribute phase=received --status running
+```
+
+Both require a backend with the analytics read path. `--attribute` is ignored
+with a warning on backends without one, and `inspect attributes` reports that
+it is unavailable.
+
+### From the Analytics API
+
 The [Analytics API](/docs/api-reference/workflow-runtime/world/analytics) can discover which attribute keys exist and filter run listings by them. The `analytics` namespace is optional on `World`, so feature-detect it before use; it is absent on local, Postgres, and other custom Worlds:
 
 ```typescript lineNumbers

package/docs/whats-new.mdx

@@ -33,7 +33,7 @@ The largest change in v5 has no API surface: the runtime does far less work per
 
 **The runtime avoids waiting on the persistence layer where it can determine that is safe for your workload.** The runtime skips many API calls when they aren't needed, such as requesting the event log on a run's first invocation. Step creation is folded into step execution rather than being its own round trip. The inline loop consumes the event-log delta from the previous step's write instead of re-listing events. Each optimization is gated on specific runtime conditions and can be turned off individually. See [Runtime tuning](/docs/configuration/runtime-tuning).
 
-**The workflow VM is kept alive across inline steps.** Within one invocation, a step-driven suspension keeps the live VM and hydrated state, including when hooks are open or created at the same boundary, so the next iteration appends only the newly written events instead of rebuilding the sandbox and replaying the whole log. Step inputs made of plain data or standard built-ins keep this fast path; see [`WORKFLOW_RETAINED_VM`](/docs/configuration/runtime-tuning#workflow_retained_vm).
+**The workflow VM is kept alive across inline steps.** Within one invocation, a step- or attribute-driven suspension keeps the live VM and hydrated state, including when hooks or waits are open or created at the same boundary, so the next iteration appends only the newly written events instead of rebuilding the sandbox and replaying the whole log. Step inputs made of plain data or standard built-ins keep this fast path; see [`WORKFLOW_RETAINED_VM`](/docs/configuration/runtime-tuning#workflow_retained_vm).
 
 **Resuming a hook takes one round trip instead of two.** `resumeHook()` writes the `hook_received` event and dispatches the queue message concurrently, with a `(runId, resumeId)` dedup constraint keeping the two writers converging on exactly one event. See [Resilient hook resumption](/docs/changelog/resilient-resume).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.47",
+  "version": "5.0.0-beta.48",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -58,25 +58,25 @@
     }
   },
   "dependencies": {
-    "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.47",
-    "@workflow/cli": "5.0.0-beta.47",
-    "@workflow/core": "5.0.0-beta.47",
-    "@workflow/errors": "5.0.0-beta.19",
+    "@workflow/astro": "5.0.0-beta.48",
+    "@workflow/cli": "5.0.0-beta.48",
+    "@workflow/core": "5.0.0-beta.48",
+    "@workflow/errors": "5.0.0-beta.20",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
     "@workflow/utils": "5.0.0-beta.10",
-    "@workflow/next": "5.0.0-beta.47",
-    "@workflow/nest": "5.0.0-beta.47",
-    "@workflow/nitro": "5.0.0-beta.47",
-    "@workflow/nuxt": "5.0.0-beta.47",
-    "@workflow/sveltekit": "5.0.0-beta.47",
-    "@workflow/rollup": "5.0.0-beta.47"
+    "ms": "2.1.3",
+    "@workflow/next": "5.0.0-beta.48",
+    "@workflow/nest": "5.0.0-beta.48",
+    "@workflow/nitro": "5.0.0-beta.48",
+    "@workflow/nuxt": "5.0.0-beta.48",
+    "@workflow/sveltekit": "5.0.0-beta.48",
+    "@workflow/rollup": "5.0.0-beta.48"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",
     "@types/node": "22.19.0",
-    "typescript": "^6.0.3",
-    "@workflow/tsconfig": "5.0.0-beta.0"
+    "@workflow/tsconfig": "5.0.0-beta.0",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "1"