workflow 5.0.0-beta.1 → 5.0.0-beta.2

package/docs/cookbook/common-patterns/webhooks.mdx

@@ -0,0 +1,185 @@
+---
+title: Webhooks & External Callbacks
+description: Receive HTTP callbacks from external services, process them durably, and respond inline.
+type: guide
+summary: Create webhook endpoints that your workflow can await, process incoming requests in steps, and respond to the caller — all within durable workflow context.
+---
+
+Use webhooks when external services push events to your application via HTTP callbacks. The workflow creates a webhook URL, suspends with zero compute cost, and resumes when a request arrives.
+
+## When to use this
+
+- Accepting callbacks from payment processors (Stripe, PayPal)
+- Waiting for third-party verification or processing results
+- Any integration where an external system calls you back asynchronously
+
+## Pattern: Processing webhook events
+
+Create a webhook with manual response control, then iterate over incoming requests:
+
+```typescript
+import { createWebhook, type RequestWithResponse } from "workflow";
+
+declare function processEvent(request: RequestWithResponse): Promise<{ type: string }>; // @setup
+
+export async function paymentWebhook(orderId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({ respondWith: "manual" }); // [!code highlight]
+  // webhook.url is the URL to give to the external service
+
+  const ledger: { type: string }[] = [];
+
+  for await (const request of webhook) { // [!code highlight]
+    const entry = await processEvent(request);
+    ledger.push(entry);
+
+    // Break when we've received a terminal event
+    if (entry.type === "payment.succeeded" || entry.type === "refund.created") {
+      break;
+    }
+  }
+
+  return { orderId, webhookUrl: webhook.url, ledger, status: "settled" };
+}
+```
+
+### Step function for processing
+
+Each webhook request is processed in its own step, giving you full Node.js access for validation, database writes, and responding to the caller:
+
+```typescript
+import { type RequestWithResponse } from "workflow";
+
+async function processEvent(
+  request: RequestWithResponse
+): Promise<{ type: string }> {
+  "use step";
+
+  const body = await request.json().catch(() => ({}));
+  const type = body?.type ?? "unknown";
+
+  // Validate, process, and respond inline
+  if (type === "payment.succeeded") {
+    // Record the payment in your database
+    await request.respondWith(Response.json({ ack: true, action: "captured" })); // [!code highlight]
+  } else if (type === "payment.failed") {
+    await request.respondWith(Response.json({ ack: true, action: "flagged" }));
+  } else {
+    await request.respondWith(Response.json({ ack: true, action: "ignored" }));
+  }
+
+  return { type };
+}
+```
+
+## Pattern: Async request-reply with timeout
+
+Submit a request to an external service, pass it your webhook URL, then race the callback against a deadline:
+
+```typescript
+import { createWebhook, sleep, FatalError, type RequestWithResponse } from "workflow";
+
+export async function asyncVerification(documentId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({ respondWith: "manual" });
+
+  // Submit to vendor, passing our webhook URL for the callback
+  await submitToVendor(documentId, webhook.url);
+
+  // Race: wait for callback OR timeout after 30 seconds
+  const result = await Promise.race([ // [!code highlight]
+    (async () => {
+      for await (const request of webhook) {
+        const body = await processCallback(request);
+        return body;
+      }
+      throw new FatalError("Webhook closed without callback");
+    })(),
+    sleep("30s").then(() => ({ status: "timed_out" as const })), // [!code highlight]
+  ]);
+
+  return { documentId, ...result };
+}
+
+async function submitToVendor(documentId: string, callbackUrl: string): Promise<void> {
+  "use step";
+  await fetch("https://vendor.example.com/verify", {
+    method: "POST",
+    body: JSON.stringify({ documentId, callbackUrl }),
+  });
+}
+
+async function processCallback(
+  request: RequestWithResponse
+): Promise<{ status: string; details: string }> {
+  "use step";
+  const body = await request.json();
+  await request.respondWith(Response.json({ ack: true }));
+  return {
+    status: body.approved ? "verified" : "rejected",
+    details: body.details ?? body.reason ?? "",
+  };
+}
+```
+
+## Pattern: Large payload by reference
+
+When payloads are too large to serialize into the event log, pass a lightweight reference (a "claim check") instead. Use a hook to signal when the data is ready:
+
+```typescript
+import { defineHook } from "workflow";
+
+export const blobReady = defineHook<{ blobToken: string }>(); // [!code highlight]
+
+export async function importLargeFile(importId: string) {
+  "use workflow";
+
+  // Suspend until the external system signals the blob is uploaded
+  const { blobToken } = await blobReady.create({ token: `upload:${importId}` }); // [!code highlight]
+
+  // Process by reference -- the full payload never enters the event log
+  await processBlob(blobToken);
+
+  return { importId, blobToken, status: "indexed" };
+}
+
+async function processBlob(blobToken: string): Promise<void> {
+  "use step";
+  // Fetch the blob using the token, process it
+  const res = await fetch(`https://storage.example.com/blobs/${blobToken}`);
+  const data = await res.arrayBuffer();
+  // Index, transform, or store the data
+}
+```
+
+Resume from an API route when the upload completes:
+
+```typescript
+import { resumeHook } from "workflow/api";
+
+// POST /api/upload-complete
+export async function POST(request: Request) {
+  const { importId, blobToken } = await request.json();
+  await resumeHook(`upload:${importId}`, { blobToken }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+## Tips
+
+- **`respondWith: "manual"`** gives you control over the HTTP response from inside a step. Use this when you need to validate the request before responding.
+- **`for await` on a webhook** lets you process multiple events from the same URL. Use `break` to stop listening after a terminal event.
+- **Webhooks auto-generate URLs** at `/.well-known/workflow/v1/webhook/:token`. Pass this URL to external services.
+- **Race webhooks against `sleep()`** for deadlines. If the callback doesn't arrive in time, the workflow can take a fallback action.
+- **For large payloads**, use a hook + reference token instead of passing the data through the workflow. The event log serializes all step inputs/outputs, so large payloads hurt performance.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions with full Node.js access
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) -- creates an HTTP endpoint the workflow can await
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) -- creates a typed hook for signal-based patterns
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable timer for deadlines
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- prevents retry on permanent failures

