fix(agents): close rejected sub-agent WebSockets instead of failing the handshake (#2118)

[threepointone]

Fixes #2118.

Problem

When onBeforeSubAgent rejected a WebSocket upgrade, the handshake failed with an HTTP status. Browsers hide that status from script, so clients saw a generic close and reconnected forever. Separately, useAgent and AgentClient never reported that reconnection had ended, even when it had: a terminal close code, a shouldReconnectOnClose that declined, or exhausted maxRetries.

Fix

Server:

• A rejected upgrade is now accepted and immediately closed. A 4xx status maps to close code 4000 + status, which is terminal. Anything else maps to 1011, which is retryable. The reason is Sub-agent connection rejected (<status>).
• Nested hops use the same mapping; before, they closed with 1008 whatever the status was.
• A rejection response that already carries a webSocket is passed through untouched.

Client:

• createCloseClassifier decides, in shouldReconnectOnClose, whether this close ends reconnection. That is the point where partysocket still exposes enough state to know. When reconnection ends, useAgent and AgentClient set connectionError and reject pending calls.
• An explicit close() still reports nothing.

Edge cases:

• partysocket calls shouldReconnectOnClose even after an explicit close(), and before it increments its retry count. The classifier reads shouldReconnect === false to tell an explicit close apart.
• partysocket leaves shouldReconnect true when maxRetries runs out. The classifier compares the retry count with maxRetries itself.

Tests

• Routing tests cover close codes 4404, 4401 and 1011, and a nested hop that expects 4403.
• React tests cover a rejected sub-agent, maxRetries exhaustion, a shouldReconnectOnClose that declines, and an explicit close() that produces no error.

Docs: docs/agents/sub-agents.md has a close-code table.

Depends on #2400: before that fix, the nested rejection case hit the depth-limit bug and closed with 1011.

[changeset-bot]

🦋 Changeset detected

Latest commit: 64155b9

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

[agent-think]

🟢 agents import sizes: 1 entry point changed, no growth

	Entry point	Exports	Largest gzip change	Size now
🆕	agents/client	1 new	—	16.4 KiB

Changed exports (1)

	Import	Gzip change	Size now
🆕	agents/client#createCloseClassifier	—	16.4 KiB

How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

_{Compared 3ffc90a3 → 64155b9d · workflow run · reported by agent-think[bot]}

[devin-ai-integration]

Devin Review found 1 potential issue.

[pkg-pr-new]

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 64155b9