workflow 4.2.0-beta.75 → 4.2.0-beta.77

package/README.md

@@ -5,7 +5,7 @@
       <img alt="Workflow SDK logo" src="https://useworkflow.dev/workflow-circle-symbol-light.svg" height="128">
     </picture>
   </a>
-  <h1>Workflow Development Kit</h1>
+  <h1>Workflow SDK</h1>
 
 <a href="https://vercel.com"><img alt="Vercel logo" src="https://img.shields.io/badge/MADE%20BY%20Vercel-000000.svg?style=for-the-badge&logo=Vercel&labelColor=000"></a>
 <a href="https://www.npmjs.com/package/workflow"><img alt="NPM version" src="https://img.shields.io/npm/v/workflow?style=for-the-badge&labelColor=000000"></a>
@@ -16,7 +16,7 @@
 
 ## Getting Started
 
-The **Workflow Development Kit** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
+The **Workflow SDK** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
 
 Visit [https://useworkflow.dev](https://useworkflow.dev) to view the full documentation.
 

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -213,7 +213,7 @@ export default OutputSpecification;`}
 - Tools can use core library features like `sleep()` and Hooks within their `execute` functions
 - The agent processes tool calls iteratively until completion or `maxSteps` is reached
 - **Default `maxSteps` is unlimited** - set a value to limit the number of LLM calls
-- The `stream()` method returns `{ messages, steps, experimental_output, uiMessages }` containing the full conversation history, step details, optional structured output, and optionally accumulated UI messages
+- The `stream()` method returns `{ messages, steps, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, step details, tool call details, optional structured output, and optionally accumulated UI messages
 - Use `collectUIMessages: true` to accumulate `UIMessage[]` during streaming, useful for persisting conversation state without re-reading the stream
 - The `prepareStep` callback runs before each step and can modify model, messages, generation settings, tool choice, and context
 - Generation settings (temperature, maxOutputTokens, etc.) can be set on the constructor and overridden per-stream call
@@ -842,6 +842,91 @@ async function saveConversation(messages: UIMessage[]) {
 The `uiMessages` property is only available when `collectUIMessages` is set to `true`. When disabled, `uiMessages` is `undefined`.
 </Callout>
 
+### Machine-Readable Tool Results
+
+`stream()` returns tool call information you can inspect programmatically. Compare `toolCalls` with `toolResults` to find unresolved tool calls that need client-side handling:
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { UIMessageChunk } from "ai";
+
+async function checkOrderStatus({ orderId }: { orderId: string }) {
+  "use step";
+  return `Order ${orderId}: shipped`;
+}
+
+async function agentWithToolInspection(userMessage: string) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    tools: {
+      checkOrderStatus: {
+        description: "Check order status",
+        inputSchema: z.object({ orderId: z.string() }),
+        execute: checkOrderStatus,
+      },
+    },
+  });
+
+  const result = await agent.stream({
+    messages: [{ role: "user", content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+  });
+
+  const unresolved = result.toolCalls.filter( // [!code highlight]
+    (tc) => !result.toolResults.some((tr) => tr.toolCallId === tc.toolCallId) // [!code highlight]
+  ); // [!code highlight]
+
+  if (unresolved.length > 0) {
+    return {
+      status: "needs-client-tools",
+      unresolved,
+    };
+  }
+
+  return {
+    status: "complete",
+    messages: result.messages,
+    toolResults: result.toolResults,
+  };
+}
+```
+
+<Callout type="info">
+`toolCalls` and `toolResults` reflect the *last step* of the agent loop. Tools without an `execute` function will appear in `toolCalls` but not in `toolResults`, which is how you detect calls that need client-side handling.
+</Callout>
+
+### Aborting Long-Running Streams
+
+Use `timeout` to abort a stream automatically after a fixed duration:
+
+<Callout type="warn">
+`abortSignal` is not yet supported and will be available in a future release. Use `timeout` for now.
+</Callout>
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import type { UIMessageChunk } from "ai";
+
+async function agentWithTimeout(userMessage: string) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+  });
+
+  await agent.stream({
+    messages: [{ role: "user", content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+    timeout: 30_000, // [!code highlight]
+  });
+}
+```
+
 ## See Also
 
 - [Building Durable AI Agents](/docs/ai) - Complete guide to creating durable agents

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

@@ -39,23 +39,17 @@ showSections={["returns"]}
 The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-api/world) reference for complete documentation:
 
 <Cards>
-    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
-        List, filter, and inspect workflow runs.
+    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+        Query runs, steps, hooks, and the underlying event log.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
-        List and inspect step execution data.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
-        Look up hooks by ID or token.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
-        Query the append-only event log.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/streams" title="world.streams">
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
         Read, write, and manage data streams.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
-        Enqueue runs and create queue handlers.
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability">
+        Hydrate step I/O, parse display names, decrypt data.
     </Card>
 </Cards>
 
@@ -72,6 +66,57 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 
 See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full hydration, parsing, and encryption API.
 
+### List Workflow Runs (Display Names)
+
+List workflow runs and derive human-readable names from the `workflowName` field:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseWorkflowName } from "@workflow/utils/parse-name"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+
+  try {
+    const world = getWorld(); // [!code highlight]
+    const runs = await world.runs.list({
+      pagination: { cursor },
+      resolveData: "none",
+    });
+
+    return Response.json({
+      data: runs.data.map((run) => {
+        const parsed = parseWorkflowName(run.workflowName); // [!code highlight]
+
+        return {
+          runId: run.runId,
+          // Use shortName for UI display (e.g., "processOrder") // [!code highlight]
+          displayName: parsed?.shortName ?? run.workflowName, // [!code highlight]
+          // Module info available for debugging // [!code highlight]
+          module: parsed?.moduleSpecifier, // [!code highlight]
+          status: run.status,
+          startedAt: run.startedAt,
+          completedAt: run.completedAt,
+        };
+      }),
+      cursor: runs.cursor,
+    });
+  } catch (error) {
+    return Response.json(
+      { error: "Failed to list workflow runs" },
+      { status: 500 }
+    );
+  }
+}
+```
+
+<Callout type="info">
+  The `workflowName` field contains a machine-readable identifier like `workflow//./src/workflows/order//processOrder`.
+  Use `parseWorkflowName()` from `@workflow/utils/parse-name` to extract the `shortName` (e.g., `"processOrder"`)
+  and `moduleSpecifier` for display in your UI.
+</Callout>
+
 ## Related Functions
 
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) - Higher-level API for working with individual runs by ID.

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

