workflow 5.0.0-beta.4 → 5.0.0-beta.5

package/docs/changelog/index.mdx

@@ -12,4 +12,5 @@ Stay up to date with the latest changes to Workflow SDK.
 
 ## 2026
 
-- TBD
+- [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) - March 2026
+- [Serializable AbortController and AbortSignal](/docs/changelog/serializable-abort-controller) — March 12, 2026

package/docs/cookbook/advanced/meta.json

@@ -1,9 +1,4 @@
 {
   "title": "Advanced",
-  "pages": [
-    "child-workflows",
-    "distributed-abort-controller",
-    "serializable-steps",
-    "publishing-libraries"
-  ]
+  "pages": ["child-workflows", "serializable-steps", "publishing-libraries"]
 }

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

@@ -1,70 +1,15 @@
 ---
 title: Agent Cancellation
-description: Cancel a running agent from the outside — either immediately via run.cancel() or gracefully via a stop signal hook.
+description: Cancel a running agent from the outside using AbortSignal — a hook fires the abort, the agent step bails out of the model stream, and the client gets a clean stop notification.
 type: guide
-summary: Two patterns for cancelling a running agent — Hard Cancellation via getRun(runId).cancel() for forced termination, or Stop Signal via a hook + Promise.race for a clean exit with cleanup and final stream notification.
+summary: Cancel a running agent cooperatively with AbortController. A stop hook fires controller.abort(), the signal propagates into the agent step to cancel the model stream, and a data-stopped part is emitted to streaming clients before the workflow returns.
 ---
 
-Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback. Two patterns are available depending on whether you need the agent to exit cleanly or just need the run to stop: **Hard Cancellation** via `getRun(runId).cancel()` for immediate forced termination, or **Stop Signal** via a hook + `Promise.race` for a graceful exit that runs cleanup and notifies streaming clients before returning.
+Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback.
 
-## When to use this
+## Pattern
 
