workflow 4.2.0-beta.71 → 4.2.0-beta.72

package/dist/api.d.ts

@@ -1,2 +1,2 @@
-export { type Event, getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, type StartOptions, start, type StopSleepOptions, type StopSleepResult, type WorkflowReadableStreamOptions, type WorkflowRun, } from '@workflow/core/runtime';
+export { type Event, getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, type StartOptions, start, type StopSleepOptions, type StopSleepResult, type WorkflowReadableStream, type WorkflowReadableStreamOptions, type WorkflowRun, } from '@workflow/core/runtime';
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,cAAc,EACd,MAAM,EACN,GAAG,EACH,UAAU,EACV,aAAa,EACb,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,6BAA6B,EAClC,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,cAAc,EACd,MAAM,EACN,GAAG,EACH,UAAU,EACV,aAAa,EACb,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/api.js

@@ -1,2 +1,2 @@
 export { getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, start, } from '@workflow/core/runtime';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBRUwsY0FBYyxFQUNkLE1BQU0sRUFDTixHQUFHLEVBQ0gsVUFBVSxFQUNWLGFBQWEsRUFDYixPQUFPLEVBRVAsS0FBSyxHQUtOLE1BQU0sd0JBQXdCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBRUwsY0FBYyxFQUNkLE1BQU0sRUFDTixHQUFHLEVBQ0gsVUFBVSxFQUNWLGFBQWEsRUFDYixPQUFPLEVBRVAsS0FBSyxHQU1OLE1BQU0sd0JBQXdCLENBQUMifQ==

package/dist/internal/errors.d.ts

