workflow 5.0.0-beta.2 → 5.0.0-beta.4

package/docs/cookbook/advanced/custom-serialization.mdx

@@ -1,168 +0,0 @@
----
-title: Custom Serialization
-description: Make class instances serializable across workflow boundaries using the WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbol protocol.
-type: guide
-summary: Implement the WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbol protocol on classes so instances survive serialization when passed between workflow and step functions.
----
-
-<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. Every value that crosses a function boundary — step arguments, step return values, workflow inputs — must be [serializable](/docs/foundations/serialization). Plain objects, strings, numbers, and many built-in types (`Date`, `Map`, `Set`, `RegExp`, etc.) work automatically, but **class instances** that don't implement the custom class serialization protocol will throw a serialization error.
-
-```typescript lineNumbers
-class StorageClient {
-  constructor(private region: string) {}
-
-  async upload(key: string, body: Uint8Array) {
-    // ... uses this.region internally
-  }
-}
-
-export async function processFile(client: StorageClient) {
-  "use workflow";
-
-  // client fails to serialize — StorageClient doesn't implement custom class serialization
-  // The runtime throws a serialization error
-  await uploadStep(client, "output.json", data);
-}
-```
-
-Custom class serialization solves this by teaching the runtime how to convert your class instances to plain data and back.
-
-## The WORKFLOW_SERIALIZE / WORKFLOW_DESERIALIZE Protocol
-
-The `@workflow/serde` package exports two symbols that act as a custom class serialization protocol. When the workflow runtime encounters a class instance with these symbols, it knows how to convert it to plain data and back.
-
-{/* @skip-typecheck - @workflow/serde is not mapped in the type-checker */}
-```typescript lineNumbers
-import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
-
-class Point {
-  constructor(public x: number, public y: number) {}
-
-  distanceTo(other: Point): number {
-    return Math.sqrt((this.x - other.x) ** 2 + (this.y - other.y) ** 2);
-  }
-
-  static [WORKFLOW_SERIALIZE](instance: Point) { // [!code highlight]
-    return { x: instance.x, y: instance.y };
-  }
-
-  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) { // [!code highlight]
-    return new Point(data.x, data.y);
-  }
-}
-```
-
-Both methods must be **static**. `WORKFLOW_SERIALIZE` receives an instance and returns plain serializable data. `WORKFLOW_DESERIALIZE` receives that same data and reconstructs a new instance.
-
-<Callout type="warn">
-Both serialization methods run inside the workflow VM. They must not use Node.js APIs, non-deterministic operations, or network calls. Keep them focused on extracting and reconstructing data.
-</Callout>
-
-## Automatic Class Registration
-
-For the runtime to deserialize a class, the class must be registered in a global registry with a stable `classId`. The SWC compiler plugin handles this automatically — when it detects a class with both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` static methods, it generates registration code at build time.
-
-This means you only need to implement the two symbol methods. The compiler assigns a deterministic `classId` based on the file path and class name, and registers it in the global `Symbol.for("workflow-class-registry")` registry.
-
-<Callout type="info">
-No manual registration is required for classes defined in your workflow files. The SWC plugin detects the serialization symbols and generates the registration automatically at build time.
-</Callout>
-
-## Full Example: A Workflow-Safe Storage Client
-
-Here's a complete example of a storage client class that survives serialization across workflow boundaries. This pattern is useful when you need an object with methods to be passed as a workflow input or returned from a step.
-
-```typescript lineNumbers
-import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
-
-interface StorageClientOptions {
-  region: string;
-  bucket: string;
-  accessKeyId?: string;
-  secretAccessKey?: string;
-}
-
-export class WorkflowStorageClient {
-  private readonly region: string;
-  private readonly bucket: string;
-  private readonly accessKeyId?: string;
-  private readonly secretAccessKey?: string;
-
-  constructor(options: StorageClientOptions) {
-    this.region = options.region;
-    this.bucket = options.bucket;
-    this.accessKeyId = options.accessKeyId;
-    this.secretAccessKey = options.secretAccessKey;
-  }
-
-  async upload(key: string, body: Uint8Array) {
-    "use step";
-    const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
-    const client = new S3Client({
-      region: this.region,
-      credentials: this.accessKeyId
-        ? { accessKeyId: this.accessKeyId, secretAccessKey: this.secretAccessKey! }
-        : undefined,
-    });
-    await client.send(
-      new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body })
-    );
-  }
-
-  async getSignedUrl(key: string): Promise<string> {
-    "use step";
-    const { S3Client, GetObjectCommand } = await import("@aws-sdk/client-s3");
-    const { getSignedUrl } = await import("@aws-sdk/s3-request-presigner");
-    const client = new S3Client({ region: this.region });
-    return getSignedUrl(client, new GetObjectCommand({ Bucket: this.bucket, Key: key }));
-  }
-
-  // --- Serialization protocol ---
-
-  static [WORKFLOW_SERIALIZE](instance: WorkflowStorageClient): StorageClientOptions { // [!code highlight]
-    return {
-      region: instance.region,
-      bucket: instance.bucket,
-      accessKeyId: instance.accessKeyId,
-      secretAccessKey: instance.secretAccessKey,
-    };
-  }
-
-  static [WORKFLOW_DESERIALIZE]( // [!code highlight]
-    data: StorageClientOptions
-  ): WorkflowStorageClient {
-    return new WorkflowStorageClient(data);
-  }
-}
-```
-
-Now this client can be passed into a workflow and used directly:
-
-```typescript lineNumbers
-import { WorkflowStorageClient } from "./storage-client";
-
-export async function processUpload(
-  client: WorkflowStorageClient,
-  data: Uint8Array
-) {
-  "use workflow";
-
-  // client is a real WorkflowStorageClient with working methods
-  await client.upload("output/result.json", data); // [!code highlight]
-  const url = await client.getSignedUrl("output/result.json"); // [!code highlight]
-  return { url };
-}
-```
-
-## Key APIs
-
-- [`WORKFLOW_SERIALIZE`](/docs/api-reference/workflow-serde/workflow-serialize) — symbol for the static serialization method
-- [`WORKFLOW_DESERIALIZE`](/docs/api-reference/workflow-serde/workflow-deserialize) — symbol for the static deserialization method
-- [`"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

