[Docs] Cookbook update for child workflows pattern by karthikscale3 · Pull Request #2100 · vercel/workflow

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 · 2026-05-23T00:24:50Z

Summary

Rewrites the v4 and v5 Child Workflows cookbook to recommend hook-based completion (defineHook + withChildCompletionHook + startAndWait) instead of getRun().status polling loops
Updates Workflow Composition cross-links in v4/v5 to point at the hook resume pattern
Updates the workbench cookbook fixture to spawn a wrapped child that resumes the parent hook in finally

Why

Polling child status in a durable sleep loop works but is slower to wake, holds worker slots when combined with returnValue, and requires extra result-collection steps. The hook resume pattern lets each child signal completion directly and keeps the parent suspended with zero compute until the child finishes.

Test plan

pnpm --filter @workflow/docs-typecheck typecheck
pnpm exec vitest run test/cookbook-common.test.ts -t "child-workflows" in workbench/vitest (local plugin env issue unrelated to this diff)
Review updated cookbook pages at /cookbook/advanced/child-workflows for v4 and v5

Made with Cursor

TooTallNate

Approve — all four asks addressed cleanly

Karthik's fix commit (1c0e18ff0 Fix child-workflows cookbook review feedback) addresses all four items from the previous review:

Ask	Fix
1. Type error in `resumeParentCompletion` (Docs Code Samples CI)	Tightened to discriminated union in both v4 and v5
2. Missing `zod` dep (Vitest Plugin Tests CI)	Added `"zod": "catalog:"` to `workbench/vitest/package.json` + lockfile
3. Unused `resumeHook` import	Removed
4. No changeset	Added empty changeset `.changeset/cookbook-child-workflows-hook-resume.md`

What I verified locally

pnpm install --frozen-lockfile ✓ (lockfile updated cleanly)
pnpm turbo run build --filter '!./workbench/*' ✓
pnpm --filter @workflow/docs-typecheck test:docs ✓ (911/911 tests pass — child-workflows v4 and v5 both clean)
cd workbench/vitest && pnpm test ✓ (34/34 tests pass, including should spawn a child workflow via start() and collect its result)

CI

37 success, 0 failures, 73 in progress — both previously-failing checks now green:
- Docs Code Samples: pass (was failing on lines 33 of both v4 and v5)
- Vitest Plugin Tests: pass (was failing on zod resolution)

Branch hygiene

The ~10 merge commits from main are still there — they'll be squashed away on merge so it's not a blocker, but a rebase would clean up the working history.

Nice work on the pattern. The hook resume + withChildCompletionHook + startAndWait shape is clean, and the prose explanation of why hooks beat polling (zero compute, immediate wake, typed payloads, no worker-pool pressure) is well-grounded with the Eager Processing link.

Approving.

…workflows-hook-completion

Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T23:03:15Z

No backport to stable for c58cae6 (AI decision).

All meaningful changes target docs cookbook pages (docs/content/docs/v4/cookbook/..., docs/content/docs/v5/cookbook/..., docs/lib/cookbook-tree.ts) and a workbench/vitest fixture (workbench/vitest/workflows/cookbook/child-workflows.ts) that do not exist on stable — verified via git ls-tree origin/stable. The only file present on stable is workbench/vitest/package.json, where the sole change is adding a zod dependency that solely supports the new fixture which isn't on stable, so the backport would be meaningless on its own.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c58cae66122bed2c0dddfe7cf793def18c08b708

