@economic/agents 0.0.1-alpha.9 → 0.0.1-beta.2

package/README.md

@@ -1,87 +1,608 @@
 # @economic/agents
 
-Base classes and utilities for building LLM agents on Cloudflare's Agents SDK with lazy tool loading.
+Base class and utilities for building LLM chat agents on Cloudflare's Agents SDK with lazy skill loading, optional message compaction, and built-in audit logging.
 
-## Exports
+```bash
+npm install @economic/agents ai @cloudflare/ai-chat agents
+```
+
+For React UIs that import `@economic/agents/react`, also install `react`. It is an **optional** peer of the package so Workers-only installs are not required to add React. The hook still needs `agents`, `ai`, and `@cloudflare/ai-chat` at runtime (same as the Cloudflare SDK imports it wraps).
 
-- **`AIChatAgent`** — base class that owns the full `onChatMessage` lifecycle. Implement `getModel()`, `getTools()`, `getSkills()`, and `getSystemPrompt()`. Compaction is **enabled by default** (uses `getModel()` for summarisation).
-- **`AIChatAgentBase`** — base class for when you need full control over `streamText`. Implement `getTools()`, `getSkills()`, and your own `onChatMessage` decorated with `@withSkills`. Compaction is **disabled by default**.
-- **`withSkills`** — method decorator used with `AIChatAgentBase`.
-- **`createSkills`** — lower-level factory for wiring lazy skill loading into any agent subclass yourself.
-- **`filterEphemeralMessages`**, **`injectGuidance`** — utilities used internally, exported for custom wiring.
-- **`compactIfNeeded`**, **`compactMessages`**, **`estimateMessagesTokens`**, **`COMPACT_TOKEN_THRESHOLD`** — compaction utilities, exported for use with `AIChatAgentBase` or fully custom agents.
-- Types: `Tool`, `Skill`, `SkillsConfig`, `SkillsResult`, `SkillContext`.
+---
 
-See [COMPARISON.md](./COMPARISON.md) for a side-by-side code example of both base classes.
+## Overview
 
-See [src/features/skills/README.md](./src/features/skills/README.md) for full `createSkills` documentation.
+`@economic/agents` provides:
 
-## Development
+- **`AIChatAgent`** — an abstract Cloudflare Durable Object base class. Implement `onChatMessage`, call `this.buildLLMParams()`, and pass the result to `streamText` from the AI SDK.
+- **`guard`** — optional TypeScript 5+ method decorator for `onChatMessage`. Runs your function with `options.body`; return a `Response` to short-circuit (e.g. auth), or nothing to continue.
+- **`buildLLMParams`** — the standalone version of the above, for use outside of `AIChatAgent` or in custom agent implementations.
+- **`useAIChatAgent`** (subpath `@economic/agents/react`) — React hook that wraps `useAgent` (`agents/react`) and `useAgentChat` (`@cloudflare/ai-chat/react`). Connection status is **callback-only** (`onConnectionStatusChange`). On WebSocket close codes **`>= 3000`**, the hook calls `agent.close()` to stop reconnection, then forwards `onClose` (use `event.reason` for the server message). Pass-through **`onOpen`**, **`onClose`**, **`onError`** are supported.
 
-```bash
-vp install   # install dependencies
-vp test      # run tests
-vp pack      # build
+Skills and compaction are AI SDK concerns — they control what goes to the LLM. The CF layer is responsible for WebSockets, Durable Objects, and message persistence. These are kept separate.
+
+### React client
+
+```typescript
+import { useAIChatAgent, type AgentConnectionStatus } from "@economic/agents/react";
+import { useState } from "react";
+
+const [connectionStatus, setConnectionStatus] = useState<AgentConnectionStatus>("connecting");
+
+const { agent, chat } = useAIChatAgent({
+  agent: "MyAgent",
+  host: "localhost:8787",
+  chatId: "session-id",
+  toolContext: {},
+  connectionParams: { userId: "…" },
+  onConnectionStatusChange: setConnectionStatus,
+  onOpen: (event) => {},
+  onClose: (event) => {},
+  onError: (event) => {},
+});
+
+const { messages, sendMessage, status, stop } = chat;
 ```
 
----
+Server-side agent code still imports only from `@economic/agents`; the `/react` entry is a separate build output and does not pull Workers runtime code into the client bundle.
 
-## Implementing your own agent
+---
 
-Extend `AIChatAgent` and implement the four required methods:
+## Quick start
 
 ```typescript
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { tool } from "ai";
+import { z } from "zod";
 import { AIChatAgent } from "@economic/agents";