package/docs/cookbook/advanced/durable-objects.mdx

@@ -1,148 +0,0 @@
----
-title: Durable Objects
-description: Model long-lived stateful entities as workflows that persist state across requests.
-type: guide
-summary: Build a durable counter or session object whose state survives restarts by using a workflow's event log as the persistence layer.
----
-
-<Callout>
-This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
-</Callout>
-
-## The Idea
-
-A workflow's event log already records every step result and replays them to reconstruct state. This is the same property that makes an "object" durable — its fields survive cold starts, crashes, and redeployments. Instead of using a workflow to model a *process*, you can use one to model an *entity* with methods.
-
-Each "method call" is a hook that the object's workflow loop awaits. External callers resume the hook with a payload describing the operation. The workflow applies the operation, updates its internal state, and waits for the next call.
-
-## Pattern: Durable Counter
-
-A counter that persists its value without a database. Each increment/decrement is recorded in the event log.
-
-```typescript lineNumbers
-import { defineHook, getWorkflowMetadata } from "workflow";
-import { z } from "zod";
-
-const counterAction = defineHook({ // [!code highlight]
-  schema: z.object({
-    type: z.enum(["increment", "decrement", "get"]),
-    amount: z.number().default(1),
-  }),
-});
-
-export async function durableCounter() {
-  "use workflow";
-
-  let count = 0;
-  const { workflowRunId } = getWorkflowMetadata();
-
-  while (true) {
-    const hook = counterAction.create({ token: `counter:${workflowRunId}` });
-    const action = await hook; // [!code highlight]
-
-    switch (action.type) {
-      case "increment":
-        count += action.amount;
-        await recordState(count);
-        break;
-      case "decrement":
-        count -= action.amount;
-        await recordState(count);
-        break;
-      case "get":
-        await emitValue(count);
-        break;
-    }
-  }
-}
-
-async function recordState(count: number) {
-  "use step";
-  // Step records the state transition in the event log.
-  // On replay, the step result restores `count` without re-executing.
-  return count;
-}
-
-async function emitValue(count: number) {
-  "use step";
-  return { count };
-}
-```
-
-### Calling the Object
-
-From an API route, resume the hook to "invoke a method" on the durable object:
-
-```typescript lineNumbers
-import { resumeHook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const { runId, type, amount } = await request.json();
-  await resumeHook(`counter:${runId}`, { type, amount }); // [!code highlight]
-  return Response.json({ ok: true });
-}
-```
-
-## Pattern: Durable Session
-
-A chat session where conversation history is the durable state. Each user message is a hook event; the workflow accumulates messages and generates responses.
-
-```typescript lineNumbers
-import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
-import { DurableAgent } from "@workflow/ai/agent";
-import { anthropic } from "@workflow/ai/anthropic";
-import { z } from "zod";
-import type { UIMessageChunk, ModelMessage } from "ai";
-
-const messageHook = defineHook({ // [!code highlight]
-  schema: z.object({
-    role: z.literal("user"),
-    content: z.string(),
-  }),
-});
-
-export async function durableSession() {
-  "use workflow";
-
-  const writable = getWritable<UIMessageChunk>();
-  const { workflowRunId: runId } = getWorkflowMetadata();
-  const messages: ModelMessage[] = [];
-
-  const agent = new DurableAgent({
-    model: anthropic("claude-sonnet-4-20250514"),
-    instructions: "You are a helpful assistant.",
-  });
-
-  while (true) {
-    const hook = messageHook.create({ token: `session:${runId}` });
-    const userMessage = await hook; // [!code highlight]
-
-    messages.push({
-      role: userMessage.role,
-      content: userMessage.content,
-    });
-
-    await agent.stream({ messages, writable });
-  }
-}
-```
-
-## When to Use This
-
-- **Entity-per-workflow**: Each user, document, or device gets its own workflow run. The run ID is the entity ID.
-- **No external database needed**: State lives in the event log. Reads replay from the log; writes append to it.
-- **Automatic consistency**: Only one execution runs at a time per workflow run, so there are no race conditions on the entity's state.
-
-## Trade-offs
-
-- **Read latency**: Accessing current state requires replaying the event log (or caching the last known state in a step result).
-- **Not a replacement for databases**: If you need to query across entities (e.g., "all counters above 100"), you still need a database. Durable objects are for single-entity state.
-- **Log growth**: Long-lived objects accumulate large event logs. Consider periodic "snapshot" steps that checkpoint the full state.
-
-## 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
-- [`defineHook`](/docs/api-reference/workflow/define-hook) — type-safe hook for receiving external method calls
-- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
-- [`resumeHook`](/docs/api-reference/workflow-api/resume-hook) — invoke a method on the durable object from an API route