…anch - ai-sdk (#2099): tools inside the per-turn step are not individually durable — remove the misleading "use step" directives and durability claims, rewrite when-to-use, add the pitfall and corrected streamText-vs-DurableAgent comparison - child-workflows (#2100): replace spawn-and-poll (getRun().status loop) with startAndWait() + withChildCompletionHook() hook resume - durable-agent + agent-cancellation + human-in-the-loop (#2285): DurableAgent is deprecated in v5 — add warn callout and notes pointing at AI SDK v7's WorkflowAgent - ai-sdk: add deployment-pinning versioning callout (#2010)

karthikscale3 added 30 commits January 27, 2026 10:51

Merge branch 'main' of github.com:vercel/workflow
ad8b7f1

Merge branch 'main' of github.com:vercel/workflow
e0cb61b

Merge branch 'main' of github.com:vercel/workflow
051cadc

Merge branch 'main' of github.com:vercel/workflow
af8ac1f

Merge branch 'main' of github.com:vercel/workflow
e68e7d2

Merge branch 'main' of github.com:vercel/workflow
8305e5b

Merge branch 'main' of github.com:vercel/workflow
f3da688

Merge branch 'main' of github.com:vercel/workflow
f8ee413

Merge branch 'main' of github.com:vercel/workflow
589cbd7

Merge branch 'main' of github.com:vercel/workflow
e979fdf

Merge branch 'main' of github.com:vercel/workflow
d4baed2

Merge branch 'main' of github.com:vercel/workflow
53503a4

Merge branch 'main' of github.com:vercel/workflow
d51e2e4

Merge branch 'main' of github.com:vercel/workflow
5123088

Merge branch 'main' of github.com:vercel/workflow
dd1a307

Merge branch 'main' of github.com:vercel/workflow
00bcfcd

Merge branch 'main' of github.com:vercel/workflow
f6a157b

Merge branch 'main' of github.com:vercel/workflow
816f35b

Merge branch 'main' of github.com:vercel/workflow
2b87dce

Merge branch 'main' of github.com:vercel/workflow
146de28

Merge branch 'main' of github.com:vercel/workflow
0ef6455

Merge branch 'main' of github.com:vercel/workflow
2d8c690

Merge branch 'main' of github.com:vercel/workflow
3513471

Merge branch 'main' of github.com:vercel/workflow
0f5d29e

Merge branch 'main' of github.com:vercel/workflow
c76001e

Merge branch 'main' of github.com:vercel/workflow
f97184f

Merge branch 'main' of github.com:vercel/workflow
f71c531

Merge branch 'main' of github.com:vercel/workflow
530e598

Merge branch 'main' of github.com:vercel/workflow
ea38511

Merge branch 'main' of github.com:vercel/workflow
19b1a3f

vercelBotdeployed to Preview – workbench-nuxt-workflow May 23, 2026 00:42 View deployment

vercelBotdeployed to Preview – example-workflow May 23, 2026 00:42 View deployment

vercelBotdeployed to Preview – example-nextjs-workflow-webpack May 23, 2026 00:42 View deployment

vercelBotdeployed to Preview – example-nextjs-workflow-turbopack May 23, 2026 00:42 View deployment

vercelBotdeployed to Preview – workflow-docs May 23, 2026 00:42 View deployment

karthikscale3 requested a review from TooTallNate May 23, 2026 00:42

vercelBotdeployed to Preview – workflow-swc-playground May 23, 2026 00:44 View deployment

TooTallNate approved these changes May 23, 2026
View reviewed changes

karthikscale3and others added 2 commits May 25, 2026 10:03

Merge branch 'main' of github.com:vercel/workflow into karthik/child-…
3decc4a
…workflows-hook-completion

docs(cookbook): trim child-workflows hook resume guide
b72c208
Remove redundant polling comparison copy, the getRun() alternative section, and v5-only start() tips to keep the cookbook focused on the hook pattern. Co-authored-by: Cursor <cursoragent@cursor.com>

vercelBotdeployed to Preview – workflow-web May 25, 2026 17:12 View deployment

vercelBotdeployed to Preview – workflow-tarballs May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-fastify-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-express-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-hono-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-nitro-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-vite-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-sveltekit-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-astro-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – example-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-tanstack-start-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – workbench-nuxt-workflow May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – example-nextjs-workflow-turbopack May 25, 2026 17:13 View deployment

vercelBotdeployed to Preview – example-nextjs-workflow-webpack May 25, 2026 17:14 View deployment

vercelBotdeployed to Preview – workflow-docs May 25, 2026 17:14 View deployment

vercelBotdeployed to Preview – workflow-swc-playground May 25, 2026 17:15 View deployment

karthikscale3 merged commit c58cae6 into mainMay 25, 2026
229 of 252 checks passed

karthikscale3 deleted the karthik/child-workflows-hook-completion branch May 25, 2026 23:02