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

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

@@ -7,165 +7,141 @@ summary: Use defineHook with the tool call ID to suspend an agent for human appr
 
 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.
 
-## Pattern
-
-Create a typed hook using `defineHook()`. When the agent calls the approval tool, the tool creates a hook instance using the tool call ID as the token, then awaits it. The UI renders approval controls, and an API route resumes the hook with the decision.
-
-### Simplified
+## When to use this
 
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { defineHook, sleep, getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-export const bookingApprovalHook = defineHook({
-  schema: z.object({
-    approved: z.boolean(),
-    comment: z.string().optional(),
-  }),
-});
-
-declare function confirmBooking(args: { flightId: string; passenger: string }): Promise<{ confirmationId: string }>; // @setup
-
-// This tool runs at the workflow level (no "use step") because hooks are workflow primitives
-async function requestBookingApproval(
-  { flightId, passenger, price }: { flightId: string; passenger: string; price: number },
-  { toolCallId }: { toolCallId: string }
-) {
-  const hook = bookingApprovalHook.create({ token: toolCallId }); // [!code highlight]
-
-  const result = await Promise.race([ // [!code highlight]
-    hook.then((payload) => ({ type: "decision" as const, ...payload })),
-    sleep("24h").then(() => ({ type: "timeout" as const, approved: false })),
-  ]);
+- 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
 
-  if (result.type === "timeout") return "Booking request expired after 24 hours.";
-  if (!result.approved) return `Booking rejected: ${result.comment || "No reason given"}`;
-
-  const booking = await confirmBooking({ flightId, passenger });
-  return `Booked! Confirmation: ${booking.confirmationId}`;
-}
-
-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: {
-      requestBookingApproval: {
-        description: "Request human approval before booking a flight",
-        inputSchema: z.object({
-          flightId: z.string(),
-          passenger: z.string(),
-          price: z.number(),
-        }),
-        execute: requestBookingApproval,
-      },
-    },
-  });
+## Pattern
 
-  await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(),
-  });
-}
-```
+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.
 
-### Full Implementation
+### Workflow
 
-```typescript lineNumbers
+```typescript
 import { DurableAgent } from "@workflow/ai/agent";
 import { defineHook, sleep, getWritable } from "workflow";
 import { z } from "zod";
 import type { ModelMessage, UIMessageChunk } from "ai";
 
-// Define the approval hook with schema validation
-export const bookingApprovalHook = defineHook({
+// 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(),
   }),
 });
 
-// Step: Search for flights (full Node.js access, automatic retries)
-async function searchFlights({
-  from,
-  to,
-  date,
-}: {
+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();
+}
 
-  // Your real flight search API call here
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  return {
-    flights: [
-      { id: "FL-100", airline: "Example Air", price: 299, from, to, date },
-      { id: "FL-200", airline: "Demo Airlines", price: 349, from, to, date },
-    ],
-  };
+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();
 }
 
-// Step: Confirm the booking after approval
-async function confirmBooking({
-  flightId,
-  passenger,
-}: {
+// 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();
+  }
+}
 
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  return { confirmationId: `CONF-${flightId}-${Date.now().toString(36)}` };
+// 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();
+  }
 }
 
-// Workflow-level tool: hooks must be created in workflow context, not inside steps
+// No "use step" — hooks are workflow-level primitives
 async function requestBookingApproval(
-  {
-    flightId,
-    passenger,
-    price,
-  }: { flightId: string; passenger: string; price: number },
+  { flightId, passenger, price }: {
+    flightId: string;
+    passenger: string;
+    price: number;
+  },
   { toolCallId }: { toolCallId: string }
 ) {
-  // No "use step" — hooks are workflow-level primitives
+  // 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 }); // [!code highlight]
+  const hook = bookingApprovalHook.create({ token: toolCallId });
 
-  // Race: human approval vs. 24-hour timeout
-  const result = await Promise.race([ // [!code highlight]
+  // 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 })),
+    sleep("24h").then(() => ({ type: "timeout" as const, approved: false as const })),
   ]);
 
   if (result.type === "timeout") {
-    return "Booking request expired after 24 hours.";
+    const msg = "Booking request expired.";
+    await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+    return msg;
   }
-
   if (!result.approved) {
-    return `Booking rejected: ${result.comment || "No reason given"}`;
+    const msg = `Rejected: ${result.comment || "No reason given"}`;
+    await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+    return msg;
   }
 
-  // Approved — proceed with booking
   const booking = await confirmBooking({ flightId, passenger });
-  return `Flight ${flightId} booked for ${passenger}. Confirmation: ${booking.confirmationId}`;
+  const msg = `Booked! Confirmation: ${booking.confirmationId}`;
+  await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+  return msg;
 }
 
 export async function bookingAgent(messages: ModelMessage[]) {
   "use workflow";
 
-  const writable = getWritable<UIMessageChunk>();
-
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    instructions:
-      "You are a flight booking assistant. Search for flights, then request approval before booking.",
+    instructions: "You help book flights. Always request approval before booking.",
     tools: {
       searchFlights: {
         description: "Search for available flights",
@@ -188,86 +164,86 @@ export async function bookingAgent(messages: ModelMessage[]) {
     },
   });
 
-  await agent.stream({ messages, writable }); // [!code highlight]
+  await agent.stream({
+    messages,
+    writable: getWritable<UIMessageChunk>(),
+  });
 }
 ```
 
