Version Packages

[github-actions]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

agents@0.5.0

Minor Changes

• #920 4dea3bd Thanks @threepointone! - Add shouldSendProtocolMessages hook and isConnectionProtocolEnabled predicate for per-connection control of protocol text frames

  Adds the ability to suppress protocol messages (CF_AGENT_IDENTITY, CF_AGENT_STATE, CF_AGENT_MCP_SERVERS) on a per-connection basis. This is useful for binary-only clients (e.g. MQTT devices) that cannot handle JSON text frames.

  Override shouldSendProtocolMessages(connection, ctx) to return false for connections that should not receive protocol messages. These connections still fully participate in RPC and regular messaging — only the automatic protocol text frames are suppressed, both on connect and during broadcasts.

  Use isConnectionProtocolEnabled(connection) to check a connection's protocol status at any time.

  Also fixes isConnectionReadonly to correctly survive Durable Object hibernation by re-wrapping the connection when the in-memory accessor cache has been cleared.

• #874 a6ec9b0 Thanks @threepointone! - Add retry utilities: this.retry(), per-task retry options, and RetryOptions type

  • this.retry(fn, options?) — retry any async operation with exponential backoff and jitter. Accepts optional shouldRetry predicate to bail early on non-retryable errors.
  • queue(), schedule(), scheduleEvery() accept { retry?: RetryOptions } for per-task retry configuration, persisted in SQLite alongside the task.
  • addMcpServer() accepts { retry?: RetryOptions } for configurable MCP connection retries.
  • RetryOptions type is exported for TypeScript consumers.
  • Retry options are validated eagerly at enqueue/schedule time — invalid values throw immediately.
  • Class-level retry defaults via static options = { retry: { ... } } — override defaults for an entire agent class.
  • Internal retries added for workflow operations (terminateWorkflow, pauseWorkflow, etc.) with Durable Object-aware error detection.

Patch Changes

• #899 04c6411 Thanks @threepointone! - Fix React hooks exhaustive-deps warning in useAgent by referencing cacheInvalidatedAt inside useMemo body.

• #904 d611b94 Thanks @ask-bonk! - Fix TypeScript "excessively deep" error with deeply nested state types

  Add a depth counter to CanSerialize and IsSerializableParam types that bails out to true after 10 levels of recursion. This prevents the "Type instantiation is excessively deep and possibly infinite" error when using deeply nested types like AI SDK CoreMessage[] as agent state.

• #911 67b1601 Thanks @threepointone! - Update all dependencies and fix breaking changes.

  Update all dependencies, add required aria-label props to Kumo Button components with shape (now required for accessibility), and fix state test for constructor-time validation of conflicting onStateChanged/onStateUpdate hooks.

