workflow 5.0.0-beta.0 → 5.0.0-beta.2

package/docs/cookbook/integrations/ai-sdk.mdx

@@ -0,0 +1,204 @@
+---
+title: AI SDK
+description: Use AI SDK model providers, tool calling, and streaming inside durable workflows.
+type: guide
+summary: Turn any AI SDK model call into a retryable, observable workflow step with built-in streaming.
+related:
+  - /docs/ai
+  - /docs/ai/defining-tools
+  - /docs/ai/resumable-streams
+  - /docs/api-reference/workflow-ai/durable-agent
+---
+
+Workflow SDK integrates with [AI SDK](https://ai-sdk.dev) through the `@workflow/ai` package. This turns your LLM calls and tool executions into durable, retryable steps with built-in streaming and observability.
+
+## What It Enables
+
+- **Durable LLM calls** -- Model invocations become steps that survive crashes and cold starts
+- **Any model provider** -- Use OpenAI, Anthropic, Google, Bedrock, or any AI SDK-compatible provider through [Vercel Gateway](https://vercel.com/docs/gateway) or direct provider configuration
+- **Tool durability** -- Tool executions become steps with automatic retries and event logging
+- **Resumable streaming** -- Clients reconnect mid-stream without losing data
+
+## When to Use
+
+Use this integration when your application calls an LLM and needs:
+
+- Reliability for long-running agent loops (multi-step tool calling)
+- Automatic retry on transient model API failures
+- Stream resumption after disconnects
+- Observability into each model call and tool execution
+
+## DurableAgent with Model Providers
+
+The `DurableAgent` wraps AI SDK's streaming interface. Pass any model string supported by [Vercel Gateway](https://vercel.com/docs/gateway) or a provider-specific model ID.
+
+```typescript title="workflows/research.ts" lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { convertToModelMessages, type UIMessage, type UIMessageChunk } from "ai";
+import { getWritable } from "workflow";
+import z from "zod/v4";
+
+async function searchWeb(input: { query: string }): Promise<{ results: string[] }> {
+  "use step";
+  const response = await fetch(
+    `https://api.example.com/search?q=${encodeURIComponent(input.query)}`
+  );
+  const data = await response.json();
+  return { results: data.items.map((item: { title: string }) => item.title) };
+}
+
+async function summarize(input: { text: string }): Promise<{ summary: string }> {
+  "use step";
+  // Each step is individually retried on failure
+  const response = await fetch("https://api.example.com/summarize", {
+    method: "POST",
+    body: JSON.stringify({ text: input.text }),
+  });
+  const data = await response.json();
+  return { summary: data.summary };
+}
+
+export async function researchAgent(messages: UIMessage[]) {
+  "use workflow";
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: "anthropic/claude-sonnet-4-20250514",
+    instructions: "You are a research assistant. Search the web and summarize findings.",
+    tools: {
+      searchWeb: {
+        description: "Search the web for information",
+        inputSchema: z.object({
+          query: z.string().describe("The search query"),
+        }),
+        execute: searchWeb,
+      },
+      summarize: {
+        description: "Summarize a block of text",
+        inputSchema: z.object({
+          text: z.string().describe("The text to summarize"),
+        }),
+        execute: summarize,
+      },
+    },
+  });
+
+  const result = await agent.stream({ // [!code highlight]
+    messages: await convertToModelMessages(messages),
+    writable: getWritable<UIMessageChunk>(),
+  });
+
+  return { messages: result.messages };
+}
+```
+
+### Using Different Providers
+
+#### Vercel Gateway (string model IDs)
+
+All string model IDs route through [Vercel Gateway](https://vercel.com/docs/gateway). Switch providers by changing the model string -- no other code changes required.
+
+{/* @skip-typecheck - illustrative snippets with intentional redeclarations */}
+```typescript
+// All string model IDs route through Vercel Gateway
+const agent = new DurableAgent({ model: "anthropic/claude-sonnet-4-20250514" });
+const agent = new DurableAgent({ model: "openai/gpt-4o" });
+const agent = new DurableAgent({ model: "google/gemini-2.5-pro" });
+const agent = new DurableAgent({ model: "bedrock/claude-haiku-4-5-20251001-v1" });
+```
+
+#### Direct Provider Access
+
+Import from a provider package to bypass Gateway and connect to the provider directly.
+
+```typescript
+import { DurableAgent } from "@workflow/ai/agent";
+import { openai } from "@workflow/ai/openai";
+
+const agent = new DurableAgent({ model: openai("gpt-4o") });
+```
+
+### Provider-Specific Options
+
+Pass provider options for features like reasoning or extended thinking.
+
+```typescript
+const agent = new DurableAgent({
+  model: "anthropic/claude-sonnet-4-20250514",
+  providerOptions: {
+    anthropic: { thinking: { type: "enabled", budgetTokens: 10000 } },
+  },
+  // ...tools and instructions
+});
+```
+
+## Tool Functions with Steps
+
+Tool `execute` functions can optionally include steps by using the `"use step"` directive. When a tool is **not** a step, it runs inside the workflow context and can modify workflow state directly. When a tool **is** marked with `"use step"`, it becomes a durable step with:
+
+- **Automatic retries** -- If a tool fails (network error, API timeout), the framework retries it
+- **Event logging** -- Inputs and outputs are recorded for observability and replay
+- **Idempotency** -- On replay after a crash, completed steps return their cached result
+
+```typescript
+async function bookFlight(input: {
+  origin: string;
+  destination: string;
+  date: string;
+}): Promise<{ confirmationId: string }> {
+  "use step";
+  // This call is retried on transient failures and its result is persisted
+  const response = await fetch("https://api.airline.com/book", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(input),
+  });
+  if (!response.ok) throw new Error(`Booking failed: ${response.status}`);
+  return response.json();
+}
+```
+
+## Resumable Streaming
+
+Use `WorkflowChatTransport` on the client to automatically reconnect to a workflow's stream if the connection drops.
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse } from "ai";
+import { start } from "workflow/api";
+import { researchAgent } from "@/workflows/research";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+  const run = await start(researchAgent, [messages]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable, // [!code highlight]
+    headers: { "x-workflow-run-id": run.runId },
+  });
+}
+```
+
+```typescript title="components/chat.tsx" lineNumbers
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { WorkflowChatTransport } from "@workflow/ai";
+
+export function Chat() {
+  const chat = useChat({
+    transport: new WorkflowChatTransport({ // [!code highlight]
+      api: "/api/chat",
+    }),
+  });
+
+  // Standard useChat usage -- reconnection is handled automatically
+  return (
+    <div>
+      {chat.messages.map((m) => (
+        <div key={m.id}>{m.content}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+See [Resumable Streams](/docs/ai/resumable-streams) for advanced options like `startIndex` and `prepareReconnectToStreamRequest`.

package/docs/cookbook/integrations/chat-sdk.mdx

@@ -0,0 +1,203 @@
+---
+title: Chat SDK
+description: Build durable chat sessions by combining workflow persistence with AI SDK's chat primitives.
+type: guide
+summary: Use workflow hooks and streaming to create chat sessions that survive disconnects and server restarts.
+related:
+  - /docs/ai/chat-session-modeling
+  - /docs/ai/resumable-streams
+  - /docs/ai/message-queueing
+  - /docs/api-reference/workflow-ai/durable-agent
+  - /docs/api-reference/workflow/define-hook
+---
+
+AI SDK provides chat primitives (`useChat`, message types, streaming utilities) for building chat interfaces. Workflow SDK makes those chat sessions durable -- surviving disconnects, cold starts, and server restarts -- by persisting every message and LLM response as workflow events.
+
+## What It Enables
+
+- **Durable chat history** -- Messages and responses are persisted in the workflow event log, not just client state
+- **Resumable sessions** -- Users reconnect and pick up where they left off, even after server restarts
+- **Multi-turn conversations** -- A single workflow manages an entire chat session with hook-based message injection
+- **Server-side message queueing** -- Inject follow-up messages while the agent is still processing
+
+## When to Use
+
+Use this pattern when your chat application needs:
+
+- Persistence beyond the browser session
+- Recovery from server failures mid-conversation
+- Long-running agent sessions (minutes to hours)
+- Server-driven message injection (system messages, external events)
+
+## Single-Turn: Stateless Sessions
+
+Each user message starts a new workflow run. The client owns the message history and sends the full array with each request. This is the simplest pattern.
+
+```typescript title="workflows/chat.ts" lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { convertToModelMessages, type UIMessage, type UIMessageChunk } from "ai";
+import { getWritable } from "workflow";
+
+export async function chat(messages: UIMessage[]) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-sonnet-4-20250514",
+    instructions: "You are a helpful assistant.",
+    tools: { /* your tools here */ },
+  });
+
+  const result = await agent.stream({ // [!code highlight]
+    messages: await convertToModelMessages(messages),
+    writable: getWritable<UIMessageChunk>(),
+  });
+
+  return { messages: result.messages };
+}
+```
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse } from "ai";
+import { start } from "workflow/api";
+import { chat } from "@/workflows/chat";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+  const run = await start(chat, [messages]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: { "x-workflow-run-id": run.runId },
+  });
+}
+```
+
+The client uses `WorkflowChatTransport` for automatic stream resumption.
+
+```typescript title="components/chat.tsx" lineNumbers
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { WorkflowChatTransport } from "@workflow/ai";
+
+export function Chat() {
+  const chat = useChat({
+    transport: new WorkflowChatTransport({ api: "/api/chat" }), // [!code highlight]
+  });
+
+  return (
+    <div>
+      {chat.messages.map((m) => (
+        <div key={m.id}>{m.content}</div>
+      ))}
+      <form onSubmit={chat.handleSubmit}>
+        <input value={chat.input} onChange={chat.handleInputChange} />
+      </form>
+    </div>
+  );
+}
+```
+
+## Multi-Turn: Durable Sessions
+
+A single workflow manages the entire conversation. The workflow loops, waiting for new messages via a hook. This gives you server-side ownership of the full chat history.
+
+```typescript title="workflows/durable-chat.ts" lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import {
+  convertToModelMessages,
+  type UIMessage,
+  type UIMessageChunk,
+} from "ai";
+import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
+import { z } from "zod";
+
+const chatMessageHook = defineHook({ // [!code highlight]
+  schema: z.object({
+    messages: z.array(z.any()),
+  }),
+});
+
+export async function durableChat(initialMessages: UIMessage[]) {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+  let allMessages = await convertToModelMessages(initialMessages);
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-sonnet-4-20250514",
+    instructions: "You are a helpful assistant.",
+    tools: { /* your tools here */ },
+  });
+
+  // First turn
+  const firstResult = await agent.stream({
+    messages: allMessages,
+    writable: getWritable<UIMessageChunk>(),
+    preventClose: true,
+  });
+  allMessages = firstResult.messages;
+
+  // Subsequent turns -- wait for new messages via hook
+  while (true) {
+    const hook = chatMessageHook.create({ token: workflowRunId });
+    const { messages: newMessages } = await hook; // [!code highlight]
+
+    allMessages = [
+      ...allMessages,
+      ...await convertToModelMessages(newMessages),
+    ];
+
+    const result = await agent.stream({
+      messages: allMessages,
+      writable: getWritable<UIMessageChunk>(),
+      preventClose: true,
+    });
+    allMessages = result.messages;
+  }
+}
+```
+
+### Multi-Turn API Routes
+
+You need two routes: one to start the session, another to send follow-up messages.
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse } from "ai";
+import { start } from "workflow/api";
+import { durableChat } from "@/workflows/durable-chat";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+  const run = await start(durableChat, [messages]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: { "x-workflow-run-id": run.runId },
+  });
+}
+```
+
+```typescript title="app/api/chat/follow-up/route.ts" lineNumbers
+import { resumeHook } from "workflow/api";
+
+export async function POST(request: Request) {
+  const { runId, messages } = await request.json();
+  await resumeHook(runId, { messages }); // [!code highlight]
+  return new Response("OK");
+}
+```
+
+## Choosing a Pattern
+
+| | Single-Turn | Multi-Turn |
+|---|---|---|
+| **State ownership** | Client | Server (workflow event log) |
+| **Message injection** | Not needed | Via hooks |
+| **Complexity** | Low | Medium |
+| **Session duration** | Per-request | Minutes to hours |
+| **Crash recovery** | Client resends full history | Workflow replays from event log |
+
+Start with single-turn. Move to multi-turn when you need server-owned state, message injection from external sources, or sessions that outlive the browser tab.
+
+See [Chat Session Modeling](/docs/ai/chat-session-modeling) for the full guide including multiplayer patterns and message queueing.

package/docs/cookbook/integrations/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Integrations",
+  "pages": ["ai-sdk", "sandbox", "chat-sdk"]
+}

package/docs/cookbook/integrations/sandbox.mdx

@@ -0,0 +1,128 @@
+---
+title: Sandbox
+description: Orchestrate Vercel Sandbox lifecycle -- creation, code execution, snapshotting -- inside durable workflows.
+type: guide
+summary: Use workflow steps to provision sandboxes, run code, and manage sandbox lifecycle with automatic cleanup on failure.
+related:
+  - /docs/ai/defining-tools
+  - /docs/foundations/errors-and-retries
+  - /docs/api-reference/workflow-ai/durable-agent
+---
+
+[Vercel Sandbox](https://vercel.com/docs/sandbox) provides isolated code execution environments. The `@vercel/sandbox` package implements first-class support for the Workflow SDK -- the `Sandbox` class is serializable, and its methods (`create`, `runCommand`, `destroy`, etc.) implicitly run as steps. This means you can interact with sandboxes directly inside workflow functions without wrapping each operation in a separate `"use step"` function.
+
+## What It Enables
+
+- **Durable sandbox sessions** -- Sandbox provisioning and teardown survive cold starts
+- **Automatic cleanup** -- Saga-style compensation ensures sandboxes are destroyed on failure
+- **Multi-step code execution** -- Run a sequence of commands in the same sandbox with each step logged
+- **Agent-driven sandboxes** -- Give your DurableAgent a tool that spins up sandboxes on demand
+
+## When to Use
+
+Use this integration when your workflow needs to:
+
+- Execute user-provided or AI-generated code safely
+- Run multi-step build/test pipelines in isolated environments
+- Provision temporary environments for interactive sessions
+- Snapshot sandbox state between steps for reproducibility
+
+## Sandbox Lifecycle in a Workflow
+
+Because `@vercel/sandbox` methods are implicit steps, each call is automatically persisted to the event log. If a failure occurs partway through, the workflow replays from where it left off.
+
+```typescript title="workflows/sandbox-pipeline.ts" lineNumbers
+import { Sandbox } from "@vercel/sandbox";
+
+export async function sandboxPipeline(input: {
+  template: string;
+  commands: string[];
+}) {
+  "use workflow";
+
+  const sandbox = await Sandbox.create({ template: input.template }); // [!code highlight]
+
+  try {
+    const results = [];
+    for (const command of input.commands) {
+      const result = await sandbox.runCommand(command); // [!code highlight]
+      results.push(result);
+    }
+    return { status: "completed", results };
+  } catch (error) {
+    await sandbox.destroy(); // [!code highlight]
+    throw error;
+  }
+}
+```
+
+## Sandbox as an Agent Tool
+
+Give a DurableAgent the ability to create and use sandboxes. The agent decides when to spin up a sandbox, what code to run, and when to tear it down. Since sandbox methods are implicit steps, the tool execute functions can call them directly.
+
+```typescript title="workflows/code-agent.ts" lineNumbers
+import { Sandbox } from "@vercel/sandbox";
+import { DurableAgent } from "@workflow/ai/agent";
+import { convertToModelMessages, type UIMessage, type UIMessageChunk } from "ai";
+import { getWritable } from "workflow";
+import z from "zod/v4";
+
+export async function codeAgent(messages: UIMessage[]) {
+  "use workflow";
+
+  let activeSandbox: Sandbox | null = null;
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-sonnet-4-20250514",
+    instructions:
+      "You are a coding assistant. You can create sandboxes to run code. " +
+      "Always create a sandbox first, then execute code in it. " +
+      "Clean up the sandbox when you are done.",
+    tools: {
+      createSandbox: {
+        description: "Create an isolated sandbox environment for running code",
+        inputSchema: z.object({
+          template: z.string().describe("The sandbox template (e.g., 'node', 'python')"),
+        }),
+        execute: async ({ template }) => {
+          activeSandbox = await Sandbox.create({ template }); // [!code highlight]
+          return { sandboxId: activeSandbox.id };
+        },
+      },
+      executeCode: {
+        description: "Execute a command in the active sandbox",
+        inputSchema: z.object({
+          command: z.string().describe("The command to execute"),
+        }),
+        execute: async ({ command }) => {
+          if (!activeSandbox) throw new Error("No active sandbox");
+          return activeSandbox.runCommand(command); // [!code highlight]
+        },
+      },
+      cleanupSandbox: {
+        description: "Destroy the active sandbox when finished",
+        inputSchema: z.object({}),
+        execute: async () => {
+          if (!activeSandbox) throw new Error("No active sandbox");
+          await activeSandbox.destroy(); // [!code highlight]
+          activeSandbox = null;
+          return { cleaned: true };
+        },
+      },
+    },
+  });
+
+  const result = await agent.stream({
+    messages: await convertToModelMessages(messages),
+    writable: getWritable<UIMessageChunk>(),
+  });
+
+  return { messages: result.messages };
+}
+```
+
+## Saga Pattern for Cleanup
+
+Combine sandbox orchestration with the [saga pattern](/docs/cookbook/common-patterns/saga) to ensure sandboxes are always cleaned up, even when a step in the middle of your pipeline fails.
+
+The example above uses a try/catch around the command execution loop. For more complex pipelines with multiple resources (sandbox + database + external API), push compensation functions onto a stack as shown in the [saga recipe](/docs/cookbook/common-patterns/saga).

package/docs/cookbook/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Cookbook",
+  "defaultOpen": true,
+  "pages": ["common-patterns", "agent-patterns", "integrations", "advanced"]
+}

package/docs/deploying/building-a-world.mdx

@@ -166,54 +166,56 @@ The Streamer interface enables real-time data streaming:
 {/* @skip-typecheck - interface definition, not runnable code */}
 ```typescript
 interface Streamer {
-  writeToStream(
-    name: string,
-    runId: string,
-    chunk: string | Uint8Array
-  ): Promise<void>;
-
-  writeToStreamMulti?(
-    name: string,
-    runId: string,
-    chunks: (string | Uint8Array)[]
-  ): Promise<void>;
-
-  closeStream(
-    name: string,
-    runId: string
-  ): Promise<void>;
-
-  readFromStream(
-    name: string,
-    startIndex?: number
-  ): Promise<ReadableStream<Uint8Array>>;
-
-  listStreamsByRunId(runId: string): Promise<string[]>;
-
-  /** Paginated snapshot of stream chunks. */
-  getStreamChunks(
-    name: string,
-    runId: string,
-    options?: { limit?: number; cursor?: string }
-  ): Promise<{
-    data: { index: number; data: Uint8Array }[];
-    cursor: string | null;
-    hasMore: boolean;
-    done: boolean;
-  }>;
-
-  /** Lightweight metadata: tail index and completion flag. */
-  getStreamInfo(
-    name: string,
-    runId: string
-  ): Promise<{ tailIndex: number; done: boolean }>;
+  streamFlushIntervalMs?: number;
+
+  streams: {
+    write(
+      runId: string,
+      name: string,
+      chunk: string | Uint8Array
+    ): Promise<void>;
+
+    writeMulti?(
+      runId: string,
+      name: string,
+      chunks: (string | Uint8Array)[]
+    ): Promise<void>;
+
+    close(runId: string, name: string): Promise<void>;
+
+    get(
+      runId: string,
+      name: string,
+      startIndex?: number
+    ): Promise<ReadableStream<Uint8Array>>;
+
+    list(runId: string): Promise<string[]>;
+
+    /** Paginated snapshot of stream chunks. */
+    getChunks(
+      runId: string,
+      name: string,
+      options?: { limit?: number; cursor?: string }
+    ): Promise<{
+      data: { index: number; data: Uint8Array }[];
+      cursor: string | null;
+      hasMore: boolean;
+      done: boolean;
+    }>;
+
+    /** Lightweight metadata: tail index and completion flag. */
+    getInfo(
+      runId: string,
+      name: string
+    ): Promise<{ tailIndex: number; done: boolean }>;
+  };
 }
 ```
 
 Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
-`writeToStreamMulti()` is an optional optimization for batching multiple writes.
+`writeMulti()` is an optional optimization for batching multiple writes.
 
-`getStreamChunks` returns a paginated snapshot of currently available chunks (unlike `readFromStream` which returns a live `ReadableStream` that waits for new chunks). `getStreamInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
+`getChunks` returns a paginated snapshot of currently available chunks (unlike `get` which returns a live `ReadableStream` that waits for new chunks). `getInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
 
 ## Reference Implementations
 

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

@@ -32,7 +32,7 @@ npx workflow web
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />