workflow 4.4.0 → 4.6.0

package/docs/ai/resumable-streams.mdx

@@ -194,6 +194,10 @@ This avoids replaying potentially thousands of chunks and lets the UI render fas
 When using a negative `initialStartIndex`, the reconnection endpoint **must** return the `x-workflow-stream-tail-index` header (as shown in [Step 2](#add-a-stream-reconnection-endpoint) above). The transport uses this header to compute absolute chunk positions so that retries after a disconnect resume from the correct position. If the header is missing, the transport falls back to `startIndex: 0` (replaying the entire stream) and logs a warning.
 </Callout>
 
+### Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts (`text-*`, `reasoning-*`, `tool-input-*`) that must be opened with a `*-start` before any `*-delta` or `*-end`. A non-zero `startIndex` can land in the middle of an open part. See [`WorkflowChatTransport` → Mid-part resumes](/docs/api-reference/workflow-ai/workflow-chat-transport#mid-part-resumes) for how this is handled and an example of rewinding to a step boundary on the server.
+
 ## Related Documentation
 
 - [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options

package/docs/api-reference/index.mdx

@@ -17,9 +17,33 @@ All the functions and primitives that come with Workflow SDK by package.
     <Card title="workflow/api" href="/docs/api-reference/workflow-api">
         API reference for runtime functions from the `workflow/api` package.
     </Card>
+    <Card title="workflow/runtime" href="/docs/api-reference/workflow-runtime">
+        Runtime functions for resolving the World instance and the low-level World SDK.
+    </Card>
+    <Card title="workflow/observability" href="/docs/api-reference/workflow-observability">
+        Utilities to hydrate step I/O, parse display names, and decrypt workflow data.
+    </Card>
     <Card title="workflow/next" href="/docs/api-reference/workflow-next">
         Next.js integration for Workflow SDK that automatically configures bundling and runtime support.
     </Card>
+    <Card title="workflow/nitro" href="/docs/api-reference/workflow-nitro">
+        Nitro module for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/nuxt" href="/docs/api-reference/workflow-nuxt">
+        Nuxt module for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/sveltekit" href="/docs/api-reference/workflow-sveltekit">
+        SvelteKit Vite plugin for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/astro" href="/docs/api-reference/workflow-astro">
+        Astro integration for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/vite" href="/docs/api-reference/workflow-vite">
+        Standalone Vite plugin for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/nest" href="/docs/api-reference/workflow-nest">
+        NestJS module for workflow bundling and runtime support.
+    </Card>
     <Card title="workflow/errors" href="/docs/api-reference/workflow-errors">
         Semantic error types for handling workflow storage backend failures.
     </Card>

package/docs/api-reference/meta.json

@@ -4,7 +4,15 @@
     "workflow-globals",
     "workflow",
     "workflow-api",
+    "workflow-runtime",
+    "workflow-observability",
     "workflow-next",
+    "workflow-nitro",
+    "workflow-nuxt",
+    "workflow-sveltekit",
+    "workflow-astro",
+    "workflow-vite",
+    "workflow-nest",
     "workflow-errors",
     "workflow-serde",
     "workflow-ai",

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

@@ -11,7 +11,6 @@ The `@workflow/vitest` package provides a Vitest plugin and test helpers for run
 
 Returns a Vite plugin array that handles SWC transforms, bundle building, and in-process handler registration automatically.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -24,7 +23,6 @@ export default defineConfig({
 
 Pass a [`WorkflowTestOptions`](#workflowtestoptions) object when your project uses a non-standard layout — for example, a monorepo where `workflows/` does not live at the Vitest config's directory, or when the default `.workflow-data` / `.workflow-vitest` output locations need to move. The plugin forwards these paths to `buildWorkflowTests()` and `setupWorkflowTests()` through Vitest's per-project provided context, so each Vitest workspace project stays isolated.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -54,7 +52,6 @@ export default defineConfig({
 
 Builds workflow and step bundles to disk. Called automatically by the `workflow()` plugin in `globalSetup`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { buildWorkflowTests } from "@workflow/vitest";
@@ -76,7 +73,6 @@ Sets up an in-process workflow runtime in each test worker. Imports pre-built bu
 
 Called automatically by the `workflow()` plugin in `setupFiles`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { beforeAll, afterAll } from "vitest";
@@ -118,7 +114,6 @@ Tears down the workflow test world. Clears the global world and closes the Local
 
 Polls the event log until the workflow has a pending `sleep()` call — one with a `wait_created` event but no corresponding `wait_completed` event. Returns the correlation ID of the pending sleep, which can be passed to [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to target a specific sleep.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForSleep } from "@workflow/vitest"; // [!code highlight]
@@ -147,7 +142,6 @@ await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlig
 
 Polls the hook list and event log until a hook matching the optional `token` filter exists that hasn't been received yet. Returns the matching hook object.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForHook } from "@workflow/vitest"; // [!code highlight]

package/docs/api-reference/workflow/create-hook.mdx

@@ -65,6 +65,8 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
+Use `hook.getConflict()` (available starting in `workflow@4.5.0`) to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with `{ runId }` identifying the conflicting run if another active hook already owns the same token.
+
 ## Examples
 
 ### Basic Usage
@@ -112,6 +114,36 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
+### Detecting Token Conflicts
+
+Use `hook.getConflict()` (available starting in `workflow@4.5.0`) when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+async function processOrder(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({ // [!code highlight]
+    token: `order:${orderId}` // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active workflow run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  await chargeOrder(orderId);
+}
+```
+
+Because `createHook()` alone does not suspend the workflow, awaiting `hook.getConflict()` is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future `resumeHook()` call, await the hook itself or iterate it with `for await...of`.
+
+On a conflict, the resolved value is `{ runId }` identifying the run that currently owns the token. To act on the owner — inspect its status, wait for its result, or cancel it — pass `conflict.runId` to [`getRun()`](/docs/api-reference/workflow-api/get-run) inside a step. See [Idempotency](/docs/foundations/idempotency) for these strategies in context.
+
 ### Waiting for Multiple Payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.

package/docs/api-reference/workflow/create-webhook.mdx

@@ -55,6 +55,7 @@ The returned `Webhook` object has:
 
 - `url`: The HTTP endpoint URL that external systems can call
 - `token`: The unique token identifying this webhook
+- `getConflict()`: A promise that resolves with `{ runId }` identifying the conflicting run if another active hook already owns this token, or `null` once the webhook endpoint has been registered
 - Implements `AsyncIterable<RequestWithResponse>` for handling multiple requests
 
 The `RequestWithResponse` type extends the standard `Request` interface with a `respondWith(response: Response)` method for sending custom responses back to the caller.

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

@@ -254,6 +254,45 @@ export default function ChatWithCustomConfig() {
 }
 ```
 
+## Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts: a `text-start` opens a text part that subsequent `text-delta`s extend and a `text-end` closes, and the same shape applies to `reasoning-*` and `tool-input-*`. The AI SDK client enforces that grammar — a `reasoning-delta` whose `reasoning-start` was never seen throws and breaks the chat.
+
+A non-zero `startIndex` (in particular a negative `initialStartIndex`) resolves to a chunk offset with no awareness of those part boundaries, so it can land in the middle of an open part. When that happens, `WorkflowChatTransport` will **drop chunks that reference a part it didn't see a start for** and log a one-time warning. The chat keeps working, but any partial part overlapping the resume cursor is discarded. Tool calls are an exception: `tool-input-available` / `tool-input-error` chunks are self-contained (they carry the full input), so a tool call is recovered as soon as one of those chunks appears in the resumed window — only its streamed input deltas are lost.
+
+To preserve those partial parts, rewind to a step boundary on the server before returning the readable. `start-step` / `finish-step` chunks are the natural seams — no UI part is ever open across them. Sketch:
+
+{/*@skip-typecheck: incomplete code sample*/}
+
+```typescript title="app/api/chat/[id]/stream/route.ts"
+const run = getRun(id);
+const tailIndex = await run.getReadable().getTailIndex();
+
+let resolved = startIndex < 0
+  ? Math.max(0, tailIndex + 1 + startIndex)
+  : startIndex;
+
+if (startIndex !== 0) {
+  // Walk back from `resolved` to the most recent start-step (or chunk 0),
+  // capping the lookback so a single huge step can't trigger an unbounded scan.
+  const LOOKBACK = 200;
+  const probe = run.getReadable({ startIndex: Math.max(0, resolved - LOOKBACK) });
+  let i = Math.max(0, resolved - LOOKBACK);
+  let lastBoundary = i;
+  for await (const chunk of probe as unknown as AsyncIterable<{ type: string }>) {
+    if (i >= resolved) break;
+    if (chunk.type === "start-step") lastBoundary = i;
+    i++;
+  }
+  resolved = lastBoundary;
+}
+
+return createUIMessageStreamResponse({
+  stream: run.getReadable({ startIndex: resolved }),
+  headers: { "x-workflow-stream-tail-index": String(tailIndex) },
+});
+```
+
 ## See Also
 
 - [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - Building durable AI agents within workflows

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

@@ -1,6 +1,6 @@
 ---
 title: "workflow/api"
-description: Runtime functions to inspect runs, start workflows, and access world data.
+description: Runtime functions to inspect runs, start workflows, and manage hooks.
 type: overview
 summary: Explore runtime functions for starting workflows, inspecting runs, and managing hooks.
 ---
@@ -9,7 +9,7 @@ API reference for runtime functions from the `workflow/api` package.
 
 ## Functions
 
-The API package is for access and introspection of workflow data to inspect runs, start new runs, or access anything else directly accessible by the world.
+The API package is for access and introspection of workflow data to inspect runs, start new runs, and manage hooks.
 
 <Cards>
     <Card href="/docs/api-reference/workflow-api/start" title="start()">
@@ -27,10 +27,8 @@ The API package is for access and introspection of workflow data to inspect runs
     <Card href="/docs/api-reference/workflow-api/get-run" title="getRun()">
         Get workflow run status and metadata without waiting for completion.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
-        Get direct access to workflow storage, queuing, and streaming backends.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
-        Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
-    </Card>
 </Cards>
+
+<Callout type="info">
+  Looking for `getWorld()` and the World SDK? They are exported from `workflow/runtime` — see the [`workflow/runtime` reference](/docs/api-reference/workflow-runtime).
+</Callout>

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

@@ -97,6 +97,8 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 
 <Callout type="info">
 The `deploymentId` option is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+
+In Worlds without atomic, immutable deployments (such as local development or self-hosted Postgres), there is no notion of multiple deployments to resolve between, so `deploymentId: "latest"` has no effect: the SDK logs a warning and the run targets the current deployment. This means a workflow that opts into `"latest"` on Vercel still runs unchanged in local development.
 </Callout>
 
 <Callout type="warn">

package/docs/api-reference/workflow-errors/meta.json

@@ -1,16 +1,21 @@
 {
   "title": "workflow/errors",
   "pages": [
+    "workflow-error",
     "hook-not-found-error",
+    "hook-conflict-error",
     "step-not-registered-error",
     "workflow-not-registered-error",
     "workflow-run-not-found-error",
     "workflow-run-failed-error",
     "workflow-run-cancelled-error",
+    "workflow-run-not-completed-error",
+    "workflow-runtime-error",
     "workflow-world-error",
     "throttle-error",
     "entity-conflict-error",
     "run-expired-error",
+    "run-not-supported-error",
     "too-early-error"
   ]
 }

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -31,11 +31,35 @@ export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 If a package in `serverExternalPackages` contains workflow code (`"use step"`,
 `"use workflow"`, or serialization classes), `withWorkflow()` automatically
 removes it from `serverExternalPackages` for the current build and prints a
-warning. This ensures the package still gets transformed by the Workflow
-compiler. Remove that package from `serverExternalPackages` in your
+warning. Workflow still compiles the package so its directives are transformed.
+Remove that package from `serverExternalPackages` in your
 `next.config` to silence the warning.
 </Callout>
 
+### Workflow Discovery in Next.js
+
+`withWorkflow()` discovers workflows by scanning your Next.js entrypoints — App
+Router `route`, `page`, and `layout` files (under `app/` or `src/app/`) and any
+file under `pages/` or `src/pages/` — for `start()` calls imported from
+`workflow/api`. The workflow and step files themselves can live anywhere (for
+example `src/workflows/`); they are discovered transitively through imports, as
+long as a `start()` call in an entrypoint statically reaches them.
+
+<Callout type="info">
+Call `start()` from server-side entrypoints, including Route Handlers and Server
+Actions. Don't call workflow functions directly — that bypasses the workflow
+runtime.
+</Callout>
+
+### Next.js Server Actions and `"use server"`
+
+Don't put a top-level `"use server"` directive in modules imported by workflow
+or step functions. Workflow transformation wraps imported modules in synchronous
+initializers, and Next.js rejects a `"use server"` directive inside that wrapper
+with errors like `Server Actions must be async functions`. Keep `"use server"`
+on the files that define your Server Actions, and move shared logic into
+separate modules that don't carry the directive.
+
 ### Monorepos and Workspace Imports
 
 By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as `apps/web` and workspace resolution is not working correctly, you can set `outputFileTracingRoot` as a workaround:
@@ -68,7 +92,6 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: true,
     local: {
       port: 4000,
     },
@@ -78,7 +101,6 @@ export default withWorkflow(nextConfig, {
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
 
 <Callout type="info">

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

@@ -29,7 +29,6 @@ The `@workflow/serde` package provides two symbols that allow you to define cust
 
 ## Quick Example
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";

package/docs/api-reference/workflow-serde/workflow-deserialize.mdx

@@ -6,7 +6,6 @@ A symbol used to define custom deserialization for user-defined class instances.
 
 ## Usage
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
@@ -26,7 +25,7 @@ class Point {
 
 ## API Signature
 
-{/* @skip-typecheck */}
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
 ```typescript
 static [WORKFLOW_DESERIALIZE](data: SerializableData): T

package/docs/api-reference/workflow-serde/workflow-serialize.mdx

@@ -6,7 +6,6 @@ A symbol used to define custom serialization for user-defined class instances. T
 
 ## Usage
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
@@ -26,7 +25,7 @@ class Point {
 
 ## API Signature
 
-{/* @skip-typecheck */}
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
 ```typescript
 static [WORKFLOW_SERIALIZE](instance: T): SerializableData

package/docs/deploying/world/postgres-world.mdx

@@ -31,10 +31,42 @@ WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
 
 Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` is set when running this command:
 
+<Tabs items={["npm", "pnpm", "Yarn", "Bun"]}>
+
+<Tab value="npm">
+
+```bash
+npx --package=@workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm dlx --package @workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="Yarn">
+
+```bash
+yarn dlx --package @workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="Bun">
+
 ```bash
-npx workflow-postgres-setup
+bunx --package @workflow/world-postgres bootstrap
 ```
 
+</Tab>
+
+</Tabs>
+
 <Callout type="info">
 The migration is idempotent and can safely be run as a post-deployment lifecycle script.
 </Callout>

package/docs/deploying/world/vercel-world.mdx

@@ -48,6 +48,8 @@ For self-hosted deployments, use the [Postgres World](/worlds/postgres). For loc
 
 - **Data residency** - The Vercel World is currently deployed in the `iad1` region. This means independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region.
 
+- **Stream routes need `supportsCancellation`** - Routes that pipe `run.getReadable()` back to a client keep running — and billing — until the function's max duration, even after the client disconnects. Set [`supportsCancellation`](https://vercel.com/docs/functions/request-cancellation) in `vercel.json` for those routes so client aborts tear the invocation down. See [Streaming — Resuming Streams from a Specific Point](/docs/foundations/streaming#resuming-streams-from-a-specific-point).
+
 ## Observability
 
 Workflow observability is built into the Vercel dashboard on your project page. It respects your existing authentication and project permission settings.

package/docs/errors/index.mdx

@@ -43,6 +43,9 @@ Fix common mistakes when creating and executing workflows in the **Workflow SDK*
     <Card href="/docs/errors/step-not-registered" title="step-not-registered">
         Resolve step not registered errors caused by deployment mismatches.
     </Card>
+    <Card href="/docs/errors/step-executed-multiple-times" title="Step executed multiple times">
+        Diagnose duplicate step_started events from function crashes, timeouts, or OOMs.
+    </Card>
     <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
         Resolve workflow not registered errors caused by deployment mismatches.
     </Card>

package/docs/foundations/hooks.mdx

@@ -85,6 +85,35 @@ The key points:
 - You need the hook's `token` to resume it
 - The workflow will resume execution right where it left off
 
+### Checking for Token Conflicts
+
+Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` (available starting in `workflow@4.5.0`) for that:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOrder(orderId: string): Promise<void>; // @setup
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({
+    token: `order:${orderId}`
+  });
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  // The hook token is registered and reserved here.
+  await processOrder(orderId);
+}
+```
+
+Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with `{ runId }` identifying the run that owns the token if another active hook already claimed it (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. To act on the owner — inspect its status, wait for its result, or cancel it — pass `conflict.runId` to [`getRun()`](/docs/api-reference/workflow-api/get-run) inside a step. See [Idempotency](/docs/foundations/idempotency) for these strategies.
+
 ### Custom Tokens for Deterministic Hooks
 
 By default, hooks generate a random token. However, you often want to use a **custom token** that external systems can reconstruct. This is especially useful for long-running workflows where the same workflow instance should handle multiple events.

package/docs/foundations/streaming.mdx

@@ -87,6 +87,12 @@ export async function GET(
 
 This allows clients to reconnect and continue receiving data from where they left off, rather than restarting from the beginning.
 
+<Callout type="warn">
+**Vercel: long-lived stream routes need `supportsCancellation`**
+
+When a route like the one above pipes `run.getReadable()` out to a client on Vercel, the function keeps running — and billing — until the function's configured max duration, even after the client disconnects. Set [`supportsCancellation`](https://vercel.com/docs/functions/request-cancellation) in `vercel.json` for routes that stream workflow output so Vercel forwards the client abort signal and tears the invocation down when the client goes away.
+</Callout>
+
 `startIndex` also supports **negative values** to read relative to the end of the stream. For example, `startIndex: -5` starts 5 chunks before the current end. This is useful when you want to show the most recent output without reading the entire stream history.
 
 On an active (not-yet-closed) stream, the negative index resolves relative to the chunk count at connection time; any chunks written afterward are still delivered normally.
@@ -593,7 +599,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
+- [world.streams](/docs/api-reference/workflow-runtime/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/docs/foundations/versioning.mdx

@@ -93,7 +93,7 @@ npx workflow cancel \
   --backend vercel
 ```
 
-The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-api/world/observability) when you need display-friendly names.
+The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-observability/parse-workflow-name) when you need display-friendly names.
 
 In the [observability UI](/docs/observability), use **Rerun on latest** to enqueue the workflow again with the same inputs against the latest deployment.
 

package/docs/how-it-works/encryption.mdx

@@ -105,8 +105,8 @@ To add encryption support to a custom `World`:
 import type { WorkflowRun, World } from "@workflow/world";
 
 export const getEncryptionKeyForRun: World["getEncryptionKeyForRun"] = async (
-  run,
-  context
+  run: WorkflowRun | string,
+  context?: Record<string, unknown>
 ) => {
   const runId = typeof run === "string" ? run : run.runId;
   const deploymentId =

package/docs/how-it-works/event-sourcing.mdx

@@ -127,7 +127,7 @@ flowchart TD
 
 Unlike other entities, hooks don't have a `status` field—the states above are conceptual. An "active" hook is one that exists in storage, while "disposed" means the hook has been deleted. When a `hook_disposed` event is created, the hook record is removed rather than updated.
 
-While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that currently owns it, though older persisted events or world implementations may only include the token. This causes the hook's promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
+While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that currently owns it, though older persisted events or world implementations may only include the token. This causes `hook.getConflict()` to resolve with the conflicting run and the hook's payload promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
 
 When a hook is disposed (either explicitly or when its workflow completes), the token is released and can be claimed by future workflows. Hooks are automatically disposed when a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`). The `hook_disposed` event is only needed for explicit disposal before workflow completion.
 
@@ -188,7 +188,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 | Event | Description |
 |-------|-------------|
 | `hook_created` | Creates a new hook in `active` state. Contains the hook token and optional metadata. |
-| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. Contains the token and, for current worlds, the active hook owner's run ID. The hook is not created, and awaiting the hook will reject with a `HookConflictError`. |
+| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. Contains the token and, for current worlds, the active hook owner's run ID. The hook is not created: `hook.getConflict()` resolves with the conflicting run, and awaiting the hook payload rejects with a `HookConflictError`. |
 | `hook_received` | Records that a payload was delivered to the hook. The hook remains `active` and can receive more payloads. |
 | `hook_disposed` | Deletes the hook from storage (conceptually transitioning to `disposed` state). The token is released for reuse by future workflows. |
 

package/docs/observability/index.mdx

@@ -42,6 +42,19 @@ npx workflow inspect runs --web
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+To share a link to a specific run without opening a browser, use the `--url`
+flag. It prints the dashboard deep link to stdout and exits (no browser, no
+local server) — useful for scripts, PR comments, or automation. Add `--json` to
+get `{ "url": "..." }`.
+
+```bash
+# Print the deep-link URL for a run (no browser, no server)
+npx workflow inspect run <run_id> --url
+
+# Vercel runs: add the backend (and --env preview for preview deployments)
+npx workflow inspect run <run_id> --backend vercel --url
+```
+
 ## Backends
 
 The Workflow SDK CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the

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

@@ -0,0 +1,18 @@
+---
+title: "workflow/astro"
+description: Astro integration for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Astro integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/astro
+---
+
+Astro integration for Workflow SDK that transforms workflow code and builds the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-astro/workflow">
+        Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives)
+    </Card>
+</Cards>

package/docs/v4/api-reference/workflow-astro/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/astro",
+  "pages": ["workflow"]
+}

package/docs/v4/api-reference/workflow-astro/workflow.mdx

@@ -0,0 +1,37 @@
+---
+title: workflow
+description: Configure Astro to transform workflow directives.
+type: reference
+summary: Add the workflow integration to your Astro config to enable workflow directive transformation.
+prerequisites:
+  - /docs/getting-started/astro
+---
+
+Returns an Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives) and builds the workflow bundles.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `integrations` array of your Astro config.
+
+```typescript title="astro.config.mjs" lineNumbers
+// @ts-check
+import { defineConfig } from "astro/config";
+import { workflow } from "workflow/astro"; // [!code highlight]
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [workflow()], // [!code highlight]
+});
+```
+
+The integration registers the workflow Vite transform plugins during `astro:config:setup` and builds the workflow bundles — locally during config setup, or via the Vercel builder after `astro:build:done` when deploying to Vercel.
+
+## API Signature
+
+### Parameters
+
+This function does not accept any parameters in workflow 4.x. (5.x adds an options object with a `sourcemap` setting.)
+
+### Returns
+
+Returns an `AstroIntegration` object to include in the `integrations` array of your Astro config.