• #889 9100e65 Thanks @deathbyknowledge! - Fix scheduling schema compatibility with zod v3 and improve schema structure.

  • Change zod/v3 import to zod so the package works for users on zod v3 (who don't have the zod/v3 subpath).
  • Replace flat object with optional fields with a z.discriminatedUnion on when.type. Each scheduling variant now only contains the fields it needs, making the schema cleaner and easier for LLMs to follow.
  • Replace z.coerce.date() with z.string(). Zod v4's toJSONSchema() cannot represent Date, and the AI SDK routes zod v4 schemas through it directly. Dates are now returned as ISO 8601 strings.
  • Type change: Schedule["when"] is now a discriminated union instead of a flat object with optional fields. when.date is string instead of Date.

• #916 24e16e0 Thanks @threepointone! - Widen peer dependency ranges across packages to prevent cascading major bumps during 0.x minor releases. Mark @cloudflare/ai-chat and @cloudflare/codemode as optional peer dependencies of agents to fix unmet peer dependency warnings during installation.

• #898 cd2d34f Thanks @jvg123! - Add keepalive ping to POST SSE response streams in WorkerTransport

  The GET SSE handler already sends event: ping every 30 seconds to keep the connection alive, but the POST SSE handler did not. This caused POST response streams to be silently dropped by proxies and infrastructure during long-running tool calls (e.g., MCP tools/call), resulting in clients never receiving the response.

• #874 a6ec9b0 Thanks @threepointone! - Make queue and schedule getter methods synchronous

  getQueue(), getQueues(), getSchedule(), dequeue(), dequeueAll(), and dequeueAllByCallback() were unnecessarily async despite only performing synchronous SQL operations. They now return values directly instead of wrapping them in Promises. This is backward compatible — existing code using await on these methods will continue to work.

@cloudflare/ai-chat@0.1.0

Minor Changes

• #899 04c6411 Thanks @threepointone! - Refactor AIChatAgent: extract ResumableStream class, add WebSocket ChatTransport, simplify SSE parsing.

  Bug fixes:

  • Fix setMessages functional updater sending empty array to server
  • Fix _sendPlaintextReply creating multiple text parts instead of one
  • Fix uncaught exception on empty/invalid request body
  • Fix CF_AGENT_MESSAGE_UPDATED not broadcast for streaming messages
  • Fix stream resumption race condition (client-initiated resume request + replay flag)
  • Fix _streamCompletionPromise not resolved on error (tool continuations could hang)
  • Fix body lost during tool continuations (now preserved alongside clientTools)
  • Fix clearAll() not clearing in-memory chunk buffer (orphaned chunks could flush after clear)
  • Fix errored streams never cleaned up by garbage collector
  • Fix reasoning-delta silently dropping data when reasoning-start was missed (stream resumption)
  • Fix row size guard using string.length instead of UTF-8 byte count for SQLite limits
  • Fix completed guard on abort listener to prevent redundant cancel after stream completion

  New features:

  • maxPersistedMessages — cap SQLite message storage with automatic oldest-message deletion
  • body option on useAgentChat — send custom data with every request (static or dynamic)
  • Incremental persistence with hash-based cache to skip redundant SQL writes
  • Row size guard — automatic two-pass compaction when messages approach SQLite 2MB limit
  • onFinish is now optional — framework handles abort controller cleanup and observability
  • Stream chunk size guard in ResumableStream (skip oversized chunks for replay)
  • Full tool streaming lifecycle in message-builder (tool-input-start/delta/error, tool-output-error)

  Docs:

  • New docs/chat-agents.md — comprehensive AIChatAgent and useAgentChat reference
  • Rewritten README, migration guides, human-in-the-loop, resumable streaming, client tools docs
  • New examples/ai-chat/ example with modern patterns and Workers AI

  Deprecations (with console.warn):

  • createToolsFromClientSchemas(), extractClientToolSchemas(), detectToolsRequiringConfirmation()
  • tools, toolsRequiringConfirmation, experimental_automaticToolResolution options
  • addToolResult() (use addToolOutput())

• #919 6b6497c Thanks @threepointone! - Change autoContinueAfterToolResult default from false to true.

  Client-side tool results and tool approvals now automatically trigger a server continuation by default, matching the behavior of server-executed tools (which auto-continue via streamText's multi-step). This eliminates the most common setup friction with client tools — the LLM now responds after receiving tool results without requiring explicit opt-in.

  To restore the previous behavior, set autoContinueAfterToolResult: false in useAgentChat.

Patch Changes

• #900 16b2dca Thanks @deathbyknowledge! - Add support for data-* stream parts (developer-defined typed JSON blobs) in the shared message builder and client hook.

  Data part handling:

  applyChunkToParts now handles data-* prefixed chunk types, covering both server persistence and client reconstruction (stream resume, cross-tab broadcast). Transient parts (transient: true) are broadcast to connected clients but excluded from message.parts and SQLite persistence. Non-transient parts support reconciliation by type+id — a second chunk with the same type and id updates the existing part's data in-place instead of appending a duplicate.

  onData callback forwarding:

  useAgentChat now invokes the onData callback for data-* chunks on the stream resumption and cross-tab broadcast codepaths, which bypass the AI SDK's internal pipeline. For new messages sent via the transport, the AI SDK already invokes onData internally. This is the correct way to consume transient data parts on the client since they are not added to message.parts.

• #922 c8e5244 Thanks @threepointone! - Fix tool approval UI not surviving page refresh, and fix invalid prompt error after approval

  • Handle tool-approval-request and tool-output-denied stream chunks in the server-side message builder. Previously these were only handled client-side, so the server never transitioned tool parts to approval-requested or output-denied state.
  • Persist the streaming message to SQLite (without broadcasting) when a tool enters approval-requested state. The stream is paused waiting for user approval, so this is a natural persistence point. Without this, refreshing the page would reload from SQLite where the tool was still in input-available state, showing "Running..." instead of the Approve/Reject UI.
  • On stream completion, update the early-persisted message in place rather than appending a duplicate.
  • Fix _applyToolApproval to merge with existing approval data instead of replacing it. Previously approval: { approved } would overwrite the entire object, losing the id field that convertToModelMessages needs to produce a valid tool-approval-request content part. This caused an InvalidPromptError on the continuation stream after approval.

• #897 994a808 Thanks @alexanderjacobsen! - Fix client tool schemas lost after DO restart by re-sending them with CF_AGENT_TOOL_RESULT

• #916 24e16e0 Thanks @threepointone! - Widen peer dependency ranges across packages to prevent cascading major bumps during 0.x minor releases. Mark @cloudflare/ai-chat and @cloudflare/codemode as optional peer dependencies of agents to fix unmet peer dependency warnings during installation.

• #912 baa87cc Thanks @threepointone! - Persist request context across Durable Object hibernation.

  Persist _lastBody and _lastClientTools to SQLite so custom body fields and client tool schemas survive Durable Object hibernation during tool continuation flows (issue ai-chat: forward or document body behavior during tool continuation path #887). Add test coverage for body forwarding during tool auto-continuation, and update JSDoc for OnChatMessageOptions.body to document tool continuation and hibernation behavior.

• #913 bc91c9a Thanks @threepointone! - Sync _lastClientTools cache and SQLite when client tools arrive via CF_AGENT_TOOL_RESULT, and align the wire type with ClientToolSchema (JSONSchema7 instead of Record<string, unknown>)

• #919 6b6497c Thanks @threepointone! - Add auto-continuation support for tool approval (needsApproval).

  When a tool with needsApproval: true is approved via CF_AGENT_TOOL_APPROVAL, the server can now automatically continue the conversation (matching the existing autoContinue behavior of CF_AGENT_TOOL_RESULT). The client hook passes autoContinue with approval messages when autoContinueAfterToolResult is enabled. Also fixes silent data loss where tool-output-available events for tool calls in previous assistant messages were dropped during continuation streams by adding a cross-message fallback search in _streamSSEReply.

• #910 a668155 Thanks @threepointone! - Add structural message validation and fix message metadata on broadcast/resume path.

  Structural message validation:

  Messages loaded from SQLite are now validated for required structure (non-empty id string, valid role, parts is an array). Malformed rows — from corruption, manual tampering, or schema drift — are logged with a warning and silently skipped instead of crashing the agent. This is intentionally lenient: empty parts arrays are allowed (streams that errored mid-flight), and no tool/data schema validation is performed at load time (that remains a userland concern via safeValidateUIMessages from the AI SDK).

  Message metadata on broadcast/resume path:

  The server already captures messageMetadata from start, finish, and message-metadata stream chunks and persists it on message.metadata. However, the client-side broadcast path (multi-tab sync) and stream resume path (reconnection) did not propagate metadata — the activeStreamRef only tracked parts. Now it also tracks metadata, and flushActiveStreamToMessages includes it in the partial message flushed to React state. This means cross-tab clients and reconnecting clients see metadata (model info, token usage, timestamps) during streaming, not just after the final CF_AGENT_CHAT_MESSAGES broadcast.

@cloudflare/codemode@0.0.8

Patch Changes

• #916 24e16e0 Thanks @threepointone! - Widen peer dependency ranges across packages to prevent cascading major bumps during 0.x minor releases. Mark @cloudflare/ai-chat and @cloudflare/codemode as optional peer dependencies of agents to fix unmet peer dependency warnings during installation.

hono-agents@3.0.4

Patch Changes

• #916 24e16e0 Thanks @threepointone! - Widen peer dependency ranges across packages to prevent cascading major bumps during 0.x minor releases. Mark @cloudflare/ai-chat and @cloudflare/codemode as optional peer dependencies of agents to fix unmet peer dependency warnings during installation.

[pkg-pr-new]

Open in StackBlitz

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

commit: 4b85155