feat: split ai-chat and codemode into separate packages

.changeset/calm-poems-crash.md

@@ -0,0 +1,14 @@
+---
+"@cloudflare/codemode": patch
+"@cloudflare/ai-chat": patch
+"agents": patch
+---
+
+feat: split ai-chat and codemode into separate packages
+
+Extract @cloudflare/ai-chat and @cloudflare/codemode into their own packages
+with comprehensive READMEs. Update agents README to remove chat-specific
+content and point to new packages. Fix documentation imports to reflect
+new package structure.
+
+Maintains backward compatibility, no breaking changes.

docs/client-tools-continuation.md

@@ -12,7 +12,7 @@ The `autoContinueAfterToolResult` option lets client tools behave like server to
 ## How It Works
 
 ```typescript
-import { useAgentChat } from "agents/ai-react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
 
 const { messages, addToolResult } = useAgentChat({
   agent,

docs/codemode.md

@@ -85,7 +85,7 @@ const result = streamText({
 ### After (With Codemode)
 
 ```typescript
-import { experimental_codemode as codemode } from "agents/codemode/ai";
+import { experimental_codemode as codemode } from "@cloudflare/codemode/ai";
 
 // Define your tools as usual
 const tools = {

docs/context-management.md

@@ -7,7 +7,8 @@
 ## How It Works
 
 ```typescript
-import { AIChatAgent, getCurrentAgent } from "agents";
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
 
 export class MyAgent extends AIChatAgent {
   async customMethod() {
@@ -33,7 +34,8 @@ export class MyAgent extends AIChatAgent {
 ## Real-World Example
 
 ```typescript
-import { AIChatAgent, getCurrentAgent } from "agents";
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
 import { generateText } from "ai";
 import { openai } from "@ai-sdk/openai";
 
@@ -82,6 +84,10 @@ agent.customMethod()
 ### Working with AI SDK Tools
 
 ```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+
 export class MyAgent extends AIChatAgent {
   async generateResponse(prompt: string) {
     // AI SDK tools automatically work
@@ -101,6 +107,9 @@ export class MyAgent extends AIChatAgent {
 ### Calling External Libraries
 
 ```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
+
 async function saveToDatabase(data: any) {
   const { agent } = getCurrentAgent<MyAgent>();
   // Can access agent info for logging, context, etc.
@@ -136,6 +145,7 @@ Gets the current agent from any context where it's available.
 **Usage:**
 
 ```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
 import { getCurrentAgent } from "agents";
 
 export class MyAgent extends AIChatAgent {

docs/migration-to-ai-sdk-v5.md

@@ -67,6 +67,8 @@ If you're extending `AIChatAgent`, the message handling has been updated:
 #### Before:
 
 ```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+
 class MyAgent extends AIChatAgent<Env> {
   async onChatMessage(
     onFinish: StreamTextOnFinishCallback<ToolSet>,
@@ -80,6 +82,8 @@ class MyAgent extends AIChatAgent<Env> {
 #### After:
 
 ```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+
 class MyAgent extends AIChatAgent<Env> {
   async onChatMessage(
     onFinish: StreamTextOnFinishCallback<ToolSet>,
@@ -181,7 +185,10 @@ for await (const chunk of result.fullStream) {
 **Optional manual utilities:**
 
 ```typescript
-import { autoTransformMessages, analyzeCorruption } from "agents";
+import {
+  autoTransformMessages,
+  analyzeCorruption
+} from "@cloudflare/ai-chat/ai-chat-v5-migration";
 
 // Manual transformation (usually not needed)
 const cleanMessages = autoTransformMessages(anyFormatMessages);
@@ -205,7 +212,7 @@ The `useAgentChat` hook can now automatically detect which tools require human-i
 To enable this, pass your `tools` object to the `useAgentChat` hook:
 
 ```typescript
-import { useAgentChat } from "agents/ai-react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
 import { tools } from "./tools";
 
 // ...
@@ -319,15 +326,14 @@ You can optionally use the migration utilities to convert stored messages:
 
 ```typescript
 import {
-  needsMigration,
   migrateMessagesToUIFormat,
   analyzeCorruption
-} from "agents";
+} from "@cloudflare/ai-chat/ai-chat-v5-migration";
 
 // In your agent class
-if (needsMigration(this.messages)) {
-  // Optional: analyze what types of corruption exist
-  const stats = analyzeCorruption(this.messages);
+// Check if messages need migration (autoTransformMessages handles this automatically)
+const stats = analyzeCorruption(this.messages);
+if (stats.legacyString || stats.corruptArray) {
   console.log(
     `Migrating ${stats.legacyString} legacy and ${stats.corruptArray} corrupt messages`
   );
@@ -341,18 +347,20 @@ if (needsMigration(this.messages)) {
 ## Migration Utilities Reference
 
 ```typescript
-// Type guards
-isUIMessage(message); // Check if already in v5 format
-needsMigration(messages); // Check if any messages need migration
+import {
+  migrateMessagesToUIFormat,
+  analyzeCorruption
+} from "@cloudflare/ai-chat/ai-chat-v5-migration";
 
 // Migration functions
-migrateToUIMessage(message); // Migrate single message
 migrateMessagesToUIFormat(messages); // Migrate array of messages
 
 // Analysis tools
 analyzeCorruption(messages); // Get stats about message format issues
 ```
 
+**Note:** The `autoTransformMessages` function is used internally by `AIChatAgent` and automatically handles migration. You typically don't need to call migration utilities manually.
+
 Migration handles:
 
 - `{role, content: string}` → `{role, parts: [{type: "text", text}]}`

docs/resumable-streaming.md

@@ -17,7 +17,7 @@ It just works!
 ### Server
 
 ```typescript
-import { AIChatAgent } from "agents/ai-chat-agent";
+import { AIChatAgent } from "@cloudflare/ai-chat";
 import { streamText } from "ai";
 import { openai } from "@ai-sdk/openai";
 
@@ -38,7 +38,7 @@ export class ChatAgent extends AIChatAgent<Env> {
 
 ```tsx
 import { useAgent } from "agents/react";
-import { useAgentChat } from "agents/ai-react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
 
 function Chat() {
   const agent = useAgent({

examples/playground/src/agents/chat.ts

@@ -1,4 +1,4 @@
-import { AIChatAgent } from "agents/ai-chat-agent";
+import { AIChatAgent } from "@cloudflare/ai-chat";
 import {
   convertToModelMessages,
   streamText,

examples/playground/src/components/Chat.tsx

@@ -1,5 +1,5 @@
 import "./Chat.css";
-import { useAgentChat } from "agents/ai-react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
 import { useAgent } from "agents/react";
 import { useCallback, useEffect, useRef, useState } from "react";
 

examples/resumable-stream-chat/src/client.tsx

@@ -1,7 +1,7 @@
 import type React from "react";
 import { Suspense, useState, useRef, useEffect } from "react";
 import { useAgent } from "agents/react";
-import { useAgentChat } from "agents/ai-react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
 import type { UIMessage } from "ai";
 
 /**

examples/resumable-stream-chat/src/server.ts

@@ -1,6 +1,6 @@
 import { openai } from "@ai-sdk/openai";
 import { routeAgentRequest } from "agents";
-import { AIChatAgent } from "agents/ai-chat-agent";
+import { AIChatAgent } from "@cloudflare/ai-chat";
 import {
   streamText,
   convertToModelMessages,

guides/human-in-the-loop/src/app.tsx

@@ -3,7 +3,7 @@ import { getToolName, isToolUIPart } from "ai";
 import { clientTools } from "./tools";
 import { APPROVAL, toolsRequiringConfirmation } from "./utils";
 import "./styles.css";
-import { useAgentChat, type AITool } from "agents/ai-react";
+import { useAgentChat, type AITool } from "@cloudflare/ai-chat/react";
 import { useAgent } from "agents/react";
 import { useCallback, useEffect, useRef, useState } from "react";
 

guides/human-in-the-loop/src/server.ts

@@ -1,6 +1,6 @@
 import { openai } from "@ai-sdk/openai";
 import { routeAgentRequest } from "agents";
-import { AIChatAgent } from "agents/ai-chat-agent";
+import { AIChatAgent } from "@cloudflare/ai-chat";
 import {
   convertToModelMessages,
   type StreamTextOnFinishCallback,

package.json

@@ -13,13 +13,13 @@
   "author": "Sunil Pai <spai@cloudflare.com>",
   "private": true,
   "scripts": {
-    "build": "npm run build -w agents -w hono-agents",
+    "build": "npm run build -w agents -w hono-agents -w @cloudflare/ai-chat -w @cloudflare/codemode",
     "format": "prettier --write .",
     "typecheck": "npx tsx scripts/typecheck.ts",
     "check:exports": "npx tsx scripts/check-exports.ts",
     "check:updates": "npx tsx scripts/check-updates.ts",
     "check": "sherif && npm run check:exports && prettier --check . && biome lint && npm run typecheck",
-    "test": "npm run test -w agents",
+    "test": "npm run test -w agents -w @cloudflare/ai-chat",
     "test:react": "npm run test:react -w agents",
     "postinstall": "patch-package && playwright install --with-deps chromium",
     "prepare": "husky"