workflow 4.2.0-beta.70 → 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/builtins.d.ts

@@ -3,7 +3,7 @@
  * similar to "stdlib" except that are not meant to be imported by users, but are instead "just available"
  * alongside user defined steps. They are used internally by the runtime
  */
-export declare function __builtin_response_array_buffer(res: Response): Promise<ArrayBuffer>;
-export declare function __builtin_response_json(res: Response): Promise<unknown>;
-export declare function __builtin_response_text(res: Response): Promise<string>;
+export declare function __builtin_response_array_buffer(this: Request | Response): Promise<ArrayBuffer>;
+export declare function __builtin_response_json(this: Request | Response): Promise<unknown>;
+export declare function __builtin_response_text(this: Request | Response): Promise<string>;
 //# sourceMappingURL=builtins.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/internal/builtins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAsB,+BAA+B,CAAC,GAAG,EAAE,QAAQ,wBAGlE;AAED,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,oBAG1D;AAED,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,mBAG1D"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/internal/builtins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,OAAO,GAAG,QAAQ,wBAIzB;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,oBAGrE;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,mBAGrE"}

package/dist/internal/builtins.js

@@ -3,16 +3,16 @@
  * similar to "stdlib" except that are not meant to be imported by users, but are instead "just available"
  * alongside user defined steps. They are used internally by the runtime
  */