@@ -54,6 +54,11 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
 * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
 * All arguments must be [serializable](/docs/foundations/serialization).
+* When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
+
+<Callout type="info">
+If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
+</Callout>
 
 ## Examples
 

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

@@ -22,26 +22,17 @@ import { getWorld } from "workflow/runtime";
 const world = getWorld(); // [!code highlight]
 ```
 
-## Entities
+## Interfaces
 
 <Cards>
-    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
-        List, filter, and inspect workflow runs with pagination and status filtering.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
-        List and inspect step execution data including input/output hydration.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
-        Look up hooks by ID or token for webhook resume flows.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
-        Query the append-only event log — the source of truth for all workflow state changes.
+    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+        Query runs, steps, hooks, and the underlying event log.
     </Card>
     <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
         Read, write, and manage real-time data streams for workflow runs.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
-        Enqueue workflow runs and create queue handlers for processing.
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
     </Card>
     <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability Utilities">
         Hydrate step I/O, parse display names, and decrypt workflow data.

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

@@ -1,12 +1,4 @@
 {
   "title": "World SDK",
-  "pages": [
-    "runs",
-    "steps",
-    "hooks",
-    "events",
-    "streams",
-    "queue",
-    "observability"
-  ]
+  "pages": ["storage", "streams", "queue", "observability"]
 }

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

@@ -6,8 +6,7 @@ summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(),
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 related:
-  - /docs/api-reference/workflow-api/world/steps
-  - /docs/api-reference/workflow-api/world/runs
+  - /docs/api-reference/workflow-api/world/storage
 keywords:
   - workflow/observability
   - hydrateResourceIO
@@ -41,18 +40,14 @@ import { // [!code highlight]
 
 ### hydrateResourceIO()
 
-Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. This is required to display step input/output in your UI.
+Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Required to display step input/output in your UI.
 
 ```typescript lineNumbers
 import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
-import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
 const step = await world.steps.get(runId, stepId);
-
 const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-console.log(hydrated.input); // Deserialized input data
