fix: cleaner tests, better error handling, and protocol improvements

[threepointone]

Summary

This PR improves error handling, reduces test noise, and fixes several protocol-level issues across the Agent and MCP subsystems.

Changes

Agent core (src/index.ts)

• this.sql throws SqlError directly — Previously, SQL errors were routed through this.onError(), which logged the error and re-threw it, causing confusing double error logs. Now this.sql wraps failures in SqlError and throws directly. onError is reserved for WebSocket connection errors and unhandled server errors.

• sendIdentityOnConnect warning rewritten — The warning is now informational rather than a deprecation notice. It only fires when using custom routing (where the instance name is not visible in the URL), and tells the developer the exact name being sent. The old warning fired on every agent class regardless of routing.

MCP subsystem (src/mcp/)

• JSON-RPC error responses (rpc.ts) — RPCServerTransport.handle() now returns a proper JSON-RPC -32600 Invalid Request error response for malformed messages instead of throwing an unhandled exception. This aligns with the JSON-RPC 2.0 spec.

• McpAgent protocol message suppression (index.ts) — McpAgent now overrides shouldSendProtocolMessages() to suppress CF_AGENT_IDENTITY, CF_AGENT_STATE, and CF_AGENT_MCP_SERVERS frames on MCP transport connections (detected via the cf-mcp-method header). Regular WebSocket connections to a hybrid McpAgent are unaffected.

• SSE handler MCP header (utils.ts) — Added MCP_HTTP_METHOD_HEADER to the SSE handler's internal WebSocket upgrade request so shouldSendProtocolMessages can detect SSE-originated MCP connections.

• CORS warning removed (utils.ts, worker-transport.ts) — Removed the noisy one-time warning about Authorization in Access-Control-Allow-Headers with wildcard origin. The combination is valid for non-credentialed requests and the warning was unhelpful.

Session provider (src/experimental/memory/session/providers/agent.ts)

• Removed explicit BEGIN TRANSACTION/COMMIT/ROLLBACK — Durable Objects auto-coalesce all synchronous SQL writes within a single I/O gate into one atomic batch, making explicit transactions unnecessary. The old code threw "cannot start a transaction within a transaction" errors because the DO runtime already wraps synchronous writes.

Lifecycle rename

• onStateUpdate → onStateChanged (server-side) — The server-side lifecycle hook has been renamed. The old name still works (backward-compatible shim with a one-time console warning). The client-side onStateUpdate callback in useAgent/AgentClient is unchanged.

Test improvements

• routing.test.ts — All WebSocket upgrade tests now properly accept and close WebSockets after assertions, eliminating 17 "other end of WebSocketPipe was destroyed" log lines on teardown.
• state.test.ts — Updated to use onStateChanged naming throughout.
• rpc.test.ts — Updated to expect JSON-RPC error response instead of thrown exception.
• Test agents (state.ts, readonly.ts) — Renamed onStateUpdate to onStateChanged.

Docs

• docs/client-sdk.md — Fixed server-side method reference from onStateUpdate() to onStateChanged().

Changesets

• Updated security-hardening.md — Rewrote stale deprecation warnings bullet to reflect actual behavior.
• Created fix-sql-error-handling.md — Documents the SqlError direct-throw change.
• Created fix-mcp-protocol-handling.md — Documents JSON-RPC error responses, McpAgent protocol suppression, and CORS warning removal.

Test results

All tests pass:

• routing.test.ts — 25 tests, no WebSocketPipe noise
• state.test.ts — all state management tests with onStateChanged
• rpc.test.ts — JSON-RPC error response handling
• workflow.test.ts — 42 tests (remaining workerd logs are expected miniflare teardown artifacts)
• email-routing.test.ts — 39 tests

[changeset-bot]

🦋 Changeset detected

Latest commit: 0cd330c

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

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

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

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

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

commit: 5b43274