workflow 5.0.0-beta.1 → 5.0.0-beta.11

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -0,0 +1,255 @@
+---
+title: Human-in-the-Loop
+description: Pause an AI agent to wait for human approval, then resume based on the decision.
+type: guide
+summary: Use defineHook with the tool call ID to suspend an agent for human approval, with an optional timeout.
+---
+
+Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds.
+
+## When to use this
+
+- Booking confirmations where users must approve before charges are made
+- Content publishing gates where an editor must sign off
+- Any agent action where the cost of getting it wrong justifies a human check
+- Actions with side effects that can't be easily undone
+
+## Pattern
+
+Create a typed hook using `defineHook()`. When the agent calls the approval tool, the tool emits a custom data part to the stream so the client can render approval controls, then creates a hook and suspends. An API route resumes the hook with the decision.
+
+### Workflow
+
+```typescript
+import { DurableAgent } from "@workflow/ai/agent";
+import { defineHook, sleep, getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+// Exported so the approval API route can call .resume()
+export const bookingApprovalHook = defineHook({ // [!code highlight]
+  schema: z.object({
+    approved: z.boolean(),
+    comment: z.string().optional(),
+  }),
+});
+
+async function searchFlights({ from, to, date }: {
+  from: string;
+  to: string;
+  date: string;
+}) {
+  "use step";
+  const res = await fetch(
+    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
+  );
+  return res.json();
+}
+
+async function confirmBooking({ flightId, passenger }: {
+  flightId: string;
+  passenger: string;
+}) {
+  "use step";
+  const res = await fetch("https://api.example.com/bookings", {
+    method: "POST",
+    body: JSON.stringify({ flightId, passenger }),
+  });
+  return res.json();
+}
+
+// Stream a custom data part so the client can render the approval UI.
+// This MUST run before the hook suspends the workflow — otherwise
+// the tool-invocation won't appear in the stream until the tool returns,
+// and the client would have no way to show approval buttons.
+async function emitApprovalRequest(details: {
+  flightId: string;
+  passenger: string;
+  price: number;
+  toolCallId: string;
+}) {
+  "use step";
+  const writer = getWritable<UIMessageChunk>().getWriter();
+  try {
+    await writer.write({
+      type: "data-approval-needed", // [!code highlight]
+      id: details.toolCallId,
+      data: details,
+    } as UIMessageChunk);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+// Stream the resolution so the client can update the approval card.
+async function emitApprovalResolved(details: {
+  toolCallId: string;
+  result: string;
+}) {
+  "use step";
+  const writer = getWritable<UIMessageChunk>().getWriter();
+  try {
+    await writer.write({
+      type: "data-approval-resolved", // [!code highlight]
+      id: details.toolCallId,
+      data: details,
+    } as UIMessageChunk);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+// No "use step" — hooks are workflow-level primitives
+async function requestBookingApproval(
+  { flightId, passenger, price }: {
+    flightId: string;
+    passenger: string;
+    price: number;
+  },
+  { toolCallId }: { toolCallId: string }
+) {
+  // Emit to the stream before suspending so the UI can show buttons
+  await emitApprovalRequest({ flightId, passenger, price, toolCallId }); // [!code highlight]
+
+  const hook = bookingApprovalHook.create({ token: toolCallId });
+
+  // Race: human decision vs. timeout
+  const result = await Promise.race([
+    hook.then((payload) => ({ type: "decision" as const, ...payload })),
+    sleep("24h").then(() => ({ type: "timeout" as const, approved: false as const })),
+  ]);
+
+  if (result.type === "timeout") {
+    const msg = "Booking request expired.";
+    await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+    return msg;
+  }
+  if (!result.approved) {
+    const msg = `Rejected: ${result.comment || "No reason given"}`;
+    await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+    return msg;
+  }
+
+  const booking = await confirmBooking({ flightId, passenger });
+  const msg = `Booked! Confirmation: ${booking.confirmationId}`;
+  await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+  return msg;
+}
+
+export async function bookingAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You help book flights. Always request approval before booking.",
+    tools: {
+      searchFlights: {
+        description: "Search for available flights",
+        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,
+      },
+      requestBookingApproval: {
+        description: "Request human approval before booking a flight",
+        inputSchema: z.object({
+          flightId: z.string().describe("Flight ID to book"),
+          passenger: z.string().describe("Passenger name"),
+          price: z.number().describe("Total price"),
+        }),
+        execute: requestBookingApproval,
+      },
+    },
+  });
+
+  await agent.stream({
+    messages,
+    writable: getWritable<UIMessageChunk>(),
+  });
+}
+```
+
+### Approval API route
+
+The approval route imports the hook definition and calls `.resume()` with the tool call ID as the token:
+
+```typescript
+import { bookingApprovalHook } from "@/app/workflows/booking-agent";
+
+export async function POST(req: Request) {
+  const { toolCallId, approved, comment } = await req.json();
+
+  await bookingApprovalHook.resume(toolCallId, { approved, comment }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+### Client rendering
+
+Listen for `data-approval-needed` and `data-approval-resolved` custom data parts in the message stream. The approval tool invocation itself won't appear until the tool returns, so the custom data parts are the mechanism for showing and updating the approval UI.
+
+```tsx
+// Scan all messages for the resolution
+const approvalResult = messages
+  .flatMap((m) => m.parts)
+  .find((p) => p.type === "data-approval-resolved")
+  ?.data?.result;
+
+// In your message parts loop:
+{message.parts.map((part, i) => {
+  if (part.type === "data-approval-needed") { // [!code highlight]
+    const { flightId, passenger, price, toolCallId } = part.data;
+    if (approvalResult) {
+      return <div key={i}>Result: {approvalResult}</div>;
+    }
+    return (
+      <div key={i} className="rounded-lg border p-4 space-y-3">
+        <div className="text-sm">
+          <div>Flight: {flightId}</div>
+          <div>Passenger: {passenger}</div>
+          <div>Price: ${price}</div>
+        </div>
+        <div className="flex gap-2">
+          <button onClick={() => approve(toolCallId)}>Approve</button> {/* [!code highlight] */}
+          <button onClick={() => reject(toolCallId)}>Reject</button> {/* [!code highlight] */}
+        </div>
+      </div>
+    );
+  }
+  // Hide the requestBookingApproval tool-invocation part
+  if (part.type === "tool-invocation" &&
+      part.toolInvocation.toolName === "requestBookingApproval") {
+    return null;
+  }
+  // ... other part types
+})}
+```
+
+## How it works
+
+1. **`defineHook()` with schema** — creates a typed hook with Zod validation. The approval payload is validated before the workflow receives it.
+2. **`toolCallId` as token** — the approval tool uses the tool call ID as the hook token, naturally linking the hook to the specific tool invocation.
+3. **`emitApprovalRequest` step** — writes a `data-approval-needed` custom data part to the stream *before* the hook suspends. Without this, the client would never see the approval controls because tool invocations don't stream until the tool returns.
+4. **No `"use step"` on the approval tool** — the tool runs at the workflow level because `defineHook().create()` is a workflow primitive. It calls step functions (`emitApprovalRequest`, `emitApprovalResolved`, `confirmBooking`) for I/O.
+5. **`Promise.race` with sleep** — the approval races against a durable timeout. If nobody responds, the workflow continues with an expiration message.
+6. **`emitApprovalResolved` step** — writes the outcome to the stream so the client can update the card immediately, without waiting for the tool-invocation result.
+
+## Adapting to your use case
+
+- **Change the approval schema** — add fields like `reason`, `amount`, `reviewerEmail` to match your domain.
+- **Multiple approval gates** — the pattern works for any number of tools. Each tool creates its own hook with its own `toolCallId`.
+- **Escalation** — if the first approver doesn't respond, use `sleep()` + another hook to escalate to a backup reviewer.
+- **Adjust timeout** — use `"24h"` for production, shorter durations for demos.
+- **Workflow-level vs step tools** — tools that use `sleep()`, `defineHook()`, or other workflow primitives must NOT use `"use step"`. Tools with only I/O (API calls, DB queries) should use `"use step"` for retries.
+
+## 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 with schema validation
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream custom data parts from steps
+- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable agent with tool definitions

package/docs/cookbook/agent-patterns/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Agent Patterns",
+  "pages": ["durable-agent", "human-in-the-loop", "agent-cancellation"]
+}

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

@@ -0,0 +1,105 @@
+---
+title: Batching & Parallel Processing
+description: Process large collections in parallel batches with failure isolation between groups.
+type: guide
+summary: Split items into fixed-size batches, process each batch concurrently with Promise.allSettled, and pace batches with sleep to avoid overloading downstream services.
+---
+
+Use batching when you need to process a large list of items in parallel while controlling concurrency. Items are split into fixed-size batches, each batch runs concurrently, and failures in one batch don't affect others.
+
+## When to use this
+
+- Bulk data imports (contacts, orders, products from a CSV)
+- Processing hundreds or thousands of items against external APIs
+- Calling rate-limited APIs where you need to control concurrency
+- Any fan-out where you want failure isolation between groups
+
+## How it works
+
+1. Records are split into fixed-size batches.
+2. Each batch runs in parallel via `Promise.allSettled` — failures in one record don't affect others.
+3. A `sleep()` between batches paces requests to avoid overloading downstream services.
+4. After all batches, a summary is returned with succeeded/failed counts.
+
+## Pattern
+
+The workflow splits records into chunks, processes each chunk concurrently, tracks results per batch, and returns a final tally.
+
+```typescript
+import { sleep } from "workflow";
+
+type Record = { name: string; email: string; role: string };
+
+declare function processRecord(record: Record): Promise<string>; // @setup
+
+export async function batchImport(records: Record[], batchSize: number) {
+  "use workflow";
+
+  let totalSucceeded = 0;
+  let totalFailed = 0;
+
+  for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
+
+    // Run batch in parallel — failures are isolated per record
+    const outcomes = await Promise.allSettled( // [!code highlight]
+      batch.map((record) => processRecord(record))
+    );
+
+    for (let j = 0; j < outcomes.length; j++) {
+      if (outcomes[j].status === "fulfilled") {
+        totalSucceeded++;
+      } else {
+        totalFailed++;
+      }
+    }
+
+    // Pace between batches to avoid overloading downstream
+    if (i + batchSize < records.length) {
+      await sleep("1s"); // [!code highlight]
+    }
+  }
+
+  return { total: records.length, succeeded: totalSucceeded, failed: totalFailed };
+}
+```
+
+### Step function
+
+Each record is processed in its own step with full Node.js access and automatic retries.
+
+```typescript
+type Record = { name: string; email: string; role: string };
+
+async function processRecord(record: Record): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/contacts`, {
+    method: "POST",
+    body: JSON.stringify(record),
+  });
+  if (!res.ok) throw new Error(`Failed to import ${record.email}`);
+  const { id } = await res.json();
+  return id;
+}
+```
+
+## Adapting to your use case
+
+- Replace the `Record` type with your actual data shape (orders, images, products, etc.).
+- Replace `processRecord()` with your real import logic — DB upserts, API calls, file processing.
+- Tune `batchSize` and the `sleep()` duration to match your downstream rate limits.
+- Add or remove tracking as needed — the pattern works with any item type.
+
+## Tips
+
+- **Use `Promise.allSettled` over `Promise.all`** when you want to continue even if some items fail. `Promise.all` rejects on the first failure; `allSettled` waits for everything and tells you what failed.
+- **Tune batch size to your downstream API limits.** If the API allows 10 concurrent requests, use `batchSize: 10`.
+- **Add pacing with `sleep()`** between batches to respect rate limits. The sleep is durable — it survives cold starts.
+- **Each `processRecord` call is an independent step.** If one fails, it retries up to 3 times without affecting other items in the batch.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- pacing delay between batches
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) -- runs items in parallel, isolating failures

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

