feat: hoist useAgentChat into agents/chat/react with product wrappers (#1801)

* feat: hoist useAgentChat into agents/chat/react with product wrappers

Move the canonical `useAgentChat` implementation, WebSocket chat transport,
and chat wire types out of `@cloudflare/ai-chat` and into a new shared
`agents/chat/react` entry. `@cloudflare/ai-chat/react` and the new
`@cloudflare/think/react` become thin wrappers over this shared core, so
Think apps no longer need to depend on `@cloudflare/ai-chat` just to get the
React hook.

Why
---
Using `useAgentChat` from `@cloudflare/ai-chat` against a Think server was
awkward and behaviorally divergent. The biggest footgun was `setMessages`:
`AIChatAgent` persists a client-pushed flat transcript, while Think is
server-authoritative and silently ignores it. Apps had to pull in an
unrelated package and still got surprising behavior.

What changed
------------
- agents: add `agents/chat/react` exposing `useAgentChat`,
  `WebSocketChatTransport`, and shared chat wire types
  (`MessageType`, `OutgoingMessage`, `IncomingMessage`). Add a new
  `syncMessagesToServer` option (default `true`) so server-authoritative
  hosts can keep `setMessages` local-only. `@ai-sdk/react` is added as an
  optional peer dependency (only the chat/react subpath needs it).
- ai-chat: `react.tsx`, `types.ts`, and `ws-chat-transport.ts` are now
  thin re-export shims over `agents/chat/react`. Public API and behavior
  are unchanged for existing consumers.
- think: add `@cloudflare/think/react`, a Think-tuned wrapper that hardcodes
  `syncMessagesToServer: false` (and omits it from its option type), so
  `setMessages` stays a local view update. A dev-only warn-once covers plain
  JS callers that pass the option anyway.
- think (server): warn once (dev only) when Think receives a client-pushed
  `CF_AGENT_CHAT_MESSAGES` frame, naming `@cloudflare/think/react` and
  `clearHistory()` as the fix. This is behavior-triggered, so it only fires
  when an app actually hits the divergence (e.g. the ai-chat hook against a
  Think server).
- docs/examples/starters: migrate all Think-backed clients to import the
  hook from `@cloudflare/think/react` and drop the now-unnecessary
  `@cloudflare/ai-chat` dependency. AIChatAgent-backed examples are
  unchanged. Document that `setMessages` is display-only on Think.

Changesets: agents (minor), @cloudflare/think (minor),
@cloudflare/ai-chat (patch).

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(think-cli): assert basic template marker after ai-chat removal

The starter migration dropped `@cloudflare/ai-chat` from the basic Think
template, so the CLI scaffold test's dependency assertion was stale. Assert
on `@cloudflare/kumo` instead — still a full-starter-only marker that
distinguishes a template scaffold from an augment.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Sunil Pai <18808+threepointone@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: threepointone

.changeset/ai-chat-react-wrapper.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/ai-chat": patch
+---
+
+Refactor `@cloudflare/ai-chat/react` to re-export the shared implementation from `agents/chat/react` while preserving existing behavior and exports.

.changeset/shared-chat-react-core.md

@@ -0,0 +1,5 @@
+---
+"agents": minor
+---
+
+Add the shared `agents/chat/react` entry with `useAgentChat`, chat transport helpers, and shared chat wire types. The hook also adds `syncMessagesToServer` so hosts with server-authoritative transcript storage can keep `setMessages` local-only.

.changeset/think-react-wrapper.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/think": minor
+---
+
+Add `@cloudflare/think/react`, a Think-tuned `useAgentChat` wrapper that keeps `setMessages` local-only by default while reusing the shared chat React implementation.

docs/think/client-tools.md

@@ -18,7 +18,7 @@ On the client, pass `clientTools` to `useAgentChat`:
 
 ```tsx
 import { useAgent } from "agents/react";
-import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { useAgentChat } from "@cloudflare/think/react";
 
 function Chat() {
   const agent = useAgent({ agent: "MyAgent" });

docs/think/getting-started.md

@@ -25,7 +25,7 @@ npm init -y
 Install dependencies:
 
 ```sh
-npm install @cloudflare/think @cloudflare/ai-chat agents ai @cloudflare/shell zod workers-ai-provider react react-dom
+npm install @cloudflare/think agents ai @cloudflare/shell zod workers-ai-provider react react-dom
 npm install -D wrangler @cloudflare/vite-plugin @cloudflare/workers-types @vitejs/plugin-react @tailwindcss/vite tailwindcss typescript vite
 ```
 
@@ -119,7 +119,7 @@ Create `src/client.tsx`:
 ```tsx
 import { createRoot } from "react-dom/client";
 import { useAgent } from "agents/react";
-import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { useAgentChat } from "@cloudflare/think/react";
 
 function Chat() {
   const agent = useAgent({ agent: "MyAgent" });
@@ -194,6 +194,8 @@ npx vite dev
 
 Open the browser and send a message. The agent responds with streaming text, and workspace file tools are available to the model automatically.
 
+> **`setMessages` is display-only on Think.** Think is server-authoritative — its transcript is a projection of the Session tree, not a flat array the client owns. `useAgentChat` from `@cloudflare/think/react` therefore keeps `setMessages` local to the React view: edits update what's on screen but are **not** persisted and won't survive a refresh or reconnect (the server re-projects the authoritative history). To persist a clear, call `clearHistory()`. If you push a full transcript to Think anyway (for example, by using `@cloudflare/ai-chat/react` against a Think server), the server ignores it and logs a one-time dev warning.
+
 ## 6. Add persistent memory
 
 Override `configureSession` to give the model writable memory that survives restarts:

docs/think/index.md

@@ -584,7 +584,7 @@ chats.
 
 ```tsx
 import { useAgent } from "agents/react";
-import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { useAgentChat } from "@cloudflare/think/react";
 
 function Chat() {
   const agent = useAgent({ agent: "MyAgent" });

examples/AGENTS.md

@@ -209,7 +209,7 @@ Every example should include an info card at the top of the page explaining what
 
 ### Chat message rendering
 
-Any example with a chat UI (`useAgentChat` from `@cloudflare/ai-chat/react`, or `useChat`) must render the full shape of an assistant turn — not just text. Reference implementations: **`examples/ai-chat`** (streamdown + complete tool states) and **`examples/assistant`** (adds reasoning + approvals + branches).
+Any example with a chat UI (`useAgentChat` from `@cloudflare/ai-chat/react` or `@cloudflare/think/react`, or `useChat`) must render the full shape of an assistant turn — not just text. Reference implementations: **`examples/ai-chat`** (streamdown + complete tool states) and **`examples/assistant`** (adds reasoning + approvals + branches).
 
 Rules:
 

examples/agent-skills/package.json

@@ -10,7 +10,6 @@
     "types": "wrangler types env.d.ts --include-runtime false"
   },
   "dependencies": {
-    "@cloudflare/ai-chat": "*",
     "@cloudflare/kumo": "^2.5.2",
     "@cloudflare/think": "*",
     "@phosphor-icons/react": "^2.1.10",

examples/agent-skills/src/client.tsx

@@ -1,5 +1,5 @@
 import { useAgent } from "agents/react";
-import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { useAgentChat } from "@cloudflare/think/react";
 import { getToolName, isToolUIPart } from "ai";
 import {
   ChatCircleTextIcon,

examples/agents-as-tools/package.json

@@ -13,7 +13,6 @@
     "types": "wrangler types env.d.ts --include-runtime false"
   },
   "dependencies": {
-    "@cloudflare/ai-chat": "*",
     "@cloudflare/kumo": "^2.5.2",
     "@cloudflare/think": "*",
     "@phosphor-icons/react": "^2.1.10",