ai-chat: align with Think + multi-ai-chat example on the sub-agent routing primitive

.changeset/ai-chat-cleanups.md

@@ -0,0 +1,15 @@
+---
+"@cloudflare/ai-chat": minor
+"agents": patch
+---
+
+Align `AIChatAgent` generics and types with `@cloudflare/think`, plus a reference example for multi-session chat built on the sub-agent routing primitive.
+
+- **New `Props` generic**: `AIChatAgent<Env, State, Props>` extending `Agent<Env, State, Props>`. Subclasses now get properly typed `this.ctx.props`.
+- **Shared lifecycle types**: `ChatResponseResult`, `ChatRecoveryContext`, `ChatRecoveryOptions`, `SaveMessagesResult`, and `MessageConcurrency` now live in `agents/chat` and are re-exported by both `@cloudflare/ai-chat` and `@cloudflare/think`. No behavior change; one place to edit when shapes evolve.
+- **`ChatMessage` stays the public message type**: the package continues to export `ChatMessage`, and the public API/docs keep using that name.
+- **`messages` stays a public field**: `messages: ChatMessage[]`.
+
+The full stance (AIChatAgent is first-class, production-ready, and continuing to get features; shared infrastructure should land in `agents/chat` where both classes benefit) is captured in [`design/rfc-ai-chat-maintenance.md`](../design/rfc-ai-chat-maintenance.md).
+
+A new example, `examples/multi-ai-chat`, demonstrates the multi-session pattern end-to-end on top of the sub-agent routing primitive: an `Inbox` Agent owns the chat list + shared memory; each chat is an `AIChatAgent` facet (`this.subAgent(Chat, id)`). The client addresses the active chat via `useAgent({ sub: [{ agent: "Chat", name: chatId }] })` — no separate DO binding, no custom routing on the server. `Inbox.onBeforeSubAgent` gates with `hasSubAgent` as a strict registry, and `Chat` reaches its parent via `this.parentAgent(Inbox)`.

README.md

@@ -100,26 +100,27 @@ The agent is a Durable Object, so it needs a binding and a SQLite migration in `
 
 ## Features
 
-| Feature                 | Description                                                                |
-| ----------------------- | -------------------------------------------------------------------------- |
-| **Persistent State**    | Syncs to all connected clients, survives restarts                          |
-| **Callable Methods**    | Type-safe RPC via the `@callable()` decorator                              |
-| **Scheduling**          | One-time, recurring, and cron-based tasks                                  |
-| **WebSockets**          | Real-time bidirectional communication with lifecycle hooks                 |
-| **AI Chat**             | Message persistence, resumable streaming, server/client tool execution     |
-| **MCP**                 | Act as MCP servers or connect as MCP clients (HTTP, SSE, RPC, elicitation) |
-| **WebMCP**              | Expose browser-side tools to agents over WebSocket                         |
-| **Workflows**           | Durable multi-step tasks with human-in-the-loop approval                   |
-| **Email**               | Send, receive, and reply via Cloudflare Email Service                      |
-| **Voice**               | Continuous STT, streaming TTS, VAD, interruption, SFU utilities            |
-| **Browser Agents**      | Run agents in the browser tab with `agents/browser`                        |
-| **Code Mode**           | LLMs generate executable TypeScript instead of individual tool calls       |
-| **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem     |
-| **x402 Payments**       | Pay-per-call APIs and tools via the x402 protocol                          |
-| **Observability**       | Built-in tracing, metrics, and structured logs                             |
-| **SQL**                 | Direct SQLite queries via Durable Objects                                  |
-| **React Hooks**         | `useAgent`, `useAgentChat`, `useVoiceAgent` for frontend integration       |
-| **Vanilla JS Client**   | `AgentClient` and `VoiceClient` for non-React environments                 |
+| Feature                 | Description                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| **Persistent State**    | Syncs to all connected clients, survives restarts                               |
+| **Callable Methods**    | Type-safe RPC via the `@callable()` decorator                                   |
+| **Sub-agents**          | Parent/child DO composition via facets, nested routing, and typed parent lookup |
+| **Scheduling**          | One-time, recurring, and cron-based tasks                                       |
+| **WebSockets**          | Real-time bidirectional communication with lifecycle hooks                      |
+| **AI Chat**             | Message persistence, resumable streaming, server/client tool execution          |
+| **MCP**                 | Act as MCP servers or connect as MCP clients (HTTP, SSE, RPC, elicitation)      |
+| **WebMCP**              | Expose browser-side tools to agents over WebSocket                              |
+| **Workflows**           | Durable multi-step tasks with human-in-the-loop approval                        |
+| **Email**               | Send, receive, and reply via Cloudflare Email Service                           |
+| **Voice**               | Continuous STT, streaming TTS, VAD, interruption, SFU utilities                 |
+| **Browser Agents**      | Run agents in the browser tab with `agents/browser`                             |
+| **Code Mode**           | LLMs generate executable TypeScript instead of individual tool calls            |
+| **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem          |
+| **x402 Payments**       | Pay-per-call APIs and tools via the x402 protocol                               |
+| **Observability**       | Built-in tracing, metrics, and structured logs                                  |
+| **SQL**                 | Direct SQLite queries via Durable Objects                                       |
+| **React Hooks**         | `useAgent`, `useAgentChat`, `useVoiceAgent` for frontend integration            |
+| **Vanilla JS Client**   | `AgentClient` and `VoiceClient` for non-React environments                      |
 
 ## Packages
 
@@ -141,7 +142,7 @@ The agent is a Durable Object, so it needs a binding and a SQLite migration in `
 The [`examples/`](examples) directory has 30+ self-contained demos. A non-exhaustive tour:
 
 - **Showcase** — [`playground/`](examples/playground) is the kitchen-sink app: state, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in one UI
