npm / @cloudflare/ai-chat
@cloudflare/ai-chat
What changed in @cloudflare/ai-chat 0.12, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-01.
7 breaking2 deprecations5 new APIs and options4 behavior and defaults8 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@cloudflare/ai-chat 0.1226 changes
Breaking changes 7
Requires agents@>=0.25.0 so Think and AI Chat can import the chat helpers provided by that release.
An active stream that finishes with a normal assistant response no longer starts an automatic continuation.
AIChatAgent messages are stored through Sessions, with existing message rows imported once on first wake; rolling back after migration leaves an empty conversation.
AI Chat requires agents 0.23.0 or later for the shared recovery Task definition and internal enqueue support.
The cleanupStreamBuffers export is removed because stream-buffer sweeps are no longer used.
The STREAM_CLEANUP_DELAY_SECONDS export is removed because stream-buffer sweeps are no longer used.
The transcript is now empty until onStart; subclasses that read this.messages in the constructor should read it from onStart or later.
Deprecations 2
maxOomRetries is deprecated in favor of chatRecovery.maxInterruptedAttempts.
Deprecated in favour of reconcileMessages; message reconciliation keeps assistant messages and tool outputs attached to the correct turn when a provider reuses a toolCallId.
New APIs and options 5
Interfaces can now be used as Props on Agent, AIChatAgent, Think, and routing helpers.
Adds eventDelivery: "terminal" to forward only lifecycle, progress, and milestone events for a run.
Adds session.mirror() to keep an in-memory transcript in sync with a session's change feed.
Adds onTurnEnd; terminal chat frames also carry outcomes and user message IDs so clients can settle sends correctly across recovery and reconnects.
AIChatAgent exposes its backing Streams capability so consumers on the same Durable Object can observe chat streams with streams.read().
Behavior and default changes 4
Chat recovery seals a turn after the configured number of interrupted attempts, defaulting to 5, so turns that repeatedly exceed the Durable Object memory limit do not retry forever.
The recovery work budget increases from 1000 to 10000, keeping it as generous as before when work is counted in durable segments.
The response is streamed instead of serializing the whole transcript; clients calling .json() are unaffected.
ResumableStream now uses the shared Streams capability for durable chat output; existing chat stream tables migrate on first construction after upgrade.
Fixes and other changes 8
Prevents agent-tool chunks from being duplicated or dropped during reconnect, child re-attach, and fiber recovery.
A failed agent-tool child is reported as failed even if it was evicted before the failure was recorded.
Settles approved tool calls that never ran once the conversation moves past them, preventing later turns from sending unresolved tool calls.
Continuation turns that fail before streaming now report an error to clients and onChatResponse instead of appearing to hang.
AI Chat recovers from transient response-reader errors instead of ending the turn, respects recovery persistence choices, and avoids joining stale recovery runs.
AI Chat and Think send the terminal done frame after persisting and broadcasting the assistant reply, preventing later sends from being overwritten.
Keeps a tool call's input when its approval request arrives before the input finishes streaming.
Prevents text from appearing twice when reconnecting during a tool continuation.