@@ -1,2 +1,2 @@
-export { WorkflowAPIError, WorkflowError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, } from '@workflow/errors';
+export { EntityConflictError, HookConflictError, HookNotFoundError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, 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,gBAAgB,EAChB,aAAa,EACb,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,GACrB,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,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"}

package/dist/internal/errors.js

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

package/dist/observability.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Observability utilities for hydrating serialized workflow data.
+ *
+ * Use these when inspecting workflow step I/O, run inputs/outputs,
+ * or event data from the Workflow SDK's world APIs.
+ *
+ * @example
+ * ```ts
+ * import { getWorld } from 'workflow/api';
+ * import { hydrateResourceIO, observabilityRevivers } from 'workflow/observability';
+ *
+ * const world = getWorld();
+ * const step = await world.steps.get(runId, stepId, { resolveData: 'all' });
+ * const hydrated = hydrateResourceIO(step, observabilityRevivers);
+ * // hydrated.input and hydrated.output are now plain JS objects
+ * ```
+ */
+export { hydrateData, hydrateResourceIO, observabilityRevivers, type Revivers, } from '@workflow/core/serialization-format';
+export { parseClassName, parseStepName, parseWorkflowName, } from '@workflow/utils';
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,QAAQ,GACd,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,iBAAiB,CAAC"}

package/dist/observability.js

@@ -0,0 +1,20 @@
+/**
+ * Observability utilities for hydrating serialized workflow data.
+ *
+ * Use these when inspecting workflow step I/O, run inputs/outputs,
+ * or event data from the Workflow SDK's world APIs.
+ *
+ * @example
+ * ```ts
+ * import { getWorld } from 'workflow/api';
+ * import { hydrateResourceIO, observabilityRevivers } from 'workflow/observability';
+ *
+ * const world = getWorld();
+ * const step = await world.steps.get(runId, stepId, { resolveData: 'all' });
+ * const hydrated = hydrateResourceIO(step, observabilityRevivers);
+ * // hydrated.input and hydrated.output are now plain JS objects
+ * ```
+ */
+export { hydrateData, hydrateResourceIO, observabilityRevivers, } from '@workflow/core/serialization-format';
+export { parseClassName, parseStepName, parseWorkflowName, } from '@workflow/utils';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib2JzZXJ2YWJpbGl0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9vYnNlcnZhYmlsaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7O0dBZ0JHO0FBQ0gsT0FBTyxFQUNMLFdBQVcsRUFDWCxpQkFBaUIsRUFDakIscUJBQXFCLEdBRXRCLE1BQU0scUNBQXFDLENBQUM7QUFFN0MsT0FBTyxFQUNMLGNBQWMsRUFDZCxhQUFhLEVBQ2IsaUJBQWlCLEdBQ2xCLE1BQU0saUJBQWlCLENBQUMifQ==

package/docs/ai/defining-tools.mdx

@@ -23,6 +23,9 @@ Just like in regular AI SDK tool definitions, tool in DurableAgent are called wi
 When you tool needs access to the full message history, you can access it via the `messages` property of the tool call context:
 
 ```typescript title="tools.ts" lineNumbers
+import { Experimental_Agent as Agent } from "ai";
+import type { ModelMessage } from "ai";
+
 async function getWeather(
   { city }: { city: string },
   { messages, toolCallId }: { messages: ModelMessage[], toolCallId: string }) { // [!code highlight]
@@ -65,6 +68,9 @@ Tools can be implemented either at the step level or the workflow level, with di
 Tools can also combine both by starting out on the workflow level, and calling into steps for I/O operations, like so:
 
 ```typescript title="tools.ts" lineNumbers
+import { sleep } from "workflow";
+import type { LanguageModel, ModelMessage } from "ai";
+
 // Step: handles I/O with retries
 async function performFetch(url: string) {
   "use step";

package/docs/ai/index.mdx

@@ -123,6 +123,9 @@ The core code that makes all of this happen is quite simple. Here's a breakdown
 Our API route makes a simple call to [AI SDK's `Agent` class](https://ai-sdk.dev/docs/agents/overview), which is a simple wrapper around [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
+import { Experimental_Agent as Agent } from "ai";
+import type { LanguageModel } from "ai";
+
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const agent = new Agent({ // [!code highlight]

package/docs/ai/message-queueing.mdx

@@ -32,6 +32,8 @@ If you just need basic multi-turn conversations where messages arrive between tu
 The `prepareStep` callback runs before each step in the agent loop. It receives the current state and can modify the messages sent to the model:
 
 ```typescript lineNumbers
+import type { ModelMessage, LanguageModel } from "ai";
+
 interface PrepareStepInfo {
   model: string | (() => Promise<LanguageModel>);    // Current model
   stepNumber: number;                                // 0-indexed step count

package/docs/ai/resumable-streams.mdx

@@ -30,7 +30,8 @@ Let's add stream resumption to our Flight Booking Agent that we build in the [Bu
 
 Modify your chat endpoint to include the workflow run ID in a response header. The Run ID uniquely identifies the run's stream, so it allows the client to know which stream to reconnect to.
 
-{/* @skip-typecheck: incomplete code sample */}
+{/*@skip-typecheck: incomplete code sample*/}
+
 ```typescript title="app/api/chat/route.ts" lineNumbers
 // ... imports ...
 
@@ -76,14 +77,24 @@ export async function GET(
 
   // Instead of starting a new run, we fetch an existing run.
   const run = getRun(id); // [!code highlight]
-  const stream = run.getReadable({ startIndex }); // [!code highlight]
+  const readable = run.getReadable({ startIndex }); // [!code highlight]
+
+  // Provide the stream's tail index so the transport can resolve
+  // negative startIndex values into absolute positions for retries.
+  const tailIndex = await readable.getTailIndex(); // [!code highlight]
 
-  return createUIMessageStreamResponse({ stream }); // [!code highlight]
+  return createUIMessageStreamResponse({
+    stream: readable, // [!code highlight]
+    headers: { // [!code highlight]
+      "x-workflow-stream-tail-index": String(tailIndex), // [!code highlight]
+    }, // [!code highlight]
+  });
 }
 ```
 
-The `startIndex` parameter ensures the client can choose where to resume the stream from. For instance, if the function times out during streaming, the chat transport will use `startIndex` to resume the stream exactly from the last token it received.
+The `startIndex` parameter ensures the client can choose where to resume the stream from. For instance, if the function times out during streaming, the chat transport will use `startIndex` to resume the stream exactly from the last token it received. Negative values are also supported (e.g. `-5` starts 5 chunks before the end), which is useful for custom stream consumers (such as a dashboard showing recent output) that want to show the most recent output without replaying the full stream.
 
+When using a negative `startIndex`, your stream endpoint must return a `x-workflow-stream-tail-index` header in order for relative resumption to work. Missing the header will fall back to replaying the entire stream.
 </Step>
 
 <Step>
@@ -161,6 +172,28 @@ Now try the flight booking example again. Open it up in a separate tab, or spam
 
 This approach also handles page refreshes, as the client will automatically reconnect to the stream from the last known position when the UI loads with a stored run ID, following the behavior of [AI SDK's stream resumption](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-resume-streams#chatbot-resume-streams).
 
+### Resuming from the end of the stream
+
+By default, reconnecting replays the entire stream from the beginning (`startIndex: 0`). If you only need to show recent output — for example, when resuming a long conversation after a page refresh — you can set `initialStartIndex` to a negative value to read from the end of the stream instead:
+
+{/*@skip-typecheck: incomplete code sample*/}
+
+```typescript
+const { messages, sendMessage } = useChat({
+  resume: !!activeWorkflowRunId,
+  transport: new WorkflowChatTransport({
+    initialStartIndex: -20, // Only fetch the last 20 chunks // [!code highlight]
+    // ... callbacks as above
+  }),
+});
+```
+
+This avoids replaying potentially thousands of chunks and lets the UI render faster. The negative value is resolved server-side, so `-20` on a 500-chunk stream starts at chunk 480.
+
+<Callout>
+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>
+
 ## Related Documentation
 
 - [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options

package/docs/ai/sleep-and-delays.mdx

@@ -162,6 +162,8 @@ Aside from providing `sleep()` as a tool, there are other use cases for Agents t
 When hitting API rate limits, use `RetryableError` with a delay:
 
 ```typescript lineNumbers
+import { RetryableError } from "workflow";
+
 async function callRateLimitedAPI(endpoint: string) {
   "use step";
 

package/docs/api-reference/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "API Reference",
-  "pages": ["...", "workflow-serde", "workflow-ai", "vitest"]
+  "pages": ["...", "workflow-errors", "workflow-serde", "workflow-ai", "vitest"]
 }

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

@@ -193,6 +193,8 @@ export const approvalHook = defineHook({
 Tokens are used to identify a specific hook and for resuming a hook. You can customize the token to be more specific to a use case.
 
 ```typescript lineNumbers
+import { defineHook } from "workflow";
+
 const slackHook = defineHook<{ text: string; userId: string }>();
 
 export async function slackBotWorkflow(channelId: string) {

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

@@ -208,6 +208,7 @@ Here's a more complex example showing how you might stream AI chat responses:
 ```typescript lineNumbers
 import { getWritable } from "workflow";
 import { generateId, streamText, type UIMessageChunk } from "ai";
+import type { ModelMessage } from "ai";
 
 export async function chat(messages: ModelMessage[]) {
   "use workflow";

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

@@ -317,6 +317,8 @@ async function multiToolAgentWorkflow(userQuery: string) {
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import type { UIMessageChunk } from "ai";
 import { z } from "zod";
 
 async function searchProducts({ query }: { query: string }) {

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

@@ -71,6 +71,8 @@ export default WorkflowChatTransportOptions;`}
 - The `onChatSendMessage` callback receives the full response object, allowing you to extract and store the workflow run ID for session resumption
 - Stream interruptions are automatically detected when a "finish" chunk is not received in the initial response
 - The `maxConsecutiveErrors` option controls how many reconnection attempts are made before giving up (default: 3)
+- `initialStartIndex` (constructor option) sets the default chunk position for the **first** reconnection attempt (e.g. after a page refresh). Subsequent retries within the same reconnection loop always resume from the last received chunk. Negative values (e.g. `-20`) read from the end of the stream, which is useful for showing only recent output without replaying the full conversation. `startIndex` (per-call option on `reconnectToStream`) overrides `initialStartIndex` for a single reconnection
+- When using a negative `initialStartIndex`, the reconnection endpoint must return the `x-workflow-stream-tail-index` response header (via `readable.getTailIndex()`). The transport reads this header to compute absolute chunk positions for retries. Without it, startIndex is assumed to be 0, replaying the entire stream
 
 ## Examples
 

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

@@ -39,6 +39,18 @@ export default Run;`}
 showSections={["returns"]}
 />
 
+#### WorkflowReadableStream
+
+`run.getReadable()` returns a `WorkflowReadableStream` — a standard `ReadableStream` extended with a `getTailIndex()` helper:
+
+<TSDoc
+definition={`
+import type { WorkflowReadableStream } from "workflow/api";
+export default WorkflowReadableStream;`}
+/>
+
+`getTailIndex()` returns the index of the last known chunk (0-based), or `-1` when no chunks have been written. This is useful when building [reconnection endpoints](/docs/ai/resumable-streams) that need to inform clients where the stream starts.
+
 #### WorkflowReadableStreamOptions
 
 <TSDoc
@@ -144,6 +156,8 @@ export async function POST(req: Request) {
 You can also target specific sleep calls by correlation ID:
 
 ```typescript lineNumbers
+import { getRun } from "workflow/api";
+
 const run = getRun("my-run-id"); // @setup
 const { stoppedCount } = await run.wakeUp({
   correlationIds: ["wait_abc123"],

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

@@ -91,6 +91,111 @@ export async function POST(req: Request) {
 }
 ```
 
+### List Steps for a Run (Without Data)
+
+List steps for a workflow run with `resolveData: 'none'` to efficiently get step metadata without fetching serialized input/output. Use `parseStepName` to extract user-friendly display names:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseStepName } from "@workflow/utils/parse-name"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+
+  if (!runId) {
+    return Response.json({ error: "No runId provided" }, { status: 400 });
+  }
+
+  try {
+    const world = getWorld(); // [!code highlight]
+    const steps = await world.steps.list({ // [!code highlight]
+      runId, // [!code highlight]
+      resolveData: "none", // Skip fetching input/output for performance // [!code highlight]
+    }); // [!code highlight]
+
+    // Map steps to a progress view using parseStepName for display
+    const progress = steps.data.map((step) => {
+      const parsed = parseStepName(step.stepName); // [!code highlight]
+      return {
+        stepId: step.stepId,
+        // Use shortName for UI display (e.g., "fetchUserData") // [!code highlight]
+        displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
+        // Module info available for debugging // [!code highlight]
+        module: parsed?.moduleSpecifier, // [!code highlight]
+        status: step.status,
+        startedAt: step.startedAt,
+        completedAt: step.completedAt,
+      };
+    });
+
+    return Response.json({ progress, cursor: steps.cursor });
+  } catch (error) {
+    return Response.json(
+      { error: "Failed to list steps" },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Get Step with Hydrated Input/Output
+
+Retrieve a step with its serialized data and hydrate it for display. This example shows how to decrypt and deserialize step input/output:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseStepName } from "@workflow/utils/parse-name"; // [!code highlight]
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+} from "@workflow/core/serialization-format"; // [!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 });
+  }
+
+  try {
+    const world = getWorld(); // [!code highlight]
+    // Fetch step with data (default resolveData behavior) // [!code highlight]
+    const step = await world.steps.get(runId, stepId); // [!code highlight]
+
+    // Hydrate serialized input/output for display // [!code highlight]
+    const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+
+    // Parse the stepName for user-friendly display
+    const parsed = parseStepName(step.stepName);
+
+    return Response.json({
+      stepId: hydrated.stepId,
+      displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
+      module: parsed?.moduleSpecifier, // [!code highlight]
+      status: hydrated.status,
+      attempt: hydrated.attempt,
+      // Hydrated input/output ready for rendering // [!code highlight]
+      input: hydrated.input, // [!code highlight]
+      output: hydrated.output, // [!code highlight]
+    });
+  } catch (error) {
+    return Response.json(
+      { error: "Step not found" },
+      { status: 404 }
+    );
+  }
+}
+```
+
+<Callout type="info">
+  The `stepName` field contains a machine-readable identifier like `step//./src/workflows/order//processPayment`.
+  Use `parseStepName()` from `@workflow/utils/parse-name` to extract the `shortName` (e.g., `"processPayment"`)
+  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-errors/entity-conflict-error.mdx

@@ -0,0 +1,60 @@
+---
+title: EntityConflictError
+description: Thrown when a storage operation conflicts with the current entity state.
+type: reference
+summary: Catch EntityConflictError when a world operation conflicts with entity state (e.g. duplicate events or runs).
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/run-expired-error
+---
+
+`EntityConflictError` is thrown by world implementations when a storage operation conflicts with the current entity state. This includes cases like creating a run that already exists or writing an event that has already been persisted.
+
+It corresponds to HTTP 409 Conflict semantics.
+
+<Callout>
+The Workflow runtime handles this error automatically during replay and event deduplication. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { EntityConflictError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (EntityConflictError.is(error)) { // [!code highlight]
+    // Event already exists — safe to ignore during replay
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface EntityConflictError {
+  /** The error message. */
+  message: string;
+}
+export default EntityConflictError;`}
+/>
+
+### Static Methods
+
+#### `EntityConflictError.is(value)`
+
+Type-safe check for `EntityConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { EntityConflictError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (EntityConflictError.is(error)) {
+  // error is typed as EntityConflictError
+}
+```

package/docs/api-reference/workflow-errors/hook-not-found-error.mdx

@@ -0,0 +1,90 @@
+---
+title: HookNotFoundError
+description: Thrown when resuming a hook that does not exist.
+type: reference
+summary: Catch HookNotFoundError when calling resumeHook() or resumeWebhook() with a token that doesn't match any active hook.
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/api-reference/workflow/define-hook
+---
+
+`HookNotFoundError` is thrown when calling `resumeHook()` or `resumeWebhook()` with a token that does not match any active hook. This typically happens when:
+
+- The hook has expired (past its TTL)
+- The hook was already consumed and disposed
+- The workflow has not started yet, so the hook does not exist
+
+```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors"
+declare function resumeHook(token: string, payload: any): Promise<any>; // @setup
+declare const token: string; // @setup
+declare const payload: any; // @setup
+
+try {
+  await resumeHook(token, payload);
+} catch (error) {
+  if (HookNotFoundError.is(error)) { // [!code highlight]
+    console.error("Hook not found:", error.token);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface HookNotFoundError {
+  /** The hook token that was not found. */
+  token: string;
+  /** The error message. */
+  message: string;
+}
+export default HookNotFoundError;`}
+/>
+
+### Static Methods
+
+#### `HookNotFoundError.is(value)`
+
+Type-safe check for `HookNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { HookNotFoundError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (HookNotFoundError.is(error)) {
+  // error is typed as HookNotFoundError
+}
+```
+
+## Examples
+
+### Resume hook or start workflow
+
+A common pattern for idempotent workflows is to try resuming a hook, and if it doesn't exist yet, start a new workflow run with the input data.
+
+<Callout>
+This "resume or start" pattern is not atomic — there is a small window where a race condition is possible. A better native approach is being worked on, but this pattern works well for many use cases.
+</Callout>
+
+```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors"
+declare function resumeHook(token: string, data: unknown): Promise<any>; // @setup
+declare function startWorkflow(name: string, data: unknown): Promise<any>; // @setup
+
+async function handleIncomingEvent(token: string, data: unknown) {
+  try {
+    // Try to resume an existing hook
+    await resumeHook(token, data);
+  } catch (error) {
+    if (HookNotFoundError.is(error)) { // [!code highlight]
+      // Hook doesn't exist yet — start a new workflow run
+      await startWorkflow("processEvent", data); // [!code highlight]
+    } else {
+      throw error;
+    }
+  }
+}
+```

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

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

package/docs/api-reference/workflow-errors/run-expired-error.mdx

@@ -0,0 +1,58 @@
+---
+title: RunExpiredError
+description: Thrown when a workflow run has expired and can no longer be operated on.
+type: reference
+summary: Catch RunExpiredError when a workflow run has expired and can no longer accept operations.
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/entity-conflict-error
+---
+
+`RunExpiredError` is thrown by world implementations when a workflow run has expired and can no longer be operated on. It corresponds to HTTP 410 Gone semantics.
+
+<Callout>
+The Workflow runtime handles this error automatically. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { RunExpiredError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (RunExpiredError.is(error)) { // [!code highlight]
+    console.log("Run has expired and can no longer accept events");
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface RunExpiredError {
+  /** The error message. */
+  message: string;
+}
+export default RunExpiredError;`}
+/>
+
+### Static Methods
+
+#### `RunExpiredError.is(value)`
+
+Type-safe check for `RunExpiredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { RunExpiredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (RunExpiredError.is(error)) {
+  // error is typed as RunExpiredError
+}
+```