Fix sub-agent workflow origins

[threepointone]

Summary

Fixes workflows started from sub-agent facets by preserving the exact originating Agent path and routing workflow callbacks/RPC back to that facet instead of assuming a top-level Agent binding.

This addresses the failure mode from #1359 where runWorkflow() could not detect a binding for sub-agents and gives facet-started workflows the same tracking, callback, and Agent RPC semantics as top-level workflows.

What changed

• Adds a versioned AgentWorkflowOrigin internal payload for workflow starts:
  • top-level Agents use { kind: "agent", binding, name }
  • sub-agent facets use { kind: "facet", rootBinding, path }
• Updates Agent.runWorkflow() to preserve root binding + selfPath for facet callers.
• Adds path-based internal RPC dispatch via _cf_invokeAgentPath() so AgentWorkflow.agent, progress, completion, error, event, and state callbacks land on the originating facet.
• Makes facet workflow AgentWorkflow.agent explicitly RPC-only and throws a clear error for .fetch().
• Registers sub-agents before facet startup so workflows started in onStart() can route callbacks immediately, with rollback if initialization fails.
• Makes broadcastToClients() await the underlying Agent RPC.
• Adds regression coverage for direct facets, nested facets, onStart() workflow starts, approval/rejection, errors, durable events, state updates, and facet-local tracking.
• Updates SDK docs, examples, README, and design notes for sub-agent workflow behavior.

Test plan

• npm test -w agents -- src/tests/workflow-sub-agent.test.ts
• npm run typecheck
• npx oxfmt --check packages/agents/src/workflows.ts packages/agents/src/tests/test-workflow.ts packages/agents/src/tests/agents/workflow.ts packages/agents/src/tests/worker.ts packages/agents/src/tests/wrangler.jsonc packages/agents/src/tests/workflow-sub-agent.test.ts docs/workflows.md docs/sub-agents.md docs/long-running-agents.md docs/human-in-the-loop.md

Note: the targeted workflow suite logs expected Workflows runtime exceptions for intentionally thrown/rejected workflow cases, while the suite itself passes.

Made with Cursor

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 975480c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1430

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1430

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1430

hono-agents

npm i https://pkg.pr.new/hono-agents@1430

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1430

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1430

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1430

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1430

commit: 975480c

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.