-### API Route for Approvals
+### Approval API route
+
+The approval route imports the hook definition and calls `.resume()` with the tool call ID as the token:
 
-```typescript lineNumbers
-import { bookingApprovalHook } from "@/workflows/booking-agent";
+```typescript
+import { bookingApprovalHook } from "@/app/workflows/booking-agent";
 
-export async function POST(request: Request) {
-  const { toolCallId, approved, comment } = await request.json();
+export async function POST(req: Request) {
+  const { toolCallId, approved, comment } = await req.json();
 
-  // Schema validation happens automatically via defineHook
   await bookingApprovalHook.resume(toolCallId, { approved, comment }); // [!code highlight]
 
   return Response.json({ success: true });
 }
 ```
 
-### Approval Component
-
-```tsx lineNumbers
-"use client";
+### 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
+})}
+```
 
-import { useState } from "react";
+## How it works
 
-export function BookingApproval({
-  toolCallId,
-  input,
-  output,
-}: {
-  toolCallId: string;
-  input?: { flightId: string; passenger: string; price: number };
-  output?: string;
-}) {
-  const [comment, setComment] = useState("");
-  const [isSubmitting, setIsSubmitting] = useState(false);
+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.
 
-  if (output) {
-    return <p className="text-sm text-muted-foreground">{output}</p>;
-  }
+## Adapting to your use case
 
-  const handleSubmit = async (approved: boolean) => {
-    setIsSubmitting(true);
-    await fetch("/api/hooks/approval", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ toolCallId, approved, comment }),
-    });
-    setIsSubmitting(false);
-  };
-
-  return (
-    <div className="border rounded-lg p-4 space-y-3">
-      {input && (
-        <div className="text-sm space-y-1">
-          <div>Flight: {input.flightId}</div>
-          <div>Passenger: {input.passenger}</div>
-          <div>Price: ${input.price}</div>
-        </div>
-      )}
-      <textarea
-        value={comment}
-        onChange={(e) => setComment(e.target.value)}
-        placeholder="Add a comment (optional)..."
-        className="w-full border rounded p-2 text-sm"
-        rows={2}
-      />
-      <div className="flex gap-2">
-        <button type="button" onClick={() => handleSubmit(true)} disabled={isSubmitting}>
-          Approve
-        </button>
-        <button type="button" onClick={() => handleSubmit(false)} disabled={isSubmitting}>
-          Reject
-        </button>
-      </div>
-    </div>
-  );
-}
-```
+- **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
 