-console.log(hydrated.output); // Deserialized output data
+console.log(hydrated.input, hydrated.output);
 ```
 
 **Parameters:**
@@ -68,77 +63,41 @@ console.log(hydrated.output); // Deserialized output data
 
 A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
 
-```typescript lineNumbers
-import { observabilityRevivers } from "workflow/observability";
-```
-
 ## Name Parsing
 
-Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names.
+Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
 
 ### parseStepName()
 
-Parse a machine-readable step name into its components.
-
 ```typescript lineNumbers
 import { parseStepName } from "workflow/observability"; // [!code highlight]
 
 const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
-// parsed.shortName → "processPayment"
-// parsed.moduleSpecifier → "./src/workflows/order"
+// parsed?.shortName → "processPayment"
+// parsed?.moduleSpecifier → "./src/workflows/order"
 ```
 
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `stepName` | `string` | The machine-readable step name |
-
-**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
-
 ### parseWorkflowName()
 
-Parse a machine-readable workflow name into its components.
-
 ```typescript lineNumbers
 import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
 
 const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
-// parsed.shortName → "processOrder"
-// parsed.moduleSpecifier → "./src/workflows/order"
+// parsed?.shortName → "processOrder"
 ```
 
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `workflowName` | `string` | The machine-readable workflow name |
-
-**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
-
 ### parseClassName()
 
-Parse a machine-readable class name into its components.
-
 ```typescript lineNumbers
 import { parseClassName } from "workflow/observability"; // [!code highlight]
 
 const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
-// parsed.shortName → "User"
-// parsed.moduleSpecifier → "./src/models"
+// parsed?.shortName → "User"
 ```
 
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `className` | `string` | The machine-readable class name |
-
-**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
-
 ## Encryption
 
-For workflows with encrypted step data, use these utilities to decrypt before hydrating.
+For workflows with encrypted step data, decrypt before hydrating.
 
 ### getEncryptionKeyForRun()
 
@@ -165,10 +124,7 @@ Hydrate step or run data using a decryption key. Use this instead of `hydrateRes
 
 {/* @expect-error:2305,2724 */}
 ```typescript lineNumbers
-import { // [!code highlight]
-  getEncryptionKeyForRun, // [!code highlight]
-  hydrateResourceIOWithKey, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
+import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
 
 const key = await getEncryptionKeyForRun(runId); // [!code highlight]
 const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
@@ -185,105 +141,24 @@ const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
 
 ## Examples
 
-### Hydrate Step Input and Output Data
-
-```typescript lineNumbers
-// app/api/workflow-steps/hydrate/route.ts
-import { getWorld } from "workflow/runtime";
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-  parseStepName, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
-  const stepId = url.searchParams.get("stepId");
-
-  if (!runId || !stepId) {
-    return Response.json({ error: "runId and stepId required" }, { status: 400 });
-  }
-
-  const world = getWorld();
-  const step = await world.steps.get(runId, stepId);
-
-  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-  const parsed = parseStepName(step.stepName);
-
-  return Response.json({
-    displayName: parsed?.shortName ?? step.stepName,
-    input: hydrated.input, // [!code highlight]
-    output: hydrated.output, // [!code highlight]
-  });
-}
-```
-
-### Decrypt and Hydrate Encrypted Step Data
-
-For teams with encryption enabled, step data must be decrypted before hydration:
-
-{/* @expect-error:2305,2724 */}
-```typescript lineNumbers
-// app/api/workflow-steps/decrypt/route.ts
-import { getWorld } from "workflow/runtime";
-import { // [!code highlight]
-  getEncryptionKeyForRun, // [!code highlight]
-  hydrateResourceIOWithKey, // [!code highlight]
-  parseStepName, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
-  const stepId = url.searchParams.get("stepId");
-
-  if (!runId || !stepId) {
-    return Response.json({ error: "runId and stepId required" }, { status: 400 });
-  }
-
-  const world = getWorld();
-  const step = await world.steps.get(runId, stepId);
-
-  // Decrypt then hydrate // [!code highlight]
-  const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-  const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
-
-  const parsed = parseStepName(step.stepName);
-
-  return Response.json({
-    displayName: parsed?.shortName ?? step.stepName,
-    input: hydrated.input,
-    output: hydrated.output,
-  });
-}
-```
-
 ### Parse Display Names for a Run's Steps
 
-Build a progress dashboard with human-readable step names:
-
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
 
 const world = getWorld();
-
-// Parse workflow name
 const run = await world.runs.get(runId, { resolveData: "none" });
-const workflowDisplay = parseWorkflowName(run.workflowName); // [!code highlight]
-console.log("Workflow:", workflowDisplay?.shortName); // [!code highlight]
+console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
 
-// Parse step names
 const steps = await world.steps.list({ runId, resolveData: "none" });
 for (const step of steps.data) {
-  const stepDisplay = parseStepName(step.stepName); // [!code highlight]
-  console.log(`  ${stepDisplay?.shortName}: ${step.status}`); // [!code highlight]
+  const parsed = parseStepName(step.stepName); // [!code highlight]
+  console.log(`  ${parsed?.shortName}: ${step.status}`); // [!code highlight]
 }
 ```
 
 ## Related
 
