feat: per-connection protocol message control

[threepointone]

Closes #881

Summary

• Add shouldSendProtocolMessages(connection, ctx) — overridable hook on Agent (default: true). Called once during onConnect to decide whether protocol text frames should be sent to this connection.
• Add isConnectionProtocolEnabled(connection) — predicate to check a connection's protocol status at any time, including after hibernation.
• When shouldSendProtocolMessages returns false, the connection receives no CF_AGENT_IDENTITY, CF_AGENT_STATE, or CF_AGENT_MCP_SERVERS messages — neither on connect nor via subsequent broadcasts. RPC and regular messaging still work normally.
• Also fixes a latent bug where isConnectionReadonly would return incorrect results after Durable Object hibernation.

Design decisions

Why a per-connection hook, not static options?

The original issue identified two needs: (1) per-connection control for DOs that serve mixed connection types (e.g. MQTT binary clients alongside web monitoring clients), and (2) agent-level feature opt-out. Per @threepointone's comment, option (2) is just the degenerate case of (1) — a hook that always returns false is effectively agent-level. So we only need the hook.

Why store the flag in connection state?

Same approach as _cf_readonly. The flag is persisted in the WebSocket attachment via connection.setState, which means it survives Durable Object hibernation. This is critical — @genmon reported that PR #892 leaked cf_agent_mcp_servers messages after hibernation wake because the in-memory state was lost.

How hibernation is handled

The core insight: both isConnectionReadonly and isConnectionProtocolEnabled call _ensureConnectionWrapped(connection) before reading the flag. This method is idempotent — if the _rawStateAccessors WeakMap already has the connection, it returns immediately. After hibernation, the WeakMap is empty, but the connection's state getter still reads from the persisted WebSocket attachment. _ensureConnectionWrapped re-captures that getter as getRaw, sets up the filtering overrides, and the predicate then reads the flag correctly. No separate fallback path needed.

This is cleaner than PRs #892/#893, which added a separate code path in the predicate that read connection.state directly when the WeakMap was empty — fragile because it depended on _ensureConnectionWrapped not having run yet.

Generalized internal key handling

Rather than hardcoding _cf_readonly in _ensureConnectionWrapped (as the current code does), the connection state wrapping now uses CF_INTERNAL_KEYS (a ReadonlySet) with module-level helpers (rawHasInternalKeys, stripInternalKeys, extractInternalFlags). Adding a future internal flag means adding one entry to the set — the wrapping logic handles it automatically.

_broadcastProtocol for filtered broadcasts

State broadcasts (_setStateInternal) and MCP broadcasts (broadcastMcpServers) now go through _broadcastProtocol, which builds an exclusion list of no-protocol connections and delegates to this.broadcast(). This keeps the filtering in one place.

Usage example

class MyAgent extends Agent {
  shouldSendProtocolMessages(connection, ctx) {
    // Suppress protocol messages for MQTT binary clients
    const url = new URL(ctx.request.url);
    return url.searchParams.get("protocol") !== "false";
    // Or check WebSocket subprotocol:
    // return ctx.request.headers.get("Sec-WebSocket-Protocol") !== "mqtt";
  }
}

Notes for reviewers

1. isConnectionReadonly bug fix — The existing isConnectionReadonly had a latent hibernation bug: after DO hibernation, the _rawStateAccessors WeakMap is empty, so the method returned false for connections that were actually readonly. The shouldConnectionBeReadonly hook only runs during onConnect, which does NOT fire on hibernation wake. My fix (calling _ensureConnectionWrapped in the predicate) fixes this for both flags. This is a behavioral change to the readonly feature, but strictly a bug fix.

2. No dynamic toggle — Unlike setConnectionReadonly(connection, bool) which can be toggled at runtime, _setConnectionNoProtocol is private and only called during onConnect. This is intentional per the issue thread: "We don't need it to be able to be dynamically set." Protocol status is evaluated once on connect and persisted.

3. All protocol message sites covered — I audited every MessageType.CF_AGENT_* send site in index.ts. The three protocol types (IDENTITY, STATE, MCP_SERVERS) are filtered in onConnect (conditional block) and in broadcasts (_broadcastProtocol). CF_AGENT_STATE_ERROR is correctly NOT filtered — it's a direct reply to a specific connection that sent a bad state update, not an unsolicited broadcast.

4. 16 tests covering: hook behavior (protocol sent / not sent on connect), predicate correctness, RPC on no-protocol connections, state broadcast filtering, mixed connections, reconnection re-evaluation, connection.state wrapping (flag hidden, preserved across setState value and callback forms), and readonly + no-protocol combination on the same connection.

Test plan

• npm run build passes
• npm run check passes (sherif, exports, oxfmt, oxlint, typecheck across 42 projects)
• npm run test — all 529+ tests pass (including 16 new protocol-messages tests)
• Existing readonly tests still pass (generalized wrapping is backward compatible)

Made with Cursor

[changeset-bot]

🦋 Changeset detected

Latest commit: e7c7241

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

This PR includes changesets to release 1 package

Name	Type
agents	Minor

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

npm i https://pkg.pr.new/cloudflare/agents@920

commit: e7c7241

[threepointone]

/bonk review this pr

[ask-bonk]

I read all 7 changed files in the PR (the core index.ts diff, test agent, test file, changeset, worker registration, wrangler config, and agent index exports), then grep-searched for all references to the new APIs across the source tree to verify completeness of the implementation and audit all call sites, before writing the review summary.

github run