-export async function __builtin_response_array_buffer(res) {
+export async function __builtin_response_array_buffer() {
     'use step';
-    return res.arrayBuffer();
+    return this.arrayBuffer();
 }
-export async function __builtin_response_json(res) {
+export async function __builtin_response_json() {
     'use step';
-    return res.json();
+    return this.json();
 }
-export async function __builtin_response_text(res) {
+export async function __builtin_response_text() {
     'use step';
-    return res.text();
+    return this.text();
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbHRpbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW50ZXJuYWwvYnVpbHRpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7R0FJRztBQUVILE1BQU0sQ0FBQyxLQUFLLFVBQVUsK0JBQStCLENBQUMsR0FBYTtJQUNqRSxVQUFVLENBQUM7SUFDWCxPQUFPLEdBQUcsQ0FBQyxXQUFXLEVBQUUsQ0FBQztBQUMzQixDQUFDO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSx1QkFBdUIsQ0FBQyxHQUFhO0lBQ3pELFVBQVUsQ0FBQztJQUNYLE9BQU8sR0FBRyxDQUFDLElBQUksRUFBRSxDQUFDO0FBQ3BCLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLHVCQUF1QixDQUFDLEdBQWE7SUFDekQsVUFBVSxDQUFDO0lBQ1gsT0FBTyxHQUFHLENBQUMsSUFBSSxFQUFFLENBQUM7QUFDcEIsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbHRpbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW50ZXJuYWwvYnVpbHRpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7R0FJRztBQUVILE1BQU0sQ0FBQyxLQUFLLFVBQVUsK0JBQStCO0lBR25ELFVBQVUsQ0FBQztJQUNYLE9BQU8sSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDO0FBQzVCLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLHVCQUF1QjtJQUMzQyxVQUFVLENBQUM7SUFDWCxPQUFPLElBQUksQ0FBQyxJQUFJLEVBQUUsQ0FBQztBQUNyQixDQUFDO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSx1QkFBdUI7SUFDM0MsVUFBVSxDQUFDO0lBQ1gsT0FBTyxJQUFJLENBQUMsSUFBSSxFQUFFLENBQUM7QUFDckIsQ0FBQyJ9

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/chat-session-modeling.mdx

@@ -39,12 +39,12 @@ export async function chat(messages: UIMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
   await agent.stream({
-    messages: convertToModelMessages(messages), // [!code highlight] Full history from client
+    messages: await convertToModelMessages(messages), // [!code highlight] Full history from client
     writable,
   });
 }
@@ -171,7 +171,7 @@ export async function chat(initialMessages: UIMessage[]) {
 
   const { workflowRunId: runId } = getWorkflowMetadata();
   const writable = getWritable<UIMessageChunk>();
-  const messages: ModelMessage[] = convertToModelMessages(initialMessages);
+  const messages: ModelMessage[] = await convertToModelMessages(initialMessages);
 
   // Write markers for initial user messages (for replay) // [!code highlight]
   for (const msg of initialMessages) { // [!code highlight]
@@ -183,7 +183,7 @@ export async function chat(initialMessages: UIMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 

package/docs/ai/defining-tools.mdx

@@ -23,9 +23,12 @@ 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: LanguageModelV2Prompt, toolCallId: string }) { // [!code highlight]
+  { messages, toolCallId }: { messages: ModelMessage[], toolCallId: string }) { // [!code highlight]
   "use step";
   return `Weather in ${city} is sunny`;
 }
@@ -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,15 +123,18 @@ 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]
     model: gateway("bedrock/claude-4-5-haiku-20251001-v1"),
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
-  const modelMessages = convertToModelMessages(messages);
-  const stream = agent.stream({ messages: modelMessages }); // [!code highlight]
+  const modelMessages = await convertToModelMessages(messages);
+  const stream = await agent.stream({ messages: modelMessages }); // [!code highlight]
   return createUIMessageStreamResponse({
     stream: stream.toUIMessageStream(),
   });
@@ -273,7 +276,7 @@ export async function chatWorkflow(messages: ModelMessage[]) {
     // ELSE if using a custom provider, pass the provider call as an argument:
     model: openai("gpt-5.1"), // [!code highlight]
 
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
@@ -304,7 +307,7 @@ import { chatWorkflow } from "@/workflows/chat/workflow";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = convertToModelMessages(messages);
+  const modelMessages = await convertToModelMessages(messages);
 
   const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
 

package/docs/ai/message-queueing.mdx

@@ -32,16 +32,18 @@ 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<LanguageModelV2>);  // Current model
+  model: string | (() => Promise<LanguageModel>);    // Current model
   stepNumber: number;                                // 0-indexed step count
   steps: StepResult[];                               // Previous step results
-  messages: LanguageModelV2Prompt;                   // Messages to be sent
+  messages: ModelMessage[];                          // Messages to be sent
 }
 
 interface PrepareStepResult {
-  model?: string | (() => Promise<LanguageModelV2>); // Override model
-  messages?: LanguageModelV2Prompt;                  // Override messages
+  model?: string | (() => Promise<LanguageModel>);   // Override model
+  messages?: ModelMessage[];                         // Override messages
 }
 ```
 
@@ -65,7 +67,7 @@ export async function chat(initialMessages: ModelMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
@@ -101,7 +103,7 @@ export async function chat(initialMessages: ModelMessage[]) {
 Messages sent via `chatMessageHook.resume()` accumulate in the queue and get injected before the next step, whether that's a tool call or another LLM request.
 
 <Callout type="info">
-The `prepareStep` callback receives messages in `LanguageModelV2Prompt` format (with content arrays), which is the internal format used by the AI SDK.
+The `prepareStep` callback receives messages in `ModelMessage[]` format (with content arrays), which is the internal format used by the AI SDK.
 </Callout>
 
 ## Combining with Multi-Turn Sessions

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/index.mdx

@@ -17,6 +17,9 @@ All the functions and primitives that come with Workflow DevKit by package.
     <Card title="workflow/next" href="/docs/api-reference/workflow-next">
         Next.js integration for Workflow DevKit that automatically configures bundling and runtime support.
     </Card>
+    <Card title="@workflow/serde" href="/docs/api-reference/workflow-serde">
+        Serialization symbols for custom class serialization in workflows.
+    </Card>
     <Card title="@workflow/ai" href="/docs/api-reference/workflow-ai">
         Helpers for integrating AI SDK for building AI-powered workflows.
     </Card>

package/docs/api-reference/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "API Reference",
-  "pages": ["...", "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

@@ -34,7 +34,7 @@ async function myAgent() {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful weather assistant.",
+    instructions: "You are a helpful weather assistant.",
     temperature: 0.7,
     tools: {
       getWeather: {
@@ -249,7 +249,7 @@ async function weatherAgentWorkflow(userQuery: string) {
         execute: getWeather,
       },
     },
-    system: "You are a helpful weather assistant. Always provide accurate weather information.",
+    instructions: "You are a helpful weather assistant. Always provide accurate weather information.",
   });
 
   await agent.stream({
@@ -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 }) {
@@ -446,7 +448,7 @@ async function agentWithPrepareStep(userMessage: string) {
 
   const agent = new DurableAgent({
     model: "openai/gpt-4.1-mini", // Default model
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   await agent.stream({
@@ -500,7 +502,7 @@ async function agentWithMessageQueue(initialMessage: string) {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   await agent.stream({
@@ -812,7 +814,7 @@ async function agentWithUIMessages(userMessage: string) {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   const result = await agent.stream({

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-api/start.mdx

@@ -76,3 +76,27 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
   deploymentId: "custom-deployment-id" // [!code highlight]
 }); // [!code highlight]
 ```
+
+### Using `deploymentId: "latest"`
+
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+
+```typescript
+import { start } from "workflow/api";
+import { myWorkflow } from "./workflows/my-workflow";
+
+const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
+  deploymentId: "latest" // [!code highlight]
+}); // [!code highlight]
+```
+
+<Callout type="info">
+The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value 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.
+</Callout>
+
+<Callout type="warn">
+When using `deploymentId: "latest"`, the workflow run will execute on a potentially different deployment than the one calling `start()`. Be mindful of forward and backward compatibility:
+
+- **Workflow identity**: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
+- **Input and output compatibility**: The arguments passed to `start()` are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
+</Callout>