-- [world.steps](/docs/api-reference/workflow-api/world/steps) — Query step data to hydrate
-- [world.runs](/docs/api-reference/workflow-api/world/runs) — Query run data to hydrate
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
 - [Serialization](/docs/foundations/serialization) — How workflow data is serialized

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

@@ -1,8 +1,8 @@
 ---
-title: world.queue
-description: Enqueue workflow runs and create queue handlers for background processing.
+title: Queue
+description: Low-level queue interface for dispatching workflow and step invocations.
 type: reference
-summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Manage workflow run queuing and processing."
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 related:
@@ -13,115 +13,74 @@ keywords:
   - getDeploymentId
   - queue
   - createQueueHandler
-  - background processing
-  - enqueue workflow
   - ValidQueueName
+  - queue dispatch
 ---
 
-The `world.queue` interface provides access to workflow run queuing and processing. Use it to enqueue runs for background execution and create handlers to process queued items.
+Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
+
+<Callout type="warn">
+  These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging resumption of a flow or step route.
+</Callout>
 
 ## Import
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
-const queue = world.queue; // [!code highlight]
+const world = getWorld(); // [!code highlight]
+// Queue methods are called directly on world — e.g. world.queue()
 ```
 
 ## Methods
 
 ### getDeploymentId()
 
-Get the current deployment ID. Useful for routing queue messages to the correct deployment.
+Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
 
 ```typescript lineNumbers
-const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
+const deploymentId = await world.getDeploymentId(); // [!code highlight]
 ```
 
 **Returns:** `string` — The current deployment ID
 
 ### queue()
 
-Enqueue a workflow run for background processing.
+Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
 
 ```typescript lineNumbers
-const messageId = await world.queue.queue(name, message, opts); // [!code highlight]
+const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `ValidQueueName` | The queue name |
-| `message` | `object` | The message payload to enqueue |
-| `opts` | `object` | Optional configuration |
+| `queueName` | `ValidQueueName` | The queue name (branded string) |
+| `message` | `QueuePayload` | Internal SDK payload |
+| `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
 
-**Returns:** `MessageId`
+**Returns:** `{ messageId: MessageId | null }`
 
 ### createQueueHandler()
 
-Create a handler function for processing queued messages.
+Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
 
 ```typescript lineNumbers
-const handler = world.queue.createQueueHandler(prefix, callback); // [!code highlight]
+const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `prefix` | `string` | Queue name prefix to match |
-| `callback` | `function` | Handler function called for each queued message |
-
-**Returns:** Queue handler function
-
-## Examples
-
-### Enqueue a Workflow Run for Background Processing
-
-```typescript lineNumbers
-// app/api/workflow-queue/route.ts
-import { getWorld } from "workflow/runtime";
-
-export async function POST(req: Request) {
-  const { workflowName, input } = await req.json();
-
-  const world = getWorld();
-  const messageId = await world.queue.queue(workflowName, { // [!code highlight]
-    input,
-    priority: "normal",
-  }); // [!code highlight]
-
-  return Response.json({ messageId });
-}
-```
-
-### Create a Queue Handler for Processing
+| `prefix` | `QueuePrefix` | Queue name prefix to match |
+| `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |
 
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-
-const handler = world.queue.createQueueHandler("my-workflows", async (message) => { // [!code highlight]
-  console.log("Processing:", message);
-  // Handle the queued workflow message
-}); // [!code highlight]
-```
-
-### Get Current Deployment ID
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
-console.log("Running on deployment:", deploymentId);
-```
+**Returns:** `(req: Request) => Promise<Response>`
 
 ## Related
 
-- [start()](/docs/api-reference/workflow-api/start) — Higher-level API for starting workflow runs
+- [start()](/docs/api-reference/workflow-api/start) — The standard way to start workflow runs
 - [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
-- [world.runs](/docs/api-reference/workflow-api/world/runs) — Inspect queued and running workflows
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Create events that trigger queue dispatch