cloudflare/agents agents@0.4.0

on GitHub

Minor Changes

• #848 a167344 Thanks @mattzcarey! - Upgrade MCP SDK to 1.26.0 to prevent cross-client response leakage. Updated examples for stateless MCP Servers create new McpServer instance per request instead of sharing a single instance. A guard is added in this version of the MCP SDK which will prevent connection to a Server instance that has already been connected to a transport. Developers will need to modify their code if they declare their McpServer instance as a global variable.

• #298 27f4e3e Thanks @jaredhanson! - Add createMcpOAuthProvider method to the Agent class, allowing subclasses to override the default OAuth provider used when connecting to MCP servers. This enables custom authentication strategies such as pre-registered client credentials or mTLS, beyond the built-in dynamic client registration.

• #610 f59f305 Thanks @threepointone! - Deprecate onStateUpdate server-side hook in favor of onStateChanged

  • onStateChanged is a drop-in rename of onStateUpdate (same signature, same behavior)
  • onStateUpdate still works but emits a one-time console warning per class
  • Throws if a class overrides both hooks simultaneously
  • validateStateChange rejections now propagate a CF_AGENT_STATE_ERROR message back to the client

• #871 27f8f75 Thanks @threepointone! - Migrate x402 MCP integration from legacy x402 package to @x402/core and @x402/evm v2

  Breaking changes for x402 users:

  • Peer dependencies changed: replace x402 with @x402/core and @x402/evm
  • PaymentRequirements type now uses v2 fields (e.g. amount instead of maxAmountRequired)
  • X402ClientConfig.account type changed from viem.Account to ClientEvmSigner (structurally compatible with privateKeyToAccount())

  Migration guide:

  1. Update dependencies:

     npm uninstall x402
     npm install @x402/core @x402/evm

  2. Update network identifiers — both legacy names and CAIP-2 format are accepted:

     // Before
     {
       network: "base-sepolia";
     }
     // After (either works)
     {
       network: "base-sepolia";
     } // legacy name, auto-converted
     {
       network: "eip155:84532";
     } // CAIP-2 format (preferred)

  3. If you access PaymentRequirements fields in callbacks, update to v2 field names (see @x402/core docs).

  4. The version field on X402Config and X402ClientConfig is now deprecated and ignored — the protocol version is determined automatically.

  Other changes:

  • X402ClientConfig.network is now optional — the client auto-selects from available payment requirements
  • Server-side lazy initialization: facilitator connection is deferred until the first paid tool invocation
  • Payment tokens support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) HTTP headers
  • Added normalizeNetwork export for converting legacy network names to CAIP-2 format
  • Re-exports PaymentRequirements, PaymentRequired, Network, FacilitatorConfig, and ClientEvmSigner from agents/x402

Patch Changes

• #610 f59f305 Thanks @threepointone! - Add readonly connections: restrict WebSocket clients from modifying agent state

  • New hooks: shouldConnectionBeReadonly, setConnectionReadonly, isConnectionReadonly
  • Blocks both client-side setState() and mutating @callable() methods for readonly connections
  • Readonly flag stored in a namespaced connection attachment (_cf_readonly), surviving hibernation without extra SQL
  • Connection state wrapping hides the internal flag from user code and preserves it across connection.setState() calls
  • Client-side onStateUpdateError callback for handling rejected state updates

• #855 271a3cf Thanks @threepointone! - Fix useAgent and AgentClient crashing when using basePath routing.

• #868 b3e2dc1 Thanks @threepointone! - Fix MCP OAuth callback URL leaking instance name

  Add callbackPath option to addMcpServer to prevent instance name leakage in MCP OAuth callback URLs. When sendIdentityOnConnect is false, callbackPath is now required — the default callback URL would expose the instance name, undermining the security intent. Also fixes callback request detection to match via the state parameter instead of a loose /callback URL substring check, enabling custom callback paths.

• #872 de71f9e Thanks @threepointone! - update dependencies

• 8893fbe Thanks @threepointone! - partykit releases

  partyserver

  0.1.3 (Feb 8, 2026)

  • #319 — Add configurable: true to the state, setState, serializeAttachment, and deserializeAttachment property descriptors on connection objects. This allows downstream consumers (like the Cloudflare Agents SDK) to redefine these properties with Object.defineProperty for namespacing or wrapping internal state storage. Default behavior is unchanged.

  0.1.4 (Feb 9, 2026)

  • #320 — Add CORS support to routePartykitRequest. Pass cors: true for permissive defaults or cors: { ...headers } for custom CORS headers. Preflight (OPTIONS) requests are handled automatically for matched routes, and CORS headers are appended to all non-WebSocket responses — including responses returned by onBeforeRequest.
  • #260 — Remove redundant initialize code as setName takes care of it, along with the nested blockConcurrencyWhile call.

  ---

  partysocket

  1.1.12 (Feb 8, 2026)

  • #317 — Fix PartySocket.reconnect() crashing when using basePath without room. The reconnect guard now accepts either room or basePath as sufficient context to construct a connection URL.
  • #319 — Throw a clear error when constructing a PartySocket without room or basePath (and without startClosed: true), instead of silently connecting to a malformed URL containing "undefined" as the room name.

  1.1.13 (Feb 9, 2026)

  • #322 — Fix reconnect() not working after maxRetries has been exhausted. The _connectLock was not released when the max retries early return was hit in _connect(), preventing any subsequent reconnect() call from initiating a new connection.

• #869 fc17506 Thanks @threepointone! - Remove room/party workaround for basePath routing now that partysocket handles reconnect without requiring room to be set.

• #873 d0579fa Thanks @threepointone! - Remove CORS wrapping from routeAgentRequest and delegate to partyserver's native CORS support. The cors option is now passed directly through to routePartykitRequest, which handles preflight and response headers automatically since partyserver 0.1.4.

• #865 c3211d0 Thanks @threepointone! - update dependencies

• Updated dependencies [21a7977, 3de98a3, c3211d0]:

  • @cloudflare/codemode@0.0.7
  • @cloudflare/ai-chat@0.0.7