package/docs/cookbook/index.mdx

@@ -0,0 +1,41 @@
+---
+title: Cookbook
+description: Best-practice workflow patterns with copy-paste code examples.
+type: overview
+---
+
+A curated collection of workflow patterns with clean, copy-paste code examples for real use cases.
+
+## Common Patterns
+
+- [**Saga**](/cookbook/common-patterns/saga) — Coordinate multi-step transactions with automatic rollback when a step fails
+- [**Batching**](/cookbook/common-patterns/batching) — Process large collections in parallel batches with failure isolation
+- [**Rate Limiting**](/cookbook/common-patterns/rate-limiting) — Handle 429 responses and transient failures with RetryableError and backoff
+- [**Fan-Out**](/cookbook/common-patterns/fan-out) — Send to multiple channels in parallel with independent failure handling
+- [**Scheduling**](/cookbook/common-patterns/scheduling) — Use durable sleep to schedule actions minutes, hours, or weeks ahead
+- [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects happen exactly once, even when steps retry
+- [**Webhooks**](/cookbook/common-patterns/webhooks) — Receive HTTP callbacks from external services and process them durably
+- [**Conditional Routing**](/cookbook/common-patterns/content-router) — Route payloads to different step handlers based on content
+- [**Child Workflows**](/cookbook/common-patterns/child-workflows) — Spawn and orchestrate child workflows from a parent
+
+## Agent Patterns
+
+- [**Durable Agent**](/cookbook/agent-patterns/durable-agent) — Replace a stateless AI agent with one that survives crashes and retries tool calls
+- [**Tool Streaming**](/cookbook/agent-patterns/tool-streaming) — Stream real-time progress updates from tools to the UI
+- [**Human-in-the-Loop**](/cookbook/agent-patterns/human-in-the-loop) — Pause an agent for human approval, then resume based on the decision
+- [**Tool Orchestration**](/cookbook/agent-patterns/tool-orchestration) — Choose between step-level and workflow-level tools, or combine both
+- [**Stop Workflow**](/cookbook/agent-patterns/stop-workflow) — Gracefully cancel a running agent workflow using a hook signal
+
+## Integrations
+
+- [**AI SDK**](/cookbook/integrations/ai-sdk) — Use AI SDK model providers, tool calling, and streaming inside durable workflows
+- [**Chat SDK**](/cookbook/integrations/chat-sdk) — Build durable chat sessions with workflow persistence and AI SDK chat primitives
+- [**Sandbox**](/cookbook/integrations/sandbox) — Orchestrate Vercel Sandbox lifecycle inside durable workflows
+
+## Advanced
+
+- [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable objects so they cross the workflow boundary
+- [**Durable Objects**](/cookbook/advanced/durable-objects) — Model long-lived stateful entities as workflows
+- [**Isomorphic Packages**](/cookbook/advanced/isomorphic-packages) — Publish packages that work inside and outside the workflow runtime
+- [**Custom Serialization**](/cookbook/advanced/custom-serialization) — Make custom classes survive workflow serialization
+- [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions

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"]
+}