+import type { Skill } from "@economic/agents";
 
-export class MyAgent extends AIChatAgent {
-  getModel() {
-    return openai("gpt-4o");
-  }
-  getTools() {
-    return [myAlwaysOnTool];
+const searchSkill: Skill = {
+  name: "search",
+  description: "Web search tools",
+  guidance: "Use search_web for any queries requiring up-to-date information.",
+  tools: {
+    search_web: tool({
+      description: "Search the web",
+      inputSchema: z.object({ query: z.string() }),
+      execute: async ({ query }) => `Results for: ${query}`,
+    }),
+  },
+};
+
+export class MyAgent extends AIChatAgent<Env> {
+  // Set fastModel to enable automatic compaction and future background summarization.
+  protected fastModel = openai("gpt-4o-mini");
+
+  async onChatMessage(onFinish, options) {
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
+      model: openai("gpt-4o"),
+      system: "You are a helpful assistant.",
+      skills: [searchSkill],
+    });
+    return streamText(params).toUIMessageStreamResponse();
   }
-  getSkills() {
-    return [searchSkill, codeSkill];
+}
+```
+
+No D1 database needed — skill state is persisted to Durable Object SQLite automatically.
+
+---
+
+## Prerequisites
+
+### Cloudflare environment
+
+Your agent class is a Durable Object. Declare it in `wrangler.jsonc`:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
+}
+```
+
+Run `wrangler types` after to generate typed `Env` bindings.
+
+---
+
+## `AIChatAgent`
+
+Extend this class and implement `onChatMessage`. Call `this.buildLLMParams()` to prepare the call, then pass the result to `streamText` or `generateText`.
+
+```typescript
+import { streamText } from "ai";
+import { AIChatAgent } from "@economic/agents";
+
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish, options) {
+    const body = (options?.body ?? {}) as { userTier: "free" | "pro" };
+    const model = body.userTier === "pro" ? openai("gpt-4o") : openai("gpt-4o-mini");
+
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
+      model,
+      system: "You are a helpful assistant.",
+      skills: [searchSkill, calcSkill], // available for on-demand loading
+      tools: { alwaysOnTool }, // always active, regardless of loaded skills
+    });
+    return streamText(params).toUIMessageStreamResponse();
   }
-  getSystemPrompt() {
-    return "You are a helpful assistant.";
+}
+```
+
+### `this.buildLLMParams(config)`
+
+Protected method on `AIChatAgent`. Wraps the standalone `buildLLMParams` function with:
+
+- `messages` pre-filled from `this.messages`
+- `activeSkills` pre-filled from `await this.getLoadedSkills()`
+- `fastModel` injected from `this.fastModel`
+- `log` injected into `experimental_context` alongside `options.body`
+- Automatic error logging for non-clean finish reasons
+- Compaction threshold defaulting: when `maxMessagesBeforeCompaction` is not in the config, defaults to `30`. Pass `maxMessagesBeforeCompaction: undefined` explicitly to disable compaction.
+
+Config is everything accepted by the standalone `buildLLMParams` except `messages`, `activeSkills`, and `fastModel`.
+
+### `guard`
+
+Method decorator (TypeScript 5+ stage-3) for handlers shaped like `onChatMessage(onFinish, options?)`. Before your method runs, it calls your `GuardFn` with `options?.body` (the same custom body the client sends via `useAgentChat` / `body` on the chat request).
+
+- Return **`undefined` / nothing** — the decorated method runs as usual.
+- Return a **`Response`** — that response is returned immediately; `onChatMessage` is not called.
+
+All policy (tokens, tiers, rate limits) lives in the guard function; the decorator only forwards `body` and branches on whether a `Response` was returned.
+
+```typescript
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { AIChatAgent, guard, type GuardFn } from "@economic/agents";
+
+const requireToken: GuardFn = async (body) => {
+  const token = body?.token;
+  if (typeof token !== "string" || !(await isValidToken(token))) {
+    return new Response("Unauthorized", { status: 401 });
   }
+};
 
-  // Return the D1 binding — typed in Cloudflare.Env after `wrangler types`
-  protected getDB() {
-    return this.env.AGENT_DB;
+export class ChatAgent extends AIChatAgent<Env> {
+  protected fastModel = openai("gpt-4o-mini");
+
+  @guard(requireToken)
+  async onChatMessage(onFinish, options) {
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
+      model: openai("gpt-4o"),
+      system: "You are a helpful assistant.",
+    });
+    return streamText(params).toUIMessageStreamResponse();
   }
 }
 ```
 
-If you need control over the response — custom model options, middleware, varying the model per request — use `AIChatAgentBase` with the `@withSkills` decorator instead. See [COMPARISON.md](./COMPARISON.md) for a side-by-side example and `src/features/skills/README.md` for full `createSkills` documentation.
+### `fastModel` property
+
+Override `fastModel` on your subclass to enable automatic compaction and future background conversation summarization:
+
+```typescript
+export class MyAgent extends AIChatAgent<Env> {
+  protected fastModel = openai("gpt-4o-mini");
+  // ...
+}
+```
+
+When `fastModel` is set, compaction runs automatically with a default threshold of 30 messages. No per-call configuration is needed in the common case. You can still customise or disable it per-call via `maxMessagesBeforeCompaction`.
 
-### Message compaction
+When `fastModel` is `undefined` (the default), compaction is disabled regardless of `maxMessagesBeforeCompaction`.
 
-`AIChatAgent` automatically compacts the conversation history when it approaches the token limit (140k tokens). Older messages are summarised by the LLM into a single system message; the most recent messages are kept verbatim. The verbatim tail size is `maxPersistedMessages - 1` (default: 49 messages + 1 summary message).
+### `getConversations` (callable)
 
-The compaction model defaults to `getModel()`. To use a cheaper model for summarisation, override `getCompactionModel()`:
+`AIChatAgent` exposes a [callable method](https://developers.cloudflare.com/agents/api-reference/callable-methods/) via the Agents SDK `@callable()` decorator (`agents` package). From any connected client (for example the object returned by `useAgent` / `useAIChatAgent`), invoke:
 
 ```typescript
-protected override getCompactionModel(): LanguageModel {
-  return openai("gpt-4o-mini"); // cheaper model for summarisation
-}
+const rows = await agent.call("getConversations");
 ```
 
-To disable compaction entirely, override `getCompactionModel()` to return `undefined`:
+- **User scope**: `userId` is taken from the segment before the first `:` in the Durable Object name (`userId:chatId`), the same format enforced in `onConnect`.
+- **Data**: Reads from `AGENT_DB`, returning all `conversations` rows whose `durable_object_name` matches `userId:%`, ordered by `updated_at` descending (newest first). Each row includes `durable_object_name`, `title`, `summary`, `created_at`, and `updated_at`.
+- **No D1**: If `AGENT_DB` is not bound, the method returns `undefined` and does not throw.
+
+### `getLoadedSkills()`
+
+Protected method on `AIChatAgent`. Returns skill names persisted from previous turns (read from DO SQLite). Used internally by `this.buildLLMParams()`.
+
+### `persistMessages` (automatic)
+
+When `persistMessages` runs at the end of each turn, it:
+
+1. Scans `activate_skill` tool results for newly loaded skill state.
+2. Writes the updated skill name list to DO SQLite (no D1 needed).
+3. Logs a turn summary via `log()`.
+4. Strips all `activate_skill` and `list_capabilities` messages from history.
+5. Delegates to the CF base `persistMessages` for message storage and WS broadcast.
+
+### `onConnect` (automatic)
+
+Replays the full message history to newly connected clients — without this, a page refresh would show an empty UI even though history is in DO SQLite.
+
+---
+
+## `buildLLMParams` (standalone)
+
+The standalone `buildLLMParams` builds the full parameter object for a Vercel AI SDK `streamText` or `generateText` call. Use this directly only if you are not extending `AIChatAgent`, or need fine-grained control.
+
+```typescript
+import { buildLLMParams } from "@economic/agents";
+
+const params = await buildLLMParams({
+  options, // OnChatMessageOptions — extracts abortSignal and body
+  onFinish, // StreamTextOnFinishCallback<ToolSet>
+  model, // LanguageModel
+  messages: this.messages, // UIMessage[] — converted to ModelMessage[] internally
+  activeSkills: await this.getLoadedSkills(),
+  system: "You are a helpful assistant.",
+  skills: [searchSkill, codeSkill],
+  tools: { myAlwaysOnTool },
+  stopWhen: stepCountIs(20), // defaults to stepCountIs(20)
+});
+
+return streamText(params).toUIMessageStreamResponse();
+// or: generateText(params);
+```
+
+| Parameter                     | Type                                  | Required | Description                                                                                       |
+| ----------------------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `options`                     | `OnChatMessageOptions \| undefined`   | Yes      | CF options object. Extracts `abortSignal` and `experimental_context`.                             |
+| `onFinish`                    | `StreamTextOnFinishCallback<ToolSet>` | Yes      | Called when the stream completes.                                                                 |
+| `model`                       | `LanguageModel`                       | Yes      | The language model to use.                                                                        |
+| `messages`                    | `UIMessage[]`                         | Yes      | Conversation history. Converted to `ModelMessage[]` internally.                                   |
+| `activeSkills`                | `string[]`                            | No       | Names of skills loaded in previous turns. Pass `await this.getLoadedSkills()`.                    |
+| `skills`                      | `Skill[]`                             | No       | Skills available for on-demand loading. Wires up meta-tools automatically.                        |
+| `system`                      | `string`                              | No       | Base system prompt.                                                                               |
+| `tools`                       | `ToolSet`                             | No       | Always-on tools, active every turn regardless of loaded skills.                                   |
+| `maxMessagesBeforeCompaction` | `number \| undefined`                 | No       | Verbatim tail kept during compaction. Defaults to `30` when omitted. Pass `undefined` to disable. |
+| `stopWhen`                    | `StopCondition`                       | No       | Stop condition. Defaults to `stepCountIs(20)`.                                                    |
+
+When `skills` are provided, `buildLLMParams`:
+
+- Registers `activate_skill` and `list_capabilities` meta-tools.
+- Sets initial `activeTools` (meta + always-on + loaded skill tools).
+- Wires up `prepareStep` to update `activeTools` after each step.
+- Composes `system` with guidance from loaded skills.
+
+---
+
+## Defining skills
+
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+import type { Skill } from "@economic/agents";
+
+// Skill with guidance — injected into the system prompt when the skill is loaded
+export const calculatorSkill: Skill = {
+  name: "calculator",
+  description: "Mathematical calculation and expression evaluation",
+  guidance:
+    "Use the calculate tool for any arithmetic or algebraic expressions. " +
+    "Always show the expression you are evaluating.",
+  tools: {
+    calculate: tool({
+      description: "Evaluate a mathematical expression and return the result.",
+      inputSchema: z.object({
+        expression: z.string().describe('e.g. "2 + 2", "Math.sqrt(144)"'),
+      }),
+      execute: async ({ expression }) => {
+        const result = new Function(`"use strict"; return (${expression})`)();
+        return `${expression} = ${result}`;
+      },
+    }),
+  },
+};
+
+// Skill without guidance — tools are self-explanatory
+export const datetimeSkill: Skill = {
+  name: "datetime",
+  description: "Current date and time information in any timezone",
+  tools: {
+    get_current_datetime: tool({
+      description: "Get the current date and time in an optional IANA timezone.",
+      inputSchema: z.object({
+        timezone: z.string().optional().describe('e.g. "Europe/Copenhagen"'),
+      }),
+      execute: async ({ timezone = "UTC" }) =>
+        new Date().toLocaleString("en-GB", {
+          timeZone: timezone,
+          dateStyle: "full",
+          timeStyle: "long",
+        }),
+    }),
+  },
+};
+```
+
+### `Skill` fields
+
+| Field         | Type      | Required | Description                                                                  |
+| ------------- | --------- | -------- | ---------------------------------------------------------------------------- |
+| `name`        | `string`  | Yes      | Unique identifier used by `activate_skill` and for DO SQLite persistence.    |
+| `description` | `string`  | Yes      | One-line description shown in the `activate_skill` schema.                   |
+| `guidance`    | `string`  | No       | Instructions appended to the `system` prompt when this skill is loaded.      |
+| `tools`       | `ToolSet` | Yes      | Record of tool names to `tool()` definitions. Names must be globally unique. |
+
+---
+
+## Compaction
+
+When `fastModel` is set on the agent class, compaction runs automatically before each turn:
+
+1. The message list is split into an older window and a recent verbatim tail.
+2. `fastModel` generates a concise summary of the older window.
+3. That summary + the verbatim tail is what gets sent to the LLM.
+4. Full history in DO SQLite is unaffected — compaction is in-memory only.
+
+### Enabling compaction
+
+Override `fastModel` on your subclass. Compaction runs automatically with a default threshold of 30 messages — no per-call config needed:
 
 ```typescript
-protected override getCompactionModel(): LanguageModel | undefined {
-  return undefined; // no compaction — older messages are dropped at maxPersistedMessages
+export class MyAgent extends AIChatAgent<Env> {
+  protected fastModel = openai("gpt-4o-mini");
+
+  async onChatMessage(onFinish, options) {
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
+      model: openai("gpt-4o"),
+      system: "...",
+      // No compaction config needed — runs automatically with default threshold
+    });
+    return streamText(params).toUIMessageStreamResponse();
+  }
 }
 ```
 
-`AIChatAgentBase` does not enable compaction by default. To add it, override `getCompactionModel()` to return a model — the `persistMessages` override will pick it up automatically:
+### Customising the threshold
+
+Pass `maxMessagesBeforeCompaction` to override the default of 30:
+
+```typescript
+const params = await this.buildLLMParams({
+  options,
+  onFinish,
+  model: openai("gpt-4o"),
+  maxMessagesBeforeCompaction: 50, // keep last 50 messages verbatim
+});
+```
+
+### Disabling compaction
+
+Pass `maxMessagesBeforeCompaction: undefined` explicitly to disable compaction for that call, even when `fastModel` is set:
 
 ```typescript
-protected override getCompactionModel(): LanguageModel {
-  return openai("gpt-4o-mini");
+const params = await this.buildLLMParams({
+  options,
+  onFinish,
+  model: openai("gpt-4o"),
+  maxMessagesBeforeCompaction: undefined, // compaction off
+});
+```
+
+Compaction is always off when `fastModel` is `undefined` (the base class default).
+
+---
+
+## Built-in meta tools
+
+Two meta tools are automatically registered when `skills` are provided. You do not need to define or wire them.
+
+### `activate_skill`
+
+Loads one or more skills by name, making their tools available for the rest of the conversation. The LLM calls this when it needs capabilities it does not currently have.
+
+- Loading is idempotent — calling for an already-loaded skill is a no-op.
+- The skills available are exactly those passed as `skills` — filter by request body to control access.
+- When skills are successfully loaded, the new state is embedded in the tool result. `persistMessages` extracts it and writes to DO SQLite.
+- All `activate_skill` messages are stripped from history before persistence — state is restored from DO SQLite, not from message history.
+
+### `list_capabilities`
+
+Returns a summary of active tools, loaded skills, and skills available to load. Always stripped from history before persistence.
+
+---
+
+## Passing request context to tools
+
+Pass arbitrary data via the `body` option of `useAgentChat`. It arrives as `experimental_context` in tool `execute` functions.
+
+When using `this.buildLLMParams()`, the context is automatically composed: your body fields plus a `log` function for writing audit events. Use `AgentContext<TBody>` to type it:
+
+```typescript
+// types.ts
+import type { AgentContext } from "@economic/agents";
+
+interface AgentBody {
+  authorization: string;
+  userId: string;
 }
+
+export type ToolContext = AgentContext<AgentBody>;
+```
+
+```typescript
+// Client
+useAgentChat({ body: { authorization: token, userId: "u_123" } });
+
+// Tool
+execute: async (args, { experimental_context }) => {
+  const ctx = experimental_context as ToolContext;
+  await ctx.log("tool called", { userId: ctx.userId });
+  const data = await fetchSomething(ctx.authorization);
+  return data;
+};
+```
+
+`log` is a no-op when `AGENT_DB` is not bound — so no changes are needed in tools when running without a D1 database.
+
+---
+
+## Audit logging — D1 setup
+
+`AIChatAgent` writes audit events to a Cloudflare D1 database when `AGENT_DB` is bound on the environment. Each agent worker has its own dedicated D1 database.
+
+### 1. Create the D1 database
+
+In the [Cloudflare dashboard](https://dash.cloudflare.com) → **Workers & Pages** → **D1** → **Create database**. Note the database name and ID.
+
+### 2. Create the schema
+
+Open the database in the D1 dashboard, select **Console**, and run the contents of [`schema/schema.sql`](schema/schema.sql) — this creates both the `audit_events` and `conversations` tables in one step:
+
+```sql
+CREATE TABLE IF NOT EXISTS audit_events (
+  id                TEXT PRIMARY KEY,
+  durable_object_id TEXT NOT NULL,
+  user_id           TEXT NOT NULL,
+  message           TEXT NOT NULL,
+  payload           TEXT,
+  created_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS audit_events_user ON audit_events(user_id);
+CREATE INDEX IF NOT EXISTS audit_events_do   ON audit_events(durable_object_id);
+CREATE INDEX IF NOT EXISTS audit_events_ts   ON audit_events(created_at);
+
+CREATE TABLE IF NOT EXISTS conversations (
+  durable_object_id TEXT PRIMARY KEY,
+  user_id           TEXT NOT NULL,
+  title             TEXT,
+  summary           TEXT,
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS conversations_user ON conversations(user_id);
+CREATE INDEX IF NOT EXISTS conversations_ts   ON conversations(updated_at);
+```
+
+Safe to re-run — all statements use `IF NOT EXISTS`.
+
+### 3. Bind it in `wrangler.jsonc`
+
+```jsonc
+"d1_databases": [
+  { "binding": "AGENT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
+]
+```
+
+Then run `wrangler types` to regenerate the `Env` type.
+
+### 4. Seed local development
+
+```bash
+npm run db:setup
+```
+
+This runs the schema SQL against the local D1 SQLite file (`.wrangler/state/`). Re-running is harmless.
+
+If `AGENT_DB` is not bound, all `log()` calls are silent no-ops — the agent works without it.
+
+### Providing `userId`
+
+The `user_id` column is `NOT NULL`. The base class reads `userId` automatically from `options.body` — no subclass override is needed. The client must include it in the `body` passed to `useAgentChat`:
+
+```typescript
+useAgentChat({
+  agent,
+  body: {
+    userId: "148583_matt", // compose from agreement number + user identifier
+    // ...other fields
+  },
+});
 ```
 
-Alternatively, import `compactIfNeeded` and `COMPACT_TOKEN_THRESHOLD` from `@economic/agents` and call them yourself inside a custom `persistMessages` override for full control over the compaction logic.
+If the client omits `userId`, the audit insert is skipped and a `console.error` is emitted. This will be visible in Wrangler's output during local development and in Workers Logs in production.
+
+---
+
+## Conversations — D1 setup
+
+`AIChatAgent` maintains a `conversations` table in `AGENT_DB` alongside `audit_events`. One row is kept per Durable Object instance (i.e. per conversation). The row is upserted automatically after every turn — no subclass code needed.
+
+The `conversations` table is created by the same `schema/schema.sql` file used for audit events — no separate setup step needed.
+
+### Upsert behaviour
+
+- **First turn**: a new row is inserted with `created_at` and `updated_at` both set to now. `title` and `summary` are `NULL`.
+- **Subsequent turns**: only `user_id` and `updated_at` are updated. `created_at`, `title`, and `summary` are never overwritten by the upsert.
+- `title` and `summary` are populated automatically after the conversation goes idle (see below).
+
+### Automatic title and summary generation
+
+After every turn, `AIChatAgent` schedules a `generateSummary` callback to fire 30 minutes in the future. If another message arrives before the timer fires, the schedule is cancelled and reset — so the callback only runs once the conversation has been idle for 30 minutes.
+
+When `generateSummary` fires it:
+
+1. Fetches the current summary from D1 (if any).
+2. Takes the last 30 messages (`SUMMARY_CONTEXT_MESSAGES`) to keep the prompt bounded.
+3. Calls `fastModel` with `Output.object()` to generate a structured `{ title, summary }`.
+4. If a previous summary exists, it is included in the prompt so the model can detect direction changes.
+5. Writes the result back to the `conversations` row.
+
+No subclass code is needed — this runs automatically when `AGENT_DB` is bound and `fastModel` is set on the class.
+
+### Querying conversation lists
+
+From a connected agent client, prefer the built-in callable (see **`getConversations` (callable)** under [`AIChatAgent`](#aichatagent)): `await agent.call("getConversations")`.
+
+To query D1 directly (same logic as the callable), filter by `durable_object_name` prefix — one row per chat, keyed as `userId:chatId`:
+
+```sql
+SELECT durable_object_name, title, summary, created_at, updated_at
+FROM conversations
+WHERE durable_object_name LIKE '148583_matt:%'
+ORDER BY updated_at DESC;
+```
+
+If `userId` is not set on the request body, the upsert is skipped and a `console.error` is emitted — the same behaviour as audit logging.
+
+---
+
+## API reference
+
+### Classes
+
+| Export        | Description                                                                                                                                                                                                                               |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state, history replay, audit log, and D1 `conversations` upserts. Exposes callable `getConversations` for listing a user’s conversations from the client. |
+
+### Functions
+
+| Export           | Signature                              | Description                                                                                            |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `guard`          | `(guardFn: GuardFn)`                   | Method decorator: runs `guardFn` with `options.body`; a returned `Response` short-circuits the method. |
+| `buildLLMParams` | `async (config) => Promise<LLMParams>` | Builds the full parameter object for `streamText` or `generateText`.                                   |
+
+### Types
+
+| Export                 | Description                                                                                                      |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `GuardFn`              | `(body) => Response \| void \| Promise<...>`. Receives chat request `body`; return `Response` to block the turn. |
+| `Skill`                | A named group of tools with optional guidance.                                                                   |
+| `AgentContext<TBody>`  | Request body type merged with `log`. Use as the type of `experimental_context`.                                  |
+| `BuildLLMParamsConfig` | Config type for the standalone `buildLLMParams` function.                                                        |
+
+---
+
+## Development
+
+```bash
+npm install   # install dependencies
+npm test      # run tests
+npm pack      # build
+```