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

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -0,0 +1,279 @@
+---
+title: Publishing Libraries
+description: Structure and publish npm packages that export workflow functions for consumers to use with Workflow SDK.
+type: guide
+summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
+---
+
+<Callout>
+This is an advanced guide for library authors who want to publish reusable workflow functions as npm packages. It assumes familiarity with `"use workflow"`, `"use step"`, and the workflow execution model.
+</Callout>
+
+## Package Structure
+
+A workflow library follows a standard TypeScript package layout with a dedicated `workflows/` directory. Each workflow file exports one or more workflow functions that consumers can import and pass to `start()`.
+
+```
+my-media-lib/
+├── src/
+│   ├── index.ts              # Package entry point
+│   ├── types.ts              # Shared types
+│   ├── workflows/
+│   │   ├── index.ts          # Re-exports all workflows
+│   │   ├── transcode.ts      # Workflow: transcode a video
+│   │   └── generate-thumbnails.ts
+│   └── lib/
+│       └── api-client.ts     # Internal helpers (NOT steps)
+├── test-server/
+│   └── workflows.ts          # Re-export for integration tests
+├── tsup.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### Entry Points and Exports
+
+Use the `exports` field in `package.json` to expose separate entry points for the main API and the raw workflow functions:
+
+```json
+{
+  "name": "@acme/media",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": { "import": "./dist/index.d.ts" },
+      "import": "./dist/index.js"
+    },
+    "./workflows": {
+      "types": { "import": "./dist/workflows/index.d.ts" },
+      "import": "./dist/workflows/index.js"
+    }
+  },
+  "files": ["dist"]
+}
+```
+
+The main entry point (`@acme/media`) exports types, utilities, and convenience wrappers. The `./workflows` entry point (`@acme/media/workflows`) exports the raw workflow functions that consumers need for the build system.
+
+### Source Files
+
+The package entry re-exports workflows alongside any utilities:
+
+```typescript lineNumbers
+// src/index.ts
+export * from "./types";
+export * as workflows from "./workflows";
+```
+
+The workflows barrel file re-exports each workflow:
+
+```typescript lineNumbers
+// src/workflows/index.ts
+export * from "./transcode";
+export * from "./generate-thumbnails";
+```
+
+### Build Configuration
+
+Use a bundler like `tsup` with separate entry points for each export. Mark `workflow` as external so it's resolved from the consumer's project:
+
+```typescript lineNumbers
+// tsup.config.ts
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: [
+    "src/index.ts",
+    "src/workflows/index.ts",
+  ],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: ["workflow"], // [!code highlight]
+});
+```
+
+## Re-Exporting for Workflow ID Stability
+
+Workflow SDK's compiler assigns each workflow function a stable ID based on its position in the source file that the build system processes. When a consumer imports a pre-built workflow from an npm package, the compiler never sees the original source — it only sees the compiled output. This means workflow IDs won't match between the library's development environment and the consumer's app.
+
+The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs.
+
+### Consumer Setup
+
+```typescript lineNumbers
+// workflows/media.ts (in the consumer's project)
+// Re-export library workflows so the build system assigns stable IDs
+export * from "@acme/media/workflows"; // [!code highlight]
+```
+
+This one-line file is all that's needed. The workflow compiler transforms this file, discovers the workflow and step functions from the library, and assigns IDs that are stable across deployments.
+
+### Why This Is Necessary
+
+Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a workflow run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If the IDs don't exist (because the compiler never processed the library's source), replay fails.
+
+The re-export pattern ensures:
+
+1. **Stable IDs** — the compiler assigns IDs based on the consumer's source tree
+2. **Replay safety** — IDs persist across deployments and cold starts
+3. **Version upgrades** — re-exported IDs remain stable as long as the consumer's file doesn't change
+
+## Keeping Step I/O Clean
+
+When you publish a workflow library, every step function's inputs and outputs are recorded in the event log. This has two implications:
+
+### 1. Everything Must Be Serializable
+
+Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/cookbook/advanced/custom-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
+
+- Functions or closures
+- `WeakRef`, `WeakMap`, or `WeakSet`
+
+If your library works with complex objects that don't implement custom class serialization, pass serializable configuration into steps and reconstruct the objects inside the step body.
+
+{/* @skip-typecheck - good/bad comparison with duplicate function names */}
+```typescript lineNumbers
+// Good: pass serializable config, construct inside the step
+async function callExternalApi(endpoint: string, params: Record<string, string>) {
+  "use step";
+  const client = createApiClient(process.env.API_KEY!);
+  return await client.request(endpoint, params);
+}
+
+// Bad: pass a pre-constructed client object
+async function callExternalApi(client: ApiClient, params: Record<string, string>) {
+  "use step";
+  // ApiClient is not serializable — this will fail on replay
+  return await client.request(params);
+}
+```
+
+See [Serializable Steps](/docs/cookbook/advanced/serializable-steps) for the step-as-factory pattern.
+
+### 2. Credentials
+
+With workflow encryption enabled, credentials passed as step arguments are encrypted in the event log, so either approach is valid:
+
+{/* @skip-typecheck - good/bad comparison with duplicate function names */}
+```typescript lineNumbers
+// Option A: resolve credentials from environment inside the step
+async function fetchData(query: string) {
+  "use step";
+  const client = createClient(process.env.API_KEY!);
+  return await client.fetch(query);
+}
+
+// Option B: pass credentials as step arguments (encrypted in the event log)
+async function fetchData(apiKey: string, query: string) {
+  "use step";
+  const client = createClient(apiKey);
+  return await client.fetch(query);
+}
+```
+
+The choice is a matter of library API design preference. Resolving from environment variables keeps the step signature simpler, while passing credentials explicitly makes dependencies visible and can be easier to test.
+
+## Testing Workflow Libraries
+
+Library authors need integration tests that exercise workflows through the full Workflow SDK runtime — not just unit tests of individual functions.
+
+### Test Server Pattern
+
+Create a minimal test server that re-exports your library's workflows, just like a consumer would:
+
+```typescript lineNumbers
+// test-server/workflows.ts
+export * from "@acme/media/workflows"; // [!code highlight]
+```
+
+This test server acts as a stand-in consumer app. Point your test runner at it to exercise the full workflow lifecycle: start, replay, and completion.
+
+### Vitest Configuration
+
+Use a dedicated Vitest config for integration tests that run against the Workflow SDK runtime:
+
+```typescript lineNumbers
+// vitest.workflowsdk.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/integration/**/*.workflowsdk.test.ts"],
+    testTimeout: 120_000, // Workflows may take time to complete
+    setupFiles: ["./tests/setup.ts"],
+  },
+});
+```
+
+Run these tests separately from your unit tests:
+
+```bash
+# Unit tests (fast, no workflow runtime)
+pnpm vitest run tests/unit
+
+# Integration tests (requires workflow runtime)
+pnpm vitest run --config vitest.workflowsdk.config.ts
+```
+
+### What to Test
+
+- **Happy path**: workflow starts, all steps execute, and the final result is correct
+- **Serialization round-trip**: inputs and outputs survive the event log
+- **Replay**: kill and restart a workflow mid-execution to verify deterministic replay
+- **Error handling**: verify that step failures produce the expected errors
+
+## Working With and Without Workflow Installed
+
+If your library should work both as a standalone package and inside Workflow SDK, declare `workflow` as an optional peer dependency:
+
+```json
+{
+  "peerDependencies": {
+    "workflow": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "workflow": {
+      "optional": true
+    }
+  }
+}
+```
+
+Use dynamic imports and runtime detection so your library gracefully degrades when workflow is not installed:
+
+```typescript lineNumbers
+async function isWorkflowRuntime(): Promise<boolean> {
+  try {
+    const wf = await import("workflow");
+    if (typeof wf.getWorkflowMetadata !== "function") return false;
+    wf.getWorkflowMetadata(); // [!code highlight]
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+See [Isomorphic Packages](/docs/cookbook/advanced/isomorphic-packages) for the full pattern including feature detection, dynamic imports, and dual-path execution.
+
+## Checklist
+
+Before publishing a workflow library:
+
+- [ ] `workflow` is listed as an **optional** peer dependency
+- [ ] Separate `./workflows` export in `package.json` for the raw workflow functions
+- [ ] `workflow` is marked as **external** in your bundler config
+- [ ] Documentation tells consumers to re-export from `@your-lib/workflows`
+- [ ] Credentials are either resolved from environment variables or passed explicitly (both are safe with encryption enabled)
+- [ ] All step I/O uses [supported serializable types](/docs/foundations/serialization)
+- [ ] Integration tests use a test server with re-exported workflows
+- [ ] Both with-workflow and without-workflow code paths are tested
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
+- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

package/docs/cookbook/advanced/serializable-steps.mdx

@@ -0,0 +1,135 @@
+---
+title: Serializable Steps
+description: Wrap non-serializable objects (like AI model providers) inside step functions so they can cross the workflow boundary.
+type: guide
+summary: Return a callback from a step to defer provider initialization, making non-serializable AI SDK models work inside durable workflows.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Problem
+
+Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable (JSON-safe). AI SDK model providers — `openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc. — return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error.
+
+```typescript lineNumbers
+import { openai } from "@ai-sdk/openai";
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import type { UIMessageChunk } from "ai";
+
+export async function brokenAgent(prompt: string) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+  const agent = new DurableAgent({
+    // This fails — the model object is not serializable
+    model: openai("gpt-4o"),
+  });
+
+  await agent.stream({ messages: [{ role: "user", content: prompt }], writable });
+}
+```
+
+## The Solution: Step-as-Factory
+
+Instead of passing the model object, pass a **callback function** that returns the model. Marking that callback with `"use step"` tells the compiler to serialize the *function reference* (which is just a string identifier) rather than its return value. The provider is only instantiated at execution time, inside the step's full Node.js runtime.
+
+```typescript lineNumbers
+import { openai as openaiProvider } from "@ai-sdk/openai";
+
+// Returns a step function, not a model object
+export function openai(...args: Parameters<typeof openaiProvider>) {
+  return async () => {
+    "use step";
+    return openaiProvider(...args); // [!code highlight]
+  };
+}
+```
+
+The `DurableAgent` receives a function (`() => Promise<LanguageModel>`) instead of a model object. When the agent needs to call the LLM, it invokes the factory inside a step where the real provider can be constructed with full Node.js access.
+
+## How `@workflow/ai` Uses This
+
+The `@workflow/ai` package ships pre-wrapped providers for all major AI SDK backends. Each one follows the same pattern:
+
+```typescript lineNumbers
+// packages/ai/src/providers/anthropic.ts
+import { anthropic as anthropicProvider } from "@ai-sdk/anthropic";
+
+export function anthropic(...args: Parameters<typeof anthropicProvider>) {
+  return async () => {
+    "use step";
+    return anthropicProvider(...args); // [!code highlight]
+  };
+}
+```
+
+This means you import from `@workflow/ai` instead of `@ai-sdk/*` directly:
+
+```typescript lineNumbers
+import { anthropic } from "@workflow/ai/anthropic";
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import type { UIMessageChunk } from "ai";
+
+export async function chatAgent(prompt: string) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+  const agent = new DurableAgent({
+    model: anthropic("claude-sonnet-4-20250514"), // [!code highlight]
+  });
+
+  await agent.stream({ messages: [{ role: "user", content: prompt }], writable });
+}
+```
+
+## Writing Your Own Serializable Wrapper
+
+Apply the same pattern to any non-serializable dependency. The key rule: **the outer function captures serializable arguments, and the inner `"use step"` function constructs the real object at runtime**.
+
+```typescript lineNumbers
+import type { S3Client as S3ClientType } from "@aws-sdk/client-s3";
+
+// The arguments (region, bucket) are plain strings — serializable
+export function createS3Client(region: string) {
+  return async (): Promise<S3ClientType> => {
+    "use step";
+    const { S3Client } = await import("@aws-sdk/client-s3");
+    return new S3Client({ region });
+  };
+}
+
+// Usage in a workflow
+export async function processUpload(region: string, key: string) {
+  "use workflow";
+
+  const getClient = createS3Client(region); // [!code highlight]
+  // getClient is a serializable step reference, not an S3Client
+  await uploadFile(getClient, key);
+}
+
+async function uploadFile(
+  getClient: () => Promise<S3ClientType>,
+  key: string
+) {
+  "use step";
+  const client = await getClient(); // [!code highlight]
+  // Now you have a real S3Client with full Node.js access
+  await client.send(/* ... */);
+}
+```
+
+## Why This Works
+
+1. **Compiler transformation**: `"use step"` tells the SWC plugin to extract the function into a separate bundle. The workflow VM only sees a serializable reference (function ID + captured arguments).
+2. **Closure tracking**: The compiler tracks which variables the step function closes over. Only serializable values (strings, numbers, plain objects) can be captured.
+3. **Deferred construction**: The actual provider/client is only constructed when the step executes in the Node.js runtime — never in the sandboxed workflow VM.
+
+## Key APIs
+
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming

package/docs/cookbook/agent-patterns/durable-agent.mdx

@@ -0,0 +1,191 @@
+---
+title: Durable Agent
+description: Replace a stateless AI agent with a durable one that survives crashes, retries tool calls, and streams output.
+type: guide
+summary: Convert an AI SDK Agent into a DurableAgent backed by a workflow, with tools as retryable steps.
+---
+
+Use this pattern to make any AI SDK agent durable. The agent becomes a workflow, tools become steps, and the framework handles retries, streaming, and state persistence automatically.
+
+## Pattern
+
+Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
+
+### Simplified
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+declare function searchFlights(args: { from: string; to: string; date: string }): Promise<{ flights: { id: string; price: number }[] }>; // @setup
+declare function bookFlight(args: { flightId: string; passenger: string }): Promise<{ confirmationId: string }>; // @setup
+
+export async function flightAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You are a helpful flight booking assistant.",
+    tools: {
+      searchFlights: {
+        description: "Search for available flights",
+        inputSchema: z.object({
+          from: z.string(),
+          to: z.string(),
+          date: z.string(),
+        }),
+        execute: searchFlights,
+      },
+      bookFlight: {
+        description: "Book a specific flight",
+        inputSchema: z.object({
+          flightId: z.string(),
+          passenger: z.string(),
+        }),
+        execute: bookFlight,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages,
+    writable: getWritable<UIMessageChunk>(),
+  });
+}
+```
+
+### Full Implementation
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+// Step: Search flights with full Node.js access and automatic retries
+async function searchFlights({
+  from,
+  to,
+  date,
+}: {
+  from: string;
+  to: string;
+  date: string;
+}) {
+  "use step";
+
+  const response = await fetch(
+    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
+  );
+  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
+  return response.json();
+}
+
+// Step: Book a flight — retries on transient failures
+async function bookFlight({
+  flightId,
+  passenger,
+}: {
+  flightId: string;
+  passenger: string;
+}) {
+  "use step";
+
+  const response = await fetch("https://api.example.com/bookings", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ flightId, passenger }),
+  });
+  if (!response.ok) throw new Error(`Booking failed: ${response.status}`);
+  return response.json();
+}
+
+// Step: Check flight status
+async function checkStatus({ flightId }: { flightId: string }) {
+  "use step";
+
+  const response = await fetch(
+    `https://api.example.com/flights/${flightId}/status`
+  );
+  return response.json();
+}
+
+export async function flightAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You are a helpful flight booking assistant.",
+    tools: {
+      searchFlights: {
+        description: "Search for available flights between two airports",
+        inputSchema: z.object({
+          from: z.string().describe("Departure airport code"),
+          to: z.string().describe("Arrival airport code"),
+          date: z.string().describe("Travel date (YYYY-MM-DD)"),
+        }),
+        execute: searchFlights,
+      },
+      bookFlight: {
+        description: "Book a specific flight for a passenger",
+        inputSchema: z.object({
+          flightId: z.string().describe("Flight ID from search results"),
+          passenger: z.string().describe("Passenger full name"),
+        }),
+        execute: bookFlight,
+      },
+      checkStatus: {
+        description: "Check the current status of a flight",
+        inputSchema: z.object({
+          flightId: z.string().describe("Flight ID to check"),
+        }),
+        execute: checkStatus,
+      },
+    },
+  });
+
+  const result = await agent.stream({ // [!code highlight]
+    messages,
+    writable,
+    maxSteps: 10,
+  });
+
+  return { messages: result.messages };
+}
+```
+
+### API Route
+
+```typescript lineNumbers
+import { createUIMessageStreamResponse } from "ai";
+import { start } from "workflow/api";
+import { flightAgent } from "@/workflows/flight-agent";
+import type { UIMessage } from "ai";
+import { convertToModelMessages } from "ai";
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const modelMessages = await convertToModelMessages(messages);
+
+  const run = await start(flightAgent, [modelMessages]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: {
+      "x-workflow-run-id": run.runId,
+    },
+  });
+}
+```
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — declares step functions with retries and full Node.js access
+- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable wrapper around AI SDK's Agent
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) — streams agent output to the client
+- [`start()`](/docs/api-reference/workflow-api/start) — starts a workflow run from an API route