-- **Chat & assistants** — [`assistant/`](examples/assistant), [`workspace-chat/`](examples/workspace-chat), [`resumable-stream-chat/`](examples/resumable-stream-chat), [`structured-input/`](examples/structured-input), [`dynamic-tools/`](examples/dynamic-tools)
+- **Chat & assistants** — [`assistant/`](examples/assistant), [`workspace-chat/`](examples/workspace-chat), [`resumable-stream-chat/`](examples/resumable-stream-chat), [`structured-input/`](examples/structured-input), [`dynamic-tools/`](examples/dynamic-tools), [`multi-ai-chat/`](examples/multi-ai-chat)
 - **MCP** — [`mcp/`](examples/mcp), [`mcp-client/`](examples/mcp-client), [`mcp-worker/`](examples/mcp-worker), [`mcp-worker-authenticated/`](examples/mcp-worker-authenticated), [`mcp-elicitation/`](examples/mcp-elicitation), [`mcp-rpc-transport/`](examples/mcp-rpc-transport), [`webmcp/`](examples/webmcp)
 - **Code Mode & sandboxes** — [`codemode/`](examples/codemode), [`codemode-mcp/`](examples/codemode-mcp), [`codemode-mcp-openapi/`](examples/codemode-mcp-openapi), [`dynamic-workers/`](examples/dynamic-workers), [`dynamic-workers-playground/`](examples/dynamic-workers-playground), [`worker-bundler-playground/`](examples/worker-bundler-playground)
 - **Voice** — [`voice-agent/`](examples/voice-agent), [`voice-input/`](examples/voice-input), [`elevenlabs-starter/`](examples/elevenlabs-starter)

design/AGENTS.md

@@ -69,23 +69,26 @@ Keep it concise. A few paragraphs is fine. These are records, not essays.
 
 ## Current contents
 