@@ -275,4 +251,5 @@ export function BookingApproval({
 - [`"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

@@ -1,10 +1,4 @@
 {
   "title": "Agent Patterns",
-  "pages": [
-    "durable-agent",
-    "tool-streaming",
-    "human-in-the-loop",
-    "tool-orchestration",
-    "stop-workflow"
-  ]
+  "pages": ["durable-agent", "human-in-the-loop", "agent-cancellation"]
 }

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

@@ -9,167 +9,93 @@ Use batching when you need to process a large list of items in parallel while co
 
 ## When to use this
 
-- Processing hundreds or thousands of items (orders, images, records)
+- 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 items into chunks and processes each chunk with `Promise.allSettled()`. A `sleep()` between chunks prevents overloading downstream services.
+The workflow splits records into chunks, processes each chunk concurrently, tracks results per batch, and returns a final tally.
 
 ```typescript
 import { sleep } from "workflow";
 
-declare function processItem(item: string): Promise<{ item: string; ok: boolean }>; // @setup
+type Record = { name: string; email: string; role: string };
+
+declare function processRecord(record: Record): Promise<string>; // @setup
 
-export async function processBatch(items: string[], batchSize: number = 5) {
+export async function batchImport(records: Record[], batchSize: number) {
   "use workflow";
 
-  const results = [];
+  let totalSucceeded = 0;
+  let totalFailed = 0;
 
-  for (let i = 0; i < items.length; i += batchSize) {
-    const batch = items.slice(i, i + batchSize);
+  for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
 
-    // Run batch in parallel -- failures are isolated
+    // Run batch in parallel — failures are isolated per record
     const outcomes = await Promise.allSettled( // [!code highlight]
-      batch.map((item) => processItem(item))
+      batch.map((record) => processRecord(record))
     );
 
     for (let j = 0; j < outcomes.length; j++) {
-      const outcome = outcomes[j];
-      results.push(
-        outcome.status === "fulfilled"
-          ? outcome.value
-          : { item: batch[j], ok: false, error: String(outcome.reason) }
-      );
+      if (outcomes[j].status === "fulfilled") {
+        totalSucceeded++;
+      } else {
+        totalFailed++;
+      }
     }
 
-    // Pace between batches to avoid overload
-    if (i + batchSize < items.length) {
+    // Pace between batches to avoid overloading downstream
+    if (i + batchSize < records.length) {
       await sleep("1s"); // [!code highlight]
     }
   }
 
-  const succeeded = results.filter((r) => r.ok).length;
-  return { total: results.length, succeeded, failed: results.length - succeeded };
+  return { total: records.length, succeeded: totalSucceeded, failed: totalFailed };
 }
 ```
 
 ### Step function
 
-Each item is processed in its own step, giving it full Node.js access and automatic retries.
+Each record is processed in its own step with full Node.js access and automatic retries.
 
 ```typescript
-async function processItem(item: string): Promise<{ item: string; ok: boolean }> {
+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/process`, {
+  const res = await fetch(`https://api.example.com/contacts`, {
     method: "POST",
-    body: JSON.stringify({ item }),
+    body: JSON.stringify(record),
   });
-  if (!res.ok) throw new Error(`Failed to process ${item}`);
-  return { item, ok: true };
+  if (!res.ok) throw new Error(`Failed to import ${record.email}`);
+  const { id } = await res.json();
+  return id;
 }
 ```
 
-## Variations
-
-### Scatter-gather
-
-When you need results from multiple independent sources before continuing, fan out in parallel and collect all results:
-
-```typescript
-export async function scatterGather(query: string) {
-  "use workflow";
-
-  const [web, database, cache] = await Promise.allSettled([ // [!code highlight]
-    searchWeb(query),
-    searchDatabase(query),
-    searchCache(query),
-  ]);
-
-  return {
-    web: web.status === "fulfilled" ? web.value : null,
-    database: database.status === "fulfilled" ? database.value : null,
-    cache: cache.status === "fulfilled" ? cache.value : null,
-  };
-}
-
-async function searchWeb(query: string): Promise<string[]> {
-  "use step";
-  // Full Node.js access -- call external APIs
-  const res = await fetch(`https://search.example.com?q=${query}`);
-  return res.json();
-}
-
-async function searchDatabase(query: string): Promise<string[]> {
-  "use step";
-  // Query your database
-  return [`db-result-for-${query}`];
-}
-
-async function searchCache(query: string): Promise<string[]> {
-  "use step";
-  return [`cached-result-for-${query}`];
-}
-```
-
-## In-step concurrency control
-
-When you need to process many items against a rate-limited API but want the entire operation to be a single atomic step, batch the work inside the step itself. This keeps the event log clean (one step instead of hundreds) while still controlling concurrency.
-
-```typescript
-async function processConcurrently<T>(
-  items: string[],
-  processor: (item: string) => Promise<T>,
-  maxConcurrent: number = 5,
-): Promise<T[]> {
-  "use step";
-  const results: T[] = [];
-
-  for (let i = 0; i < items.length; i += maxConcurrent) {
-    const batch = items.slice(i, i + maxConcurrent);
-    const batchResults = await Promise.all(batch.map(processor)); // [!code highlight]
-    results.push(...batchResults);
-  }
-
-  return results;
-}
-```
-
-Usage in a workflow:
-
-```typescript
-declare function processConcurrently<T>(items: string[], processor: (item: string) => Promise<T>, maxConcurrent?: number): Promise<T[]>; // @setup
-
-export async function moderateImages(imageUrls: string[]) {
-  "use workflow";
-
-  const results = await processConcurrently(
-    imageUrls,
-    async (url) => {
-      const res = await fetch("https://api.example.com/moderate", {
-        method: "POST",
-        body: JSON.stringify({ url }),
-      });
-      return res.json();
-    },
-    3, // max 3 concurrent API calls
-  );
-
-  return { total: results.length, results };
-}
-```
+## Adapting to your use case
 
-**When to use in-step batching vs workflow-level batching:**
-- **Workflow-level** (the pattern above): Each item is its own step with independent retries and failure isolation. Use when items are independent and individual failures should be retried.
-- **In-step**: All items are processed in one step. Use when the items are tightly coupled (e.g., moderating all thumbnails for a single video) or when you want to minimize step overhead for large item counts.
+- 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 `processItem` call is an independent step.** If one fails, it retries up to 3 times without affecting other items in the batch.
+- **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
 

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

@@ -2,14 +2,14 @@
   "title": "Common Patterns",
   "defaultOpen": true,
   "pages": [
+    "sequential-and-parallel",
+    "workflow-composition",
     "saga",
     "batching",
     "rate-limiting",
-    "fan-out",
     "scheduling",
+    "timeouts",
     "idempotency",
-    "webhooks",
-    "content-router",
-    "child-workflows"
+    "webhooks"
   ]
 }