-* **Chat stop buttons** — let users cancel a long-running agent from the browser
-* **Admin cancellation** — stop an agent from a different process or API
-* **Timeout fallback** — combine with `sleep()` to auto-stop after a deadline
-
-## Choosing an approach
-
-Pick the option that matches what your endpoint needs to deliver to the caller:
-
-* **Hard Cancellation** — terminates the run immediately with no opportunity for cleanup or client notification. A single line of code, but the workflow throws `WorkflowRunCancelledError` and any streaming clients see an abrupt connection close.
-* **Stop Signal** — the workflow exits as soon as the hook fires, runs any pending cleanup, emits a final `data-stopped` part to the stream so the client can render cleanly, and returns a real result.
-
-The trade-offs at a glance:
-
-| | Hard Cancellation | Stop Signal |
-| --- | --- | --- |
-| Mechanism | `getRun(runId).cancel()` | Hook + `Promise.race` |
-| Speed to terminate | Immediate | At the next `await` boundary in the workflow |
-| Runs `finally` / cleanup | No | Yes |
-| Final stream notification | No (abrupt close) | Yes (`data-stopped` part) |
-| `run.returnValue` | Throws `WorkflowRunCancelledError` | Returns the workflow's result |
-| Code complexity | One line | Hook + race + signal step |
-| Best for | Stuck or unresponsive runs, forced termination | User-facing stop, admin cancel, timeouts |
-
-## Hard Cancellation
-
-Call `.cancel()` on a run to terminate it immediately:
-
-```typescript lineNumbers
-import { getRun } from "workflow/api";
-
-export async function POST(
-  _request: Request,
-  { params }: { params: Promise<{ runId: string }> }
-) {
-  const { runId } = await params;
-  await getRun(runId).cancel(); // [!code highlight]
-  return Response.json({ success: true });
-}
-```
-
-This is an abrupt termination — the run is stopped mid-step with no opportunity to exit cleanly:
-
-* **No cleanup runs** — `finally` blocks, defer-style step cleanup, and any logic after the current step are all skipped
-* **No final notification to the client** — the writable closes abruptly, so a streaming UI just sees the connection drop with no `data-stopped` part to render a clean ending
-* **`run.returnValue` throws** — anyone awaiting the result receives [`WorkflowRunCancelledError`](/docs/api-reference/workflow-errors/workflow-run-cancelled-error) instead of a meaningful payload
-* **Underlying step keeps running** — same caveat as the Stop Signal pattern below: the model stream or HTTP call inside the current step continues to completion in the background
-
-Hard Cancellation is the appropriate choice when the run is stuck or unresponsive, has exceeded its expected runtime, or you don't need a clean exit. For everything else — chat stop buttons, admin "stop" actions, timeout fallbacks — you typically want the Stop Signal pattern: the agent finishes its current step, emits a final stream part so the client renders a clean ending, and returns a real result.
-
-## Stop Signal
-
-<Callout type="warn">
-**Limitation:** This pattern does not cancel the underlying model stream. The agent step writing to the writable continues running in the background until it completes — tokens generated after the stop signal are still produced (and billed by your model provider). What this pattern *does* is exit the workflow function as soon as the hook fires and emit a `data-stopped` part so the client can stop rendering. For hard cross-process cancellation that signals the inner step to bail out, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
-</Callout>
-
-### Example
+Create an `AbortController` in the workflow and race the agent (passing its signal) against a stop hook. When the hook fires, `controller.abort()` is called — the signal propagates into the agent step and cancels the underlying model stream. Before returning, a `data-stopped` part is written to the stream so any streaming clients can render a clean end state.
 
 ```typescript lineNumbers
 import { DurableAgent } from "@workflow/ai/agent";
@@ -88,7 +33,7 @@ async function analyzeData({ topic }: { topic: string }) {
   return { summary: `Analysis of ${topic}: significant developments found.`, confidence: 0.85 };
 }
 
-async function emitStopSignal(details: { reason?: string }) { // [!code highlight]
+async function emitStopSignal(details: { reason?: string }) {
   "use step";
   const writer = getWritable<UIMessageChunk>().getWriter();
   try {
@@ -102,7 +47,8 @@ export async function stoppableAgent(messages: ModelMessage[]) {
   "use workflow";
 
   const { workflowRunId } = getWorkflowMetadata();
-  const hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
+  const controller = new AbortController(); // [!code highlight]
+  const hook = stopHook.create({ token: `stop:${workflowRunId}` });
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
@@ -121,15 +67,23 @@ export async function stoppableAgent(messages: ModelMessage[]) {
     },
   });
 
-  const result = await Promise.race([ // [!code highlight]
+  const result = await Promise.race([
     agent
-      .stream({ messages, writable: getWritable<UIMessageChunk>(), maxSteps: 15 })
+      .stream({
+        messages,
+        writable: getWritable<UIMessageChunk>(),
+        abortSignal: controller.signal, // [!code highlight]
+        maxSteps: 15,
+      })
       .then((r) => ({ type: "complete" as const, messages: r.messages })),
-    hook.then(({ reason }) => ({ type: "stopped" as const, reason })), // [!code highlight]
+    hook.then(({ reason }) => {
+      controller.abort(reason); // [!code highlight]
+      return { type: "stopped" as const, reason };
+    }),
   ]);
 
   if (result.type === "stopped") {
-    await emitStopSignal({ reason: result.reason }); // [!code highlight]
+    await emitStopSignal({ reason: result.reason });
   }
 
   return result;
@@ -148,7 +102,7 @@ export async function POST(
   const { runId } = await params;
   const { reason } = await request.json();
 
-  await stopHook.resume(`stop:${runId}`, { // [!code highlight]
+  await stopHook.resume(`stop:${runId}`, {
     reason: reason || "User requested stop",
   });
 
@@ -180,13 +134,12 @@ export function StopButton({ runId }: { runId: string }) {
 
 ## How it works
 
-1. A hook is created with token `stop:${workflowRunId}` when the workflow starts
-2. `Promise.race` runs the agent stream and the stop hook concurrently
-3. When the stop API resumes the hook, the race resolves immediately — the workflow exits
-4. Before returning, `emitStopSignal` writes a `data-stopped` part to the stream so the client knows the agent was stopped (not just disconnected)
-5. The client detects `data-stopped` and updates the UI accordingly
-
-This is the same pattern used by the [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller) — race a long-running operation against a hook signal.
+1. An `AbortController` is created at the start of the workflow
+2. A hook is created with token `stop:${workflowRunId}`
+3. `Promise.race` runs the agent stream and the stop hook concurrently
+4. The agent receives `controller.signal` — when aborted, the underlying model stream is cancelled
+5. When the stop API resumes the hook, `controller.abort()` is called — the race resolves and the workflow exits
+6. `emitStopSignal` writes a `data-stopped` part to the stream so the client renders a clean stop state
 
 ## Adapting this
 
@@ -194,12 +147,10 @@ This is the same pattern used by the [Distributed Abort Controller](/cookbook/ad
 * **Audit logging** — include a `reason` field in the stop schema to record who stopped and why
 * **Cross-process** — the hook token is deterministic, so any process can call `stopHook.resume()` with the run ID
 * **Step limits** — combine with `maxSteps` on the agent to cap execution even without manual stop
-* **Hard Cancellation as a fallback** — wire your stop endpoint to fall back to `getRun(runId).cancel()` if the hook resume errors with `not found` / `expired` (for example, the hook was already consumed). This guarantees the run is terminated even when the Stop Signal path is unavailable.
 
 ## Key APIs
 
 * [`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 a stop notification to the client
-* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that gets raced against the stop hook
-* [`getRun()`](/docs/api-reference/workflow-api/get-run) — entry point for Hard Cancellation: `getRun(runId).cancel()`
+* [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream output and the stop notification to the client
+* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that respects the abort signal via its `signal` option

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

@@ -80,7 +80,7 @@ export async function waitForApproval(requestId: string) {
 4. **Throw to fail the workflow** — inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
 
 <Callout type="warn">
-**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. For hard cancellation across processes, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
+**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively — see the [Cancellation Guide](/docs/foundations/cancellation) for patterns.
 </Callout>
 
 ## Adapting to your use case

package/docs/cookbook/index.mdx

@@ -33,6 +33,5 @@ A curated collection of workflow patterns with clean, copy-paste code examples f
 ## Advanced
 
 - [**Child Workflows**](/cookbook/advanced/child-workflows) — Spawn and orchestrate child workflows from a parent
-- [**Distributed Abort Controller**](/cookbook/advanced/distributed-abort-controller) — Build a cross-process abort controller using workflow streams and hooks
 - [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable third-party objects so they cross the workflow boundary
 - [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions

package/docs/deploying/world/postgres-world.mdx

@@ -161,7 +161,9 @@ Prefix for graphile-worker queue job names. Useful when sharing a database betwe
 
 ### `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
 
-Number of concurrent workers polling for jobs. Default: `10`
+Number of concurrent workers polling for jobs. Default: `50`.
+
+This value also bounds how many parent→child workflow polls can be in flight simultaneously. Every `await childRun.returnValue` inside a workflow holds a worker slot until the child run terminates — if you expect recursive or highly-fanned-out parent/child workflows, raise this ceiling above the peak number of concurrent polls. With the default of 50, the included `fibonacciWorkflow` e2e test (fib(6), ~24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.
 
 ### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
 
@@ -179,8 +181,8 @@ import { createWorld } from "@workflow/world-postgres";
 const world = createWorld({
   connectionString: "postgres://user:password@host:5432/database",
   jobPrefix: "myapp_",
-  queueConcurrency: 20,
-  maxPoolSize: 20, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
+  queueConcurrency: 50,
+  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
 });
 ```
 

package/docs/errors/abort-signal-timeout-in-workflow.mdx

@@ -0,0 +1,80 @@
+---
+title: abort-signal-timeout-in-workflow
+description: AbortSignal.timeout() cannot be used inside workflow functions because it relies on real timers which break deterministic replay.
+type: troubleshooting
+summary: Use sleep() with AbortController instead of AbortSignal.timeout() in workflow functions.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/cancellation
+  - /docs/api-reference/workflow/sleep
+  - /docs/errors/timeout-in-workflow
+---
+
+## Error
+
+```
+AbortSignal.timeout() is not supported in workflow functions.
+Use sleep() with an AbortController instead.
+```
+
+## Why This Happens
+
+`AbortSignal.timeout()` creates a signal that aborts after a real-time delay using an internal timer. Workflow functions must be [deterministic](/docs/foundations/workflows-and-steps) to support replay — they run the same code multiple times during the workflow's lifecycle, using the [event log](/docs/how-it-works/event-sourcing) to resume execution to the correct point.
+
+Real-time timers break this determinism because:
+- On the first execution, the timer might fire after 10 seconds
+- On replay, the timer would fire again, but the event log may have already advanced past that point
+- The timer's behavior depends on wall-clock time, which varies between executions
+
+## How to Fix
+
+Use [`sleep()`](/docs/api-reference/workflow/sleep) with an `AbortController` to create a deterministic timeout that cancels in-flight work:
+
+**Before (incorrect):**
+
+{/* @skip-typecheck: intentionally incorrect example */}
+```typescript lineNumbers
+export async function workflow() {
+  "use workflow";
+
+  // This will throw an error
+  const signal = AbortSignal.timeout(10_000); // [!code highlight]
+  const result = await fetchData(signal);
+  return result;
+}
+```
+
+**After (correct):**
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+
+  const controller = new AbortController(); // [!code highlight]
+  void sleep("10s").then(() => controller.abort()); // [!code highlight]
+
+  return await fetchData(controller.signal);
+}
+
+async function fetchData(signal: AbortSignal) {
+  "use step";
+  const response = await fetch("https://api.example.com/data", { signal });
+  return response.json();
+}
+```
+
+The `sleep()` + `AbortController` pattern is the durable equivalent of `AbortSignal.timeout()`. The sleep is recorded in the event log, so it replays deterministically. If `fetchData` finishes within 10 seconds you get the response; if not, the timer fires `controller.abort()`, `fetch` rejects with an `AbortError`, and the step's failure propagates to the workflow as a `FatalError` (no retries — abort is intentional cancellation).
+
+<Callout type="info">
+`AbortSignal.timeout()` works normally inside step functions, since steps have full Node.js runtime access and are not replayed.
+</Callout>
+
+## Related
+
+- [Cancellation](/docs/foundations/cancellation) — Patterns for cancelling in-flight work
+- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) — Durable sleep primitive
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Why workflow functions must be deterministic
+- [`setTimeout` in Workflow](/docs/errors/timeout-in-workflow) — Similar restriction on `setTimeout`