Add durable cancellation mode for useAgentChat

[whoiskatrin]

Summary

Adds an opt-in durable cancellation mode for useAgentChat:

useAgentChat({
  agent,
  durable: true
});

durable: true means the browser is treated as a reconnectable observer of a server turn. Generic client-side stream abort/cleanup is local-only, but explicit stop() still sends cf_agent_chat_request_cancel and cancels the server turn.

For lower-level control, this also adds:

serverTurnCancellation?: "on-client-abort" | "explicit-only";

The default remains "on-client-abort" for backwards compatibility.

What the issue actually was

This is not about a raw WebSocket close directly calling server-side abort.

The problematic path is one layer higher:

1. useAgentChat wraps AI SDK useChat.
2. AI SDK useChat owns a local active response with an AbortController.
3. WebSocketChatTransport.sendMessages() receives that signal as options.abortSignal, and also exposes a ReadableStream whose cancel() method can be called by the client stream lifecycle.
4. Before this PR, both paths used the same onAbort() handler.
5. That handler always sent cf_agent_chat_request_cancel.
6. The server correctly treated that frame as real server-turn cancellation.

So the server could not distinguish these two cases:

• the user/app explicitly clicked Stop and wanted to cancel the durable turn
• the client-side response/stream was aborted or disposed as part of browser/React/AI SDK lifecycle

For Durable Object backed agents, the second case should often be recoverable via stream resumption. The browser can disappear or detach while the durable server turn continues and buffers chunks for a later reconnect.

What changed

• Added durable?: boolean to useAgentChat.
  • durable: true maps to serverTurnCancellation: "explicit-only".
• Added advanced serverTurnCancellation policy.
  • "on-client-abort" preserves current behavior.
  • "explicit-only" makes generic client abort/stream cancel local-only.
• Added WebSocketChatTransport.cancelActiveServerTurn() for explicit server cancellation.
• Wrapped useAgentChat().stop() so explicit stop still cancels the server turn even in durable mode.
• Updated docs for resumable/durable semantics.

Tests

• npm run check
• cd packages/ai-chat && npm run test

Related

Fixes #1471

[changeset-bot]

🦋 Changeset detected

Latest commit: d91facd

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

This PR includes changesets to release 1 package

Name	Type
@cloudflare/ai-chat	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

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1484

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1484

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1484

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1484

commit: d91facd

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[advait]

@whoiskatrin LGTM thank you!