fix(agents): one root call per sub-agent broadcast, none without recipients (#2252)

[threepointone]

Fixes #2252.

Problem

Outside the client frame that started the work, every facet broadcast resolved the root through getAgentByName() before calling _cf_broadcastToSubAgent. That resolution is an __unsafe_ensureInitialized round trip, so a streamed answer cost two billed root requests per chunk, and they ran one after the other.

Fix

• The root endpoints that facets call now start the root's lifecycle themselves, so facets use a plain stub. A root that was evicted still runs onStart() before serving the call. That is the case the extra ensureInitialized call was guarding.
• A facet skips the root entirely when its hydrated connection mirror shows no connection outside without. Until the mirror is hydrated, broadcasts go to the root as before, so an unknown mirror never drops a message.

The issue also suggested batching broadcasts. I left that out: with at most one call per chunk, and none when nobody is listening, batching would change delivery timing and need a new RPC shape for a smaller gain.

Tests

sub-agent-rpc-bridge.test.ts counts root calls:

• No root call when the sub-agent has no connections, or when every connection is excluded.
• Exactly one root call per broadcast to a connected client.
• A root-held client is still reached after the sub-agent restarts, which is the case where the mirror is not hydrated yet.
• An evicted root runs onStart() before it serves a sub-agent call.

[changeset-bot]

🦋 Changeset detected

Latest commit: 52853b1

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

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
@cloudflare/agent-think	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

[devin-ai-integration]

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 2 potential issues.

[pkg-pr-new]

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 52853b1

[agent-think]

✅ agents import sizes: no significant changes (59cad8a5 → 52853b12, workflow run)

[devin-ai-integration]

Devin Review found 1 new potential issue.