package/docs/cookbook/advanced/isomorphic-packages.mdx

@@ -1,145 +0,0 @@
----
-title: Isomorphic Packages
-description: Publish reusable workflow packages that work both inside and outside the workflow runtime.
-type: guide
-summary: Use try/catch around getWorkflowMetadata, dynamic imports, and optional peer dependencies to build libraries that run in workflows and in plain Node.js.
----
-
-<Callout>
-This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
-</Callout>
-
-## The Challenge
-
-If you're a library author publishing a package that integrates with workflow, your code needs to handle two environments:
-
-1. **Inside a workflow run** — `getWorkflowMetadata()` works, `"use step"` directives are transformed, and the full workflow runtime is available.
-2. **Outside a workflow** — your package is imported in a regular Node.js process, a test suite, or a project that doesn't use workflow at all.
-
-A hard dependency on `workflow` will crash at import time for users who don't have it installed.
-
-## Pattern 1: Feature-Detect with `getWorkflowMetadata`
-
-Use a try/catch to detect whether you're running inside a workflow. This lets you add durable behavior when available and fall back to standard execution otherwise.
-
-```typescript lineNumbers
-import { getWorkflowMetadata } from "workflow";
-
-export async function processPayment(amount: number, currency: string) {
-  "use workflow";
-
-  let runId: string | undefined;
-  try {
-    const metadata = getWorkflowMetadata(); // [!code highlight]
-    runId = metadata.workflowRunId;
-  } catch {
-    // Not running inside a workflow — proceed without durability
-    runId = undefined;
-  }
-
-  if (runId) {
-    // Inside a workflow: use the run ID as an idempotency key
-    return await chargeWithIdempotency(amount, currency, runId); // [!code highlight]
-  } else {
-    // Outside a workflow: standard charge
-    return await chargeStandard(amount, currency);
-  }
-}
-
-async function chargeWithIdempotency(amount: number, currency: string, idempotencyKey: string) {
-  "use step";
-  // Stripe charge with idempotency key from workflow run ID
-  return { charged: true, amount, currency, idempotencyKey };
-}
-
-async function chargeStandard(amount: number, currency: string) {
-  "use step";
-  return { charged: true, amount, currency };
-}
-```
-
-## Pattern 2: Dynamic Imports
-
-Avoid importing `workflow` at the top level. Use dynamic `import()` so the module is only loaded when actually needed.
-
-```typescript lineNumbers
-export async function createDurableTask(name: string, payload: unknown) {
-  "use workflow";
-
-  let sleep: ((duration: string) => Promise<void>) | undefined;
-
-  try {
-    const wf = await import("workflow"); // [!code highlight]
-    sleep = wf.sleep;
-  } catch {
-    // workflow not installed — use setTimeout fallback
-    sleep = undefined;
-  }
-
-  await executeTask(name, payload);
-
-  if (sleep) {
-    // Inside workflow: durable sleep that survives restarts
-    await sleep("5m"); // [!code highlight]
-  } else {
-    // Outside workflow: plain timer (not durable)
-    await new Promise((resolve) => setTimeout(resolve, 5 * 60 * 1000));
-  }
-
-  await sendNotification(name);
-}
-
-async function executeTask(name: string, payload: unknown) {
-  "use step";
-  return { executed: true, name, payload };
-}
-
-async function sendNotification(name: string) {
-  "use step";
-  return { notified: true, name };
-}
-```
-
-## Pattern 3: Optional Peer Dependencies
-
-In your `package.json`, declare `workflow` as an optional peer dependency. This signals to package managers that your library *can* use workflow but doesn't require it.
-
-```json
-{
-  "name": "@acme/payments",
-  "peerDependencies": {
-    "workflow": ">=1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "workflow": {
-      "optional": true
-    }
-  }
-}
-```
-
-Then guard all workflow imports with dynamic `import()` and try/catch as shown above.
-
-## Real-World Examples
-
-### Mux AI
-
-The Mux team published a reusable workflow package for video processing. Their library detects the workflow runtime and falls back to standard async processing when workflow isn't available.
-
-### World ID
-
-World ID's identity verification library uses `getWorkflowMetadata()` to attach run IDs to their human-in-the-loop verification hooks, but the same library works in non-workflow environments for simple verification flows.
-
-## Guidelines for Library Authors
-
-1. **Never hard-import `workflow` at the top level** if your package should work without it.
-2. **Use `getWorkflowMetadata()` in a try/catch** as the canonical runtime detection pattern.
-3. **Mark `workflow` as an optional peer dependency** in `package.json`.
-4. **Test both paths**: run your test suite with and without the workflow runtime to catch import errors.
-5. **Document the dual behavior**: make it clear in your README which features require workflow and which work standalone.
-
-## 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
-- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