-| File                       | Type       | Scope                                                                                 |
-| -------------------------- | ---------- | ------------------------------------------------------------------------------------- |
-| `chat-shared-layer.md`     | design doc | Chat shared layer — streaming, sanitization, and protocol primitives in agents/chat   |
-| `think.md`                 | design doc | Think — chat agent base class, streaming, client tools, resumable streams, extensions |
-| `think-sessions.md`        | design doc | Think + Session integration design (implemented in Phase 1)                           |
-| `think-vs-aichat.md`       | design doc | Think vs AIChatAgent — comparison, use cases, architectural differences               |
-| `think-roadmap.md`         | design doc | Think implementation plan — all 5 phases complete, full AIChatAgent parity            |
-| `chat-api.md`              | analysis   | AIChatAgent + useAgentChat API analysis — pain points, improvements, Think influence  |
-| `chat-improvements.md`     | design doc | Non-breaking improvements — shared extraction complete, client DX items remain        |
-| `readonly-connections.md`  | design doc | Readonly connections — enforcement, storage wrapping, caveats                         |
-| `retries.md`               | design doc | Retry system — primitives, integration points, backoff strategy, tradeoffs            |
-| `visuals.md`               | design doc | UI component library (Kumo), dark mode, custom patterns, routing integration          |
-| `workspace.md`             | design doc | Workspace — hybrid SQLite+R2 filesystem, bash, symlinks, observability                |
-| `rfc-sub-agents.md`        | RFC        | Sub-agents — child DOs via facets, typed stubs, built into Agent (accepted)           |
-| `rfc-sub-agent-routing.md` | RFC        | Sub-agent external addressability — nested URLs, `onBeforeSubAgent`, per-call bridge  |
-| `loopback.md`              | design doc | Loopback pattern — cross-boundary RPC for sub-agents and dynamic isolates             |
-| `worker-bundler.md`        | design doc | Worker bundler — host-side assets, no code generation, mounting is caller's concern   |
+| File                         | Type       | Scope                                                                                 |
+| ---------------------------- | ---------- | ------------------------------------------------------------------------------------- |
+| `chat-shared-layer.md`       | design doc | Chat shared layer — streaming, sanitization, and protocol primitives in agents/chat   |
+| `think.md`                   | design doc | Think — chat agent base class, streaming, client tools, resumable streams, extensions |
+| `think-sessions.md`          | design doc | Think + Session integration design (implemented in Phase 1)                           |
+| `think-vs-aichat.md`         | design doc | Think vs AIChatAgent — comparison, use cases, architectural differences               |
+| `think-roadmap.md`           | design doc | Think implementation plan — all 5 phases complete, full AIChatAgent parity            |
+| `chat-api.md`                | analysis   | AIChatAgent + useAgentChat API analysis — pain points, improvements, Think influence  |
+| `chat-improvements.md`       | design doc | Non-breaking improvements — shared extraction complete, client DX items remain        |
+| `readonly-connections.md`    | design doc | Readonly connections — enforcement, storage wrapping, caveats                         |
+| `retries.md`                 | design doc | Retry system — primitives, integration points, backoff strategy, tradeoffs            |
+| `visuals.md`                 | design doc | UI component library (Kumo), dark mode, custom patterns, routing integration          |
+| `workspace.md`               | design doc | Workspace — hybrid SQLite+R2 filesystem, bash, symlinks, observability                |
+| `sub-agent-routing.md`       | design doc | Sub-agent routing as shipped — facets, nested URLs, registry, parent lookup, caveats  |
+| `rfc-sub-agents.md`          | RFC        | Sub-agents — child DOs via facets, typed stubs, built into Agent (accepted)           |
+| `rfc-sub-agent-routing.md`   | RFC        | Sub-agent external addressability — nested URLs, `onBeforeSubAgent`, per-call bridge  |
+| `rfc-think-multi-session.md` | RFC        | Multi-session Think / Chats pattern — parent directory + per-chat child DOs           |
+| `rfc-ai-chat-maintenance.md` | RFC        | AIChatAgent first-class stance, shared chat toolkit, multi-session example direction  |
+| `loopback.md`                | design doc | Loopback pattern — cross-boundary RPC for sub-agents and dynamic isolates             |
+| `worker-bundler.md`          | design doc | Worker bundler — host-side assets, no code generation, mounting is caller's concern   |
 
 ## Relationship to `/docs`
 

design/README.md

@@ -12,5 +12,6 @@ The goal is to give contributors (and future-us) a quick way to understand _why_
 | [visuals.md](./visuals.md)                           | UI component library choice, Kumo usage, custom patterns                    |
 | [readonly-connections.md](./readonly-connections.md) | Readonly connection enforcement, storage, tradeoffs, and caveats            |
 | [workspace.md](./workspace.md)                       | Workspace — hybrid SQLite+R2 filesystem, bash, symlinks                     |
+| [sub-agent-routing.md](./sub-agent-routing.md)       | Sub-agent routing as shipped — facets, nested URLs, registry, parent lookup |
 | [rfc-sub-agents.md](./rfc-sub-agents.md)             | RFC: Sub-agents — child DOs via facets, typed stubs, mixin API              |
 | [loopback.md](./loopback.md)                         | Loopback pattern — cross-boundary RPC for sub-agents and dynamic isolates   |