@firtoz/chat-agent 1.0.1 → 2.1.0

package/README.md

@@ -1,39 +1,79 @@
 # @firtoz/chat-agent
 
-DB-agnostic ChatAgent for Cloudflare Durable Objects with OpenRouter - a simplified alternative to `@cloudflare/ai-chat`.
+[![npm version](https://img.shields.io/npm/v/%40firtoz%2Fchat-agent.svg)](https://www.npmjs.com/package/@firtoz/chat-agent)
+[![npm downloads](https://img.shields.io/npm/dm/%40firtoz%2Fchat-agent.svg)](https://www.npmjs.com/package/@firtoz/chat-agent)
+[![license](https://img.shields.io/npm/l/%40firtoz%2Fchat-agent.svg)](https://github.com/firtoz/fullstack-toolkit/blob/main/LICENSE)
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Cloudflare](https://img.shields.io/badge/Cloudflare-Durable_Objects-F38020?logo=cloudflare&logoColor=white)](https://developers.cloudflare.com/durable-objects/)
+[![OpenRouter](https://img.shields.io/badge/OpenRouter-AI-6366f1)](https://openrouter.ai/)
+
+**Wire protocol (Zod 4), `defineTool`, and `ChatAgentBase` for Durable Objects + OpenRouter** — streaming chat, tools, and multi-tab sync; plug in Drizzle or raw SQL via sibling packages.
+
+**Persistence is separate:** install one of:
+
+- **`@firtoz/chat-agent-drizzle`** — Drizzle ORM (recommended)
+- **`@firtoz/chat-agent-sql`** — raw `this.sql`
+
+## Upgrading from v1
+
+v1 shipped `DrizzleChatAgent`, `SqlChatAgent`, and `ChatAgent` (alias) from this package. v2 keeps only protocol + base here.
+
+| v1 | v2 |
+|----|-----|
+| `import { DrizzleChatAgent, defineTool } from "@firtoz/chat-agent"` | `import { defineTool } from "@firtoz/chat-agent"` and `import { DrizzleChatAgent } from "@firtoz/chat-agent-drizzle"` |
+| `import { SqlChatAgent } from "@firtoz/chat-agent"` | `import { SqlChatAgent } from "@firtoz/chat-agent-sql"` |
+| `import { … } from "@firtoz/chat-agent/db/schema"` | `import { … } from "@firtoz/chat-agent-drizzle/db/schema"` |
+| `import { ChatAgent } from "@firtoz/chat-agent"` (Drizzle alias) | `import { DrizzleChatAgent } from "@firtoz/chat-agent-drizzle"` (or a local `type ChatAgent = DrizzleChatAgent`) |
+
+Add `bun add @firtoz/chat-agent-drizzle` (and `drizzle-orm`) or `bun add @firtoz/chat-agent-sql` as needed.
 
 ## Overview
 
-Three classes for different database preferences:
+- **`ChatAgentBase`** — Abstract class with chat + streaming + tools + multi-tab broadcast logic
+- **Concrete agents** — `DrizzleChatAgent` (`@firtoz/chat-agent-drizzle`), `SqlChatAgent` (`@firtoz/chat-agent-sql`)
 
-- **`ChatAgentBase`** - Abstract base class with all chat logic
-- **`DrizzleChatAgent`** - Type-safe implementation using Drizzle ORM (recommended)
-- **`SqlChatAgent`** - Raw SQL implementation using `this.sql` template tags
+Shared behavior (all implementations):
 
-All implementations share the same API and features:
 - OpenRouter API integration (simpler than AI SDK)
 - Resumable streaming with chunk buffering
-- Server-side and client-side tool execution
+- **Multi-tab sync**: `messageStart`, chunks, `messageEnd`, `messageUpdated`, `streamResume`, and post-mutation `history` are **broadcast** to every WebSocket on the same Durable Object (merge by message `id` / `streamId` on the client)
+- Serialized chat turns with batched `toolResult` + `autoContinue`
+- Server-side and client-side tools
 - Cloudflare AI Gateway support
-- Message persistence in SQLite
+- Optional `maxPersistedMessages` and `sanitizeMessageForPersistence()`
+- `waitUntilStable()`, `resetTurnState()`, `hasPendingInteraction()` (subclasses)
+- Tool approval (`needsApproval` → `toolApprovalRequest` / `toolApprovalResponse`)
+- Regenerate / client sync (`sendMessage` with `trigger`, optional `messages`)
+- **Provider metadata** on tool calls for upstream round-trips
+- Wire schemas use **Zod 4** (`zod/v4`)
+
+### Long-running streams (Durable Object keep-alive)
+
+Streaming uses Partyserver’s `experimental_waitUntil`. Enable **`enable_ctx_exports`** in `wrangler.jsonc` (required for `experimental_waitUntil` on `Server` / `Agent`).
 
 ## Installation
 
 ```bash
 bun add @firtoz/chat-agent @openrouter/sdk agents
+```
 
-# For Drizzle implementation:
-bun add drizzle-orm
+For a runnable Durable Object agent, add a persistence package:
+
+```bash
+# Drizzle (recommended)
+bun add @firtoz/chat-agent-drizzle drizzle-orm
 bun add -d drizzle-kit
-```
 
-## Quick Start
+# Or raw SQL only
+bun add @firtoz/chat-agent-sql
+```
 
-### Using DrizzleChatAgent (Recommended)
+## Quick start (Drizzle)
 
 ```typescript
-import { DrizzleChatAgent, defineTool } from "@firtoz/chat-agent";
-import type { AgentContext } from "agents";
+import { defineTool, type ToolDefinition } from "@firtoz/chat-agent";
+import { DrizzleChatAgent } from "@firtoz/chat-agent-drizzle";
 
 interface Env {
   OPENROUTER_API_KEY: string;
@@ -48,14 +88,14 @@ class MyAgent extends DrizzleChatAgent<Env> {
     return "anthropic/claude-sonnet-4.5";
   }
 
-  protected override getTools() {
+  protected override getTools(): ToolDefinition[] {
     return [
       defineTool({
         name: "get_time",
         description: "Get current time",
         parameters: { type: "object", properties: {} },
-        execute: async () => ({ time: new Date().toISOString() })
-      })
+        execute: async () => ({ time: new Date().toISOString() }),
+      }),
     ];
   }
 }
@@ -63,381 +103,99 @@ class MyAgent extends DrizzleChatAgent<Env> {
 export { MyAgent };
 ```
 
-### Using SqlChatAgent
-
-```typescript
-import { SqlChatAgent } from "@firtoz/chat-agent";
-
-class MyAgent extends SqlChatAgent<Env> {
-  // Same API as DrizzleChatAgent
-  protected override getSystemPrompt(): string {
-    return "You are a helpful assistant.";
-  }
-}
-```
-
-## Setup Instructions
-
-### DrizzleChatAgent Setup
-
-#### 1. Add Wrangler Rules
-
-**IMPORTANT:** Add this to your `wrangler.jsonc` to import SQL migration files:
-
-```jsonc
-{
-  /**
-   * Rules to import SQL migration files as text
-   * Required for Drizzle ORM migrations in Durable Objects
-   * @see https://orm.drizzle.team/docs/connect-cloudflare-do
-   */
-  "rules": [
-    {
-      "type": "Text",
-      "globs": ["**/*.sql"],
-      "fallthrough": true
-    }
-  ]
-}
-```
-
-#### 2. Create Drizzle Config
-
-Create `drizzle.config.ts` in your package:
-
-```typescript
-import { defineConfig } from "drizzle-kit";
-
-export default defineConfig({
-  schema: "./node_modules/@firtoz/chat-agent/src/db/schema.ts",
-  out: "./drizzle",
-  dialect: "sqlite",
-  driver: "durable-sqlite",
-});
-```
+See **`@firtoz/chat-agent-drizzle`** for Wrangler rules, migrations, and `drizzle.config.ts`.
 
-Or if you're in the chat-agent package itself:
+## Quick start (SQL)
 
 ```typescript
-import { defineConfig } from "drizzle-kit";
-
-export default defineConfig({
-  schema: "./src/db/schema.ts",
-  out: "./drizzle",
-  dialect: "sqlite",
-  driver: "durable-sqlite",
-});
-```
+import { defineTool } from "@firtoz/chat-agent";
+import { SqlChatAgent } from "@firtoz/chat-agent-sql";
 
-#### 3. Add Script to package.json
-
-```json
-{
-  "scripts": {
-    "db:generate": "bunx drizzle-kit generate"
-  }
+class MyAgent extends SqlChatAgent<Env> {
+  // Same overrides as Drizzle; tables are created in dbInitialize()
 }
 ```
 
-#### 4. Generate Migrations
-
-```bash
-bun run db:generate
-```
-
-This creates:
-- `drizzle/migrations.js` - Runtime migration imports
-- `drizzle/0000_*.sql` - Migration SQL files
-- `drizzle/meta/` - Journal and snapshots
-
-The migrations are automatically run when `DrizzleChatAgent` initializes.
-
-### SqlChatAgent Setup
-
-No additional setup needed! The SQL version creates tables automatically using `this.sql` template tags in `dbInitialize()`.
-
-## ChatAgentBase (Abstract Class)
-
-The base class handles all chat logic and defines the abstract database interface that implementations must provide.
+## ChatAgentBase (abstract)
 
-### Abstract Methods
+Subclasses must implement the database interface (see Drizzle/SQL packages for examples).
 
-Subclasses must implement these database operations:
+### Abstract methods
 
 ```typescript
-// Initialization
 protected abstract dbInitialize(): void;
-
-// Messages
 protected abstract dbLoadMessages(): ChatMessage[];
 protected abstract dbSaveMessage(msg: ChatMessage): void;
 protected abstract dbClearAll(): void;
-
-// Stream metadata
-protected abstract dbFindActiveStream(): { 
-  id: string; 
-  messageId: string; 
-  createdAt: Date 
+protected abstract dbFindActiveStream(): {
+  id: string;
+  messageId: string;
+  createdAt: Date;
 } | null;
 protected abstract dbDeleteStreamWithChunks(streamId: string): void;
 protected abstract dbInsertStreamMetadata(streamId: string, messageId: string): void;
-protected abstract dbUpdateStreamStatus(streamId: string, status: 'completed' | 'error'): void;
+protected abstract dbUpdateStreamStatus(
+  streamId: string,
+  status: "completed" | "error",
+): void;
 protected abstract dbDeleteOldCompletedStreams(cutoffMs: number): void;
-
-// Stream chunks
 protected abstract dbFindMaxChunkIndex(streamId: string): number | null;
-protected abstract dbInsertChunks(chunks: Array<{ 
-  id: string; 
-  streamId: string; 
-  content: string; 
-  chunkIndex: number 
-}>): void;
+protected abstract dbInsertChunks(
+  chunks: Array<{
+    id: string;
+    streamId: string;
+    content: string;
+    chunkIndex: number;
+  }>,
+): void;
 protected abstract dbGetChunks(streamId: string): string[];
 protected abstract dbDeleteChunks(streamId: string): void;
+protected abstract dbIsStreamKnown(streamId: string): boolean;
+protected abstract dbReplaceAllMessages(messages: ChatMessage[]): void;
+protected abstract dbTrimMessagesToMax(maxMessages: number): void;
 ```
 
-### Override Methods
-
-Customize your agent's behavior:
+### Common overrides
 
 ```typescript
-protected getSystemPrompt(): string {
-  return "Your custom system prompt";
-}
-
-protected getModel(): string {
-  // Popular OpenRouter models:
-  // - anthropic/claude-opus-4.5 (most capable)
-  // - anthropic/claude-sonnet-4.5 (balanced, default)
-  // - anthropic/claude-haiku-3.5 (fastest, cheapest)
-  return "anthropic/claude-sonnet-4.5";
-}
-
-protected getTools(): ToolDefinition[] {
-  return [
-    // Your tools here
-  ];
-}
-```
-
-## DrizzleChatAgent
-
-Type-safe implementation using Drizzle ORM.
-
-### Database Schema
-
-The package provides three tables:
-
-```typescript
-// From @firtoz/chat-agent/db/schema
-
-export const messagesTable = sqliteTable("messages", {
-  id: text("id").primaryKey(),
-  role: text("role", { enum: ["user", "assistant", "tool"] }).notNull(),
-  messageJson: text("message_json").notNull(),
-  createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
-});
-
-export const streamChunksTable = sqliteTable("stream_chunks", {
-  id: text("id").primaryKey(),
-  streamId: text("stream_id").notNull(),
-  content: text("content").notNull(),
-  chunkIndex: integer("chunk_index").notNull(),
-  createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
-});
-
-export const streamMetadataTable = sqliteTable("stream_metadata", {
-  id: text("id").primaryKey(),
-  messageId: text("message_id").notNull(),
-  status: text("status", { enum: ["streaming", "completed", "error"] }).notNull(),
-  createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
-  completedAt: integer("completed_at", { mode: "timestamp_ms" }),
-});
-```
-
-### Implementation Details
-
-```typescript
-import { DrizzleChatAgent } from "@firtoz/chat-agent";
-
-// Automatically:
-// - Creates Drizzle DB instance in dbInitialize()
-// - Runs migrations from drizzle/migrations.js
-// - Uses type-safe query builder for all operations
-```
-
-## SqlChatAgent
-
-Raw SQL implementation following `@cloudflare/ai-chat` pattern.
-
-### Table Structure
-
-Creates these tables automatically:
-
-```sql
-CREATE TABLE IF NOT EXISTS cf_ai_chat_agent_messages (
-  id TEXT PRIMARY KEY,
-  message TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE IF NOT EXISTS cf_ai_chat_stream_chunks (
-  id TEXT PRIMARY KEY,
-  stream_id TEXT NOT NULL,
-  body TEXT NOT NULL,
-  chunk_index INTEGER NOT NULL,
-  created_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS cf_ai_chat_stream_metadata (
-  id TEXT PRIMARY KEY,
-  request_id TEXT NOT NULL,
-  status TEXT NOT NULL,
-  created_at INTEGER NOT NULL,
-  completed_at INTEGER
-);
-
-CREATE INDEX IF NOT EXISTS idx_stream_chunks_stream_id 
-  ON cf_ai_chat_stream_chunks(stream_id, chunk_index);
-```
-
-### Implementation Details
-
-```typescript
-import { SqlChatAgent } from "@firtoz/chat-agent";
-
-// Uses Agent's built-in this.sql template tag:
-// - this.sql`SELECT * FROM table WHERE id = ${id}`
-// - No additional dependencies
-// - Tables created automatically in dbInitialize()
+protected getSystemPrompt(): string { /* … */ }
+protected getModel(): string { /* … */ }
+protected getTools(): ToolDefinition[] { /* … */ }
 ```
 
 ## Tools
 
-### Server-Side Tools
+### Server-side
 
-Tools with `execute` function run on the server:
+`defineTool` with `execute` runs on the server; results are merged into the conversation.
 
-```typescript
-defineTool({
-  name: "get_weather",
-  description: "Get weather for a location",
-  parameters: {
-    type: "object",
-    properties: {
-      location: { type: "string" }
-    },
-    required: ["location"]
-  },
-  execute: async (args: { location: string }) => {
-    // Runs on server, result automatically added to conversation
-    const weather = await fetchWeather(args.location);
-    return { temperature: weather.temp, condition: weather.condition };
-  }
-})
-```
+### Client-side
 
-### Client-Side Tools
-
-Tools without `execute` are sent to client for execution:
-
-```typescript
-defineTool({
-  name: "get_user_location",
-  description: "Get user's browser location",
-  parameters: {
-    type: "object",
-    properties: {}
-  }
-  // No execute - client handles this via WebSocket
-})
-```
+Omit `execute`; tool calls are sent to the client over the WebSocket.
 
-## Environment Variables
+## Environment variables
 
 ```env
-# Required
 OPENROUTER_API_KEY=sk-or-...
-
 # Optional: Cloudflare AI Gateway
-CLOUDFLARE_ACCOUNT_ID=your-account-id
-AI_GATEWAY_NAME=your-gateway-name
-AI_GATEWAY_TOKEN=your-gateway-token
+CLOUDFLARE_ACCOUNT_ID=…
+AI_GATEWAY_NAME=…
+AI_GATEWAY_TOKEN=…
 ```
 
-## API Reference
+## Types (excerpt)
 
-### ChatMessage
+`UserMessage`, `AssistantMessage`, `ToolMessage`, `ToolCall`, `ClientMessage`, `ServerMessage`, etc. are exported from this package—import types from `@firtoz/chat-agent` only.
 
-```typescript
-type UserMessage = {
-  id: string;
-  role: "user";
-  content: string;
-  createdAt: number;
-};
+## Drizzle vs SQL
 
-type AssistantMessage = {
-  id: string;
-  role: "assistant";
-  content: string | null;
-  toolCalls?: ToolCall[];
-  createdAt: number;
-};
-
-type ToolMessage = {
-  id: string;
-  role: "tool";
-  toolCallId: string;
-  content: string;
-  createdAt: number;
-};
-```
-
-### ToolDefinition
-
-```typescript
-type ToolDefinition = {
-  type: "function";
-  function: {
-    name: string;
-    description?: string;
-    parameters?: JSONSchema;
-    strict?: boolean;
-  };
-  execute?: (args: any) => unknown | Promise<unknown>;
-};
-```
-
-## Features
-
-### Implemented
-
-- ✅ Message persistence (Drizzle or SQL)
-- ✅ Resumable streaming with chunk buffering
-- ✅ Stream restoration on reconnect
-- ✅ Request cancellation via AbortController
-- ✅ Server-side and client-side tools
-- ✅ Tool result handling with auto-continue
-- ✅ Cloudflare AI Gateway support
-- ✅ DB-agnostic architecture
-
-### Comparison: Drizzle vs SQL
-
-| Feature | DrizzleChatAgent | SqlChatAgent |
-|---------|-----------------|--------------|
-| Type Safety | ✅ Full type inference | ❌ Template string types only |
-| Setup Complexity | ⚠️ Requires migrations | ✅ Auto-creates tables |
-| Dependencies | Drizzle ORM + drizzle-kit | None (uses Agent.sql) |
-| Query Builder | ✅ Yes | ❌ Raw SQL only |
-| Performance | Same | Same |
-| Wrangler Config | ⚠️ Requires rules for .sql | ✅ No special config |
-| Recommended For | New projects, teams | Quick prototypes, SQL experts |
+| | Drizzle | SQL |
+|---|--------|-----|
+| Package | `@firtoz/chat-agent-drizzle` | `@firtoz/chat-agent-sql` |
+| Type safety | Full schema + query builder | Template SQL |
+| Setup | Migrations + Wrangler `.sql` rules | Auto-creates tables |
+| Best for | New projects | Prototypes / raw SQL |
 
 ## License
 
 MIT
-
-## Contributing
-
-PRs welcome!