@@ -0,0 +1,107 @@
+---
+title: Idempotency
+description: Ensure external side effects happen exactly once, even when steps are retried or workflows are replayed.
+type: guide
+summary: Use step IDs as idempotency keys for external APIs like Stripe so that retries and replays don't create duplicate charges.
+---
+
+Workflow steps can be retried (on failure) and replayed (on cold start). If a step calls an external API that isn't idempotent, retries could create duplicate charges, send duplicate emails, or double-process records. Use idempotency keys to make these operations safe.
+
+## When to use this
+
+- Charging a payment (Stripe, PayPal)
+- Sending transactional emails or SMS
+- Creating records in external systems where duplicates are harmful
+- Any step that has side effects in systems you don't control
+
+## Pattern: Step ID as idempotency key
+
+Every step has a unique, deterministic `stepId` available via `getStepMetadata()`. Pass this as the idempotency key to external APIs:
+
+```typescript
+import { getStepMetadata } from "workflow";
+
+declare function createCharge(customerId: string, amount: number): Promise<{ id: string }>; // @setup
+declare function sendReceipt(customerId: string, chargeId: string): Promise<void>; // @setup
+
+export async function chargeCustomer(customerId: string, amount: number) {
+  "use workflow";
+
+  const charge = await createCharge(customerId, amount);
+  await sendReceipt(customerId, charge.id);
+
+  return { customerId, chargeId: charge.id, status: "completed" };
+}
+```
+
+### Step function with idempotency key
+
+```typescript
+import { getStepMetadata } from "workflow";
+
+async function createCharge(
+  customerId: string,
+  amount: number
+): Promise<{ id: string }> {
+  "use step";
+
+  const { stepId } = getStepMetadata(); // [!code highlight]
+
+  // Stripe uses the idempotency key to deduplicate requests.
+  // If this step is retried, Stripe returns the same charge.
+  const charge = await fetch("https://api.stripe.com/v1/charges", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+      "Idempotency-Key": stepId, // [!code highlight]
+    },
+    body: new URLSearchParams({
+      amount: String(amount),
+      currency: "usd",
+      customer: customerId,
+    }),
+  });
+
+  if (!charge.ok) {
+    const error = await charge.json();
+    throw new Error(`Charge failed: ${error.message}`);
+  }
+
+  return charge.json();
+}
+
+async function sendReceipt(customerId: string, chargeId: string): Promise<void> {
+  "use step";
+
+  const { stepId } = getStepMetadata();
+
+  await fetch("https://api.example.com/receipts", {
+    method: "POST",
+    headers: { "Idempotency-Key": stepId },
+    body: JSON.stringify({ customerId, chargeId }),
+  });
+}
+```
+
+## Race condition caveats
+
+Workflow does not currently provide distributed locking or true exactly-once delivery across concurrent runs. If two workflow runs could process the same entity concurrently:
+
+- **Rely on the external API's idempotency** (like Stripe's `Idempotency-Key`) rather than checking a local flag.
+- **Don't use check-then-act patterns** like "read a flag, then write if not set" -- another run could read the same flag between your read and write.
+
+If your external API doesn't support idempotency keys natively, consider adding a deduplication layer (e.g., a database unique constraint on the operation ID).
+
+## Tips
+
+- **`stepId` is deterministic.** It's the same value across retries and replays of the same step, making it a reliable idempotency key.
+- **Always provide idempotency keys for non-idempotent external calls.** Even if you think a step won't be retried, cold-start replay will re-execute it.
+- **Handle 409/conflict as success.** If an external API returns "already processed," treat that as a successful result, not an error.
+- **Make your own APIs idempotent** where possible. Accept an idempotency key and return the cached result on duplicate requests.
+
+## 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 full Node.js access
+- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
+- [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run

package/docs/cookbook/common-patterns/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Common Patterns",
+  "defaultOpen": true,
+  "pages": [
+    "sequential-and-parallel",
+    "workflow-composition",
+    "saga",
+    "batching",
+    "rate-limiting",
+    "scheduling",
+    "timeouts",
+    "idempotency",
+    "webhooks"
+  ]
+}