package/docs/cookbook/agent-patterns/stop-workflow.mdx

@@ -1,216 +0,0 @@
----
-title: Stop Workflow
-description: Gracefully cancel a running agent workflow using a hook signal.
-type: guide
-summary: Use a hook as a stop signal to break out of an agent loop and close the stream cleanly.
----
-
-Use this pattern when you need to gracefully stop a running agent from the outside — for example, a "Stop" button in a chat UI or an admin cancellation endpoint. The workflow listens for a stop signal via a hook while the agent runs, and breaks out of the loop when the signal arrives.
-
-## Pattern
-
-Create a hook with a known token (the run ID). Listen for a stop signal in a non-blocking `.then()`. In the `prepareStep` callback, check the flag and return `{ toolChoice: "none" }` to prevent further tool calls, causing the agent to generate a final response and exit the loop cleanly.
-
-### Simplified
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-export const stopHook = defineHook({
-  schema: z.object({ reason: z.string().optional() }),
-});
-
-declare function processQuery(args: { query: string }): Promise<string>; // @setup
-
-export async function stoppableAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const { workflowRunId } = getWorkflowMetadata();
-  let stopRequested = false;
-
-  const hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
-  hook.then(() => { stopRequested = true; }); // [!code highlight]
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    tools: {
-      processQuery: {
-        description: "Process a query",
-        inputSchema: z.object({ query: z.string() }),
-        execute: processQuery,
-      },
-    },
-  });
-
-  const result = await agent.stream({
-    messages,
-    writable: getWritable<UIMessageChunk>(),
-    prepareStep: () => { // [!code highlight]
-      if (stopRequested) return { toolChoice: "none" }; // [!code highlight]
-      return {};
-    },
-  });
-
-  return { messages: result.messages, stopped: stopRequested };
-}
-```
-
-### Full Implementation
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-// Hook to signal the workflow to stop
-export const stopHook = defineHook({
-  schema: z.object({
-    reason: z.string().optional(),
-  }),
-});
-
-// Step: Search the web
-async function searchWeb({ query }: { query: string }) {
-  "use step";
-
-  await new Promise((resolve) => setTimeout(resolve, 1000));
-  return { results: [`Result for "${query}"`] };
-}
-
-// Step: Analyze data
-async function analyzeData({ data }: { data: string }) {
-  "use step";
-
-  await new Promise((resolve) => setTimeout(resolve, 800));
-  return { analysis: `Analysis of: ${data}` };
-}
-
-// Step: Write the final close marker to the stream
-async function closeStream() {
-  "use step";
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-  try {
-    await writer.write({ type: "finish" } as UIMessageChunk);
-  } finally {
-    writer.releaseLock();
-  }
-  await writable.close();
-}
-
-export async function stoppableAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const { workflowRunId } = getWorkflowMetadata();
-  const writable = getWritable<UIMessageChunk>();
-
-  // Listen for stop signal using a non-blocking hook
-  let stopRequested = false;
-  let stopReason: string | undefined;
-
-  const hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
-  hook.then(({ reason }) => { // [!code highlight]
-    stopRequested = true;
-    stopReason = reason;
-  });
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a research assistant. Search and analyze data as needed.",
-    tools: {
-      searchWeb: {
-        description: "Search the web for information",
-        inputSchema: z.object({ query: z.string() }),
-        execute: searchWeb,
-      },
-      analyzeData: {
-        description: "Analyze a piece of data",
-        inputSchema: z.object({ data: z.string() }),
-        execute: analyzeData,
-      },
-    },
-  });
-
-  const result = await agent.stream({
-    messages,
-    writable,
-    preventClose: true,
-    maxSteps: 20,
-    prepareStep: ({ stepNumber }) => { // [!code highlight]
-      // Check stop flag before each agent step.
-      // Setting toolChoice to "none" prevents tool calls,
-      // causing the agent to generate a final response and exit.
-      if (stopRequested) {
-        return { toolChoice: "none" }; // [!code highlight]
-      }
-      return {};
-    },
-  });
-
-  // Clean up: close the stream
-  await closeStream();
-
-  return {
-    messages: result.messages,
-    stopped: stopRequested,
-    stopReason,
-    stepsCompleted: result.steps.length,
-  };
-}
-```
-
-### API Route to Trigger Stop
-
-```typescript lineNumbers
-import { stopHook } from "@/workflows/stoppable-agent";
-
-export async function POST(
-  request: Request,
-  { params }: { params: Promise<{ runId: string }> }
-) {
-  const { runId } = await params;
-  const { reason } = await request.json();
-
-  await stopHook.resume(`stop:${runId}`, { // [!code highlight]
-    reason: reason || "User requested stop",
-  });
-
-  return Response.json({ success: true });
-}
-```
-
-### Client Stop Button
-
-```tsx lineNumbers
-"use client";
-
-export function StopButton({ runId }: { runId: string }) {
-  const handleStop = async () => {
-    await fetch(`/api/chat/${runId}/stop`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ reason: "User clicked stop" }),
-    });
-  };
-
-  return (
-    <button type="button" onClick={handleStop}>
-      Stop Agent
-    </button>
-  );
-}
-```
-
-## 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
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook for the stop signal
-- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream output and close cleanly on stop
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — `prepareStep` callback to check stop flag before each step