@economic/agents 0.0.1 → 1.0.0

package/README.md

@@ -1,62 +1,26 @@
 # @economic/agents
 
-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.
+A batteries-included toolkit for building AI agents on Cloudflare Workers. Provides Durable Object base classes for both chat and non-chat agents, with on-demand skill loading, automatic message compaction, conversation management, and audit logging to D1.
 
-```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).
-
----
-
-## Overview
-
-`@economic/agents` provides:
-
-- **`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.
+For chat agents, extend `ChatAgentHarness` (recommended) or `ChatAgent` (lower-level). For headless agents, extend `Agent`.
 
-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.
+For React integration, see [`@economic/agents-react`](../react/README.md).
 
-### React client
+## Install
 
-```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;
+```sh
+npm install @economic/agents @cloudflare/ai-chat ai agents
 ```
 
-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.
-
----
+## Quick Start
 
-## Quick start
+### Server
 
 ```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";
+import { ChatAgentHarness, type AgentToolContext, type Skill } from "@economic/agents";
 
 const searchSkill: Skill = {
   name: "search",
@@ -71,32 +35,28 @@ const searchSkill: Skill = {
   },
 };
 
-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();
+export class MyAgent extends ChatAgentHarness<Env> {
+  getModel(ctx: AgentToolContext) {
+    return openai("gpt-4o");
   }
-}
-```
 
-No D1 database needed — skill state is persisted to Durable Object SQLite automatically.
+  getFastModel() {
+    return openai("gpt-4o-mini");
+  }
 
----
+  getSystemPrompt(ctx: AgentToolContext) {
+    return "You are a helpful assistant.";
+  }
 
-## Prerequisites
+  getSkills(ctx: AgentToolContext) {
+    return [searchSkill];
+  }
+}
+```
 
-### Cloudflare environment
+For lower-level control (custom `onChatMessage` implementations), extend `ChatAgent` directly — see [ChatAgent](#chatagent).
 
-Your agent class is a Durable Object. Declare it in `wrangler.jsonc`:
+### Wrangler Config
 
 ```jsonc
 {
@@ -109,184 +69,234 @@ Your agent class is a Durable Object. Declare it in `wrangler.jsonc`:
 
 Run `wrangler types` after to generate typed `Env` bindings.
 
+### 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: "user_123:session-1",
+  toolContext: {},
+  connectionParams: { userId: "…" },
+  onConnectionStatusChange: setConnectionStatus,
+});
+
+const { messages, sendMessage, status, stop } = chat;
+```
+
+`chatId` is the Durable Object name — use `userId:uniqueChatId` (see [Providing userId](#providing-userid)).
+
+> **Note:** React hooks are in a separate package. Install with `npm install @economic/agents-react`.
+
 ---
 
-## `AIChatAgent`
+## Harnesses
+
+The server-side API is built around Durable Object base classes — `Agent` for headless workflows and `ChatAgent`/`ChatAgentHarness` for conversational UIs — plus a skill system that lets the LLM load tools on demand.
+
+### ChatAgentHarness
 
-Extend this class and implement `onChatMessage`. Call `this.buildLLMParams()` to prepare the call, then pass the result to `streamText` or `generateText`.
+The recommended starting point for chat agents. Extends `ChatAgent` with an opinionated structure: implement abstract methods for model selection, system prompt, tools, and skills. The harness handles `onChatMessage` for you.
 
 ```typescript
-import { streamText } from "ai";
-import { AIChatAgent } from "@economic/agents";
+import { openai } from "@ai-sdk/openai";
+import { ChatAgentHarness, type AgentToolContext, type Skill } 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");
+interface RequestBody {
+  userTier: "free" | "pro";
+}
 
-    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();
+export class MyAgent extends ChatAgentHarness<Env, RequestBody> {
+  getModel(ctx: AgentToolContext<RequestBody>) {
+    return ctx.userTier === "pro" ? openai("gpt-4o") : openai("gpt-4o-mini");
+  }
+
+  getFastModel() {
+    return openai("gpt-4o-mini");
+  }
+
+  getSystemPrompt(ctx: AgentToolContext<RequestBody>) {
+    return "You are a helpful assistant.";
+  }
+
+  getTools(ctx: AgentToolContext<RequestBody>) {
+    return { myTool };
+  }
+
+  getSkills(ctx: AgentToolContext<RequestBody>) {
+    return [searchSkill, calculatorSkill];
   }
 }
 ```
 
-### `this.buildLLMParams(config)`
+- `getModel(ctx)` — returns the primary language model. Context includes request body for tier-based model selection.
+- `getFastModel()` — returns a fast/cheap model for compaction and conversation summarization.
+- `getSystemPrompt(ctx)` — returns the system prompt.
+- `getTools(ctx)` — returns always-on tools (optional, defaults to `{}`).
+- `getSkills(ctx)` — returns skills available for on-demand loading (optional, defaults to `[]`).
+- `conversationRetentionDays` — defaults to 90. Set to `undefined` to disable auto-deletion.
 
-Protected method on `AIChatAgent`. Wraps the standalone `buildLLMParams` function with:
+#### Binding Name
 
-- `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.
+`ChatAgentHarness` automatically derives the Durable Object binding name from the class name. **The binding name in your `wrangler.jsonc` must exactly match your class name:**
 
-Config is everything accepted by the standalone `buildLLMParams` except `messages`, `activeSkills`, and `fastModel`.
+```typescript
+// Class name is "MyAgent"
+export class MyAgent extends ChatAgentHarness<Env> {
+  /* ... */
+}
+```
 
-### `guard`
+```jsonc
+// wrangler.jsonc — binding name must be "MyAgent" to match
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
+  },
+}
+```
+
+If the names don't match, the harness won't be able to resolve the binding and will throw at runtime. If you need a different binding name, override the `binding` getter:
+
+````typescript
+export class MyAgent extends ChatAgentHarness<Env> {
+  protected get binding() {
+    return this.env.CUSTOM_BINDING_NAME;
+  }
+  // ...
+}
 
-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.
+### ChatAgent
 
-All policy (tokens, tiers, rate limits) lives in the guard function; the decorator only forwards `body` and branches on whether a `Response` was returned.
+Lower-level base class for chat agents. Use when you need full control over `onChatMessage` — custom streaming, multiple LLM calls per turn, or non-standard response formats.
 
 ```typescript
 import { streamText } from "ai";
 import { openai } from "@ai-sdk/openai";
-import { AIChatAgent, guard, type GuardFn } from "@economic/agents";
+import { ChatAgent } 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 });
+export class MyAgent extends ChatAgent<Env> {
+  protected get binding() {
+    return this.env.MyAgent;
   }
-};
 
-export class ChatAgent extends AIChatAgent<Env> {
-  protected fastModel = openai("gpt-4o-mini");
+  protected getFastModel() {
+    return 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.",
+      skills: [searchSkill],
+      tools: { alwaysOnTool },
     });
     return streamText(params).toUIMessageStreamResponse();
   }
 }
-```
+````
 
-### `fastModel` property
+- `binding` — abstract getter returning the DO namespace binding. Required on every subclass.
+- `getFastModel()` — abstract method returning the fast model for compaction and summarization.
+- `maxMessagesBeforeCompaction` — class property to override the default threshold (15). Set to `undefined` to disable.
+- `conversationRetentionDays` — class property to auto-delete inactive conversations after N days.
+- `this.buildLLMParams()` — pre-fills `messages`, `activeSkills`, and injects `logEvent` into `experimental_context`.
+- `getConversations()` / `deleteConversation(id)` — callable methods for listing/deleting a user's conversations.
 
-Override `fastModel` on your subclass to enable automatic compaction and future background conversation summarization:
+---
+
+### Agent
+
+Abstract Durable Object base for non-chat agents. Use for headless workflows driven from HTTP handlers, schedules, or alarms.
 
 ```typescript
-export class MyAgent extends AIChatAgent<Env> {
-  protected fastModel = openai("gpt-4o-mini");
-  // ...
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { callable } from "agents";
+import { Agent } from "@economic/agents";
+
+export class MyAgent extends Agent<Env> {
+  @callable
+  async summarize(document: string) {
+    const params = await this.buildLLMParams({
+      model: openai("gpt-4o"),
+      messages: [{ role: "user", content: `Summarise: ${document}` }],
+      system: "You are a helpful assistant.",
+      skills: [searchSkill],
+    });
+    const result = await generateText(params);
+    return result.text;
+  }
 }
 ```
 
-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`.
+- `this.buildLLMParams()` pre-fills `activeSkills` from DO SQLite and injects `logEvent` into `experimental_context`.
+- `this.logEvent(message, payload?)` writes audit events to D1 when `AGENT_DB` is bound, silent no-op otherwise.
 
-When `fastModel` is `undefined` (the default), compaction is disabled regardless of `maxMessagesBeforeCompaction`.
+---
 
-### `getConversations` (callable)
+### Tool context
 
-`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:
+Pass data via the `body` option of `useAgentChat` (with `useAIChatAgent`, use `toolContext` — it is forwarded as `body`). It arrives as `experimental_context` in tool `execute` functions. Use `AgentToolContext<TBody>` to type it:
 
 ```typescript
-const rows = await agent.call("getConversations");
-```
-
-- **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()`
+import type { AgentToolContext } from "@economic/agents";
 
-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:
+interface AgentBody {
+  authorization: string;
+  userId: string;
+}
 
-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.
+type ToolContext = AgentToolContext<AgentBody>;
 
-### `onConnect` (automatic)
+// Tool
+execute: async (args, { experimental_context }) => {
+  const ctx = experimental_context as ToolContext;
+  await ctx.logEvent("tool called", { userId: ctx.userId });
+  return await fetchSomething(ctx.authorization);
+};
+```
 
-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.
+`logEvent` is a no-op when `AGENT_DB` is not bound.
 
 ---
 
-## `buildLLMParams` (standalone)
+### Source URLs from Tools
 
-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.
+Any tool can surface source URLs into the message stream by including a `sources` array in its return value. Detected automatically by `buildLLMParams` — no additional wiring needed.
 
 ```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);
+execute: async ({ query }) => {
+  const data = await fetchResults(query);
+  return {
+    results: data.results,
+    sources: data.results.map((r) => ({ url: r.url, title: r.title })),
+  };
+};
 ```
 
-| 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.
+Each source entry: `{ url: string, title?: string }`.
 
 ---
 
-## Defining skills
+### Skills
+
+Named groups of tools loaded on demand by the LLM. The agent starts with only always-on tools active. When the LLM needs more, it calls `activate_skill`.
 
 ```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",
@@ -295,7 +305,7 @@ export const calculatorSkill: Skill = {
     "Always show the expression you are evaluating.",
   tools: {
     calculate: tool({
-      description: "Evaluate a mathematical expression and return the result.",
+      description: "Evaluate a mathematical expression",
       inputSchema: z.object({
         expression: z.string().describe('e.g. "2 + 2", "Math.sqrt(144)"'),
       }),
@@ -306,343 +316,227 @@ export const calculatorSkill: Skill = {
     }),
   },
 };
-
-// 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
+When `skills` are provided to `buildLLMParams`, two meta-tools are registered automatically:
 
-| 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. |
+- **`activate_skill`** — loads skills by name, making their tools available for the rest of the conversation. Idempotent. State is persisted to DO SQLite.
+- **`list_capabilities`** — returns active tools, loaded skills, and skills available to load.
 
----
-
-## Surfacing source URLs from tools
-
-Any tool can surface source URLs into the message stream by including a `sources` array in its return value. `buildLLMParams` automatically detects this and emits `source-url` stream parts that the playground's Sources block renders.
-
-```typescript
-execute: async ({ query }) => {
-  const data = await fetchResults(query);
-  return {
-    results: data.results,                                          // LLM receives full content
-    sources: data.results.map(r => ({ url: r.url, title: r.title })), // rendered as source links
-  };
-},
-```
-
-The `sources` array is picked up by a built-in `experimental_transform` inside `buildLLMParams` — no agent changes, no writer passed to the tool, no additional wiring. The LLM continues to receive the full result object including `sources`. The transform fires on every `tool-result` stream part and emits a `source` part for each entry.
-
-Each source entry shape:
-
-| Field   | Type     | Required | Description             |
-| ------- | -------- | -------- | ----------------------- |
-| `url`   | `string` | Yes      | The URL to link to.     |
-| `title` | `string` | No       | Display name in the UI. |
-
-The playground's `UIMessageRenderer` collects all `source-url` parts from a message and displays them in a collapsible **Sources** block above the response text.
+The `activate_skill` and `list_capabilities` meta-tools are stripped from message history before persistence.
 
 ---
 
-## Compaction
+### Audit Logging (D1)
 
-When `fastModel` is set on the agent class, compaction runs automatically before each turn:
+All agent base classes write audit events to a D1 database when `AGENT_DB` is bound. If not bound, `logEvent` is a no-op.
 
-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.
+#### D1 Setup
 
-### Enabling compaction
+1. Create a D1 database in the Cloudflare dashboard.
+2. Run the schema in the D1 console. For `Agent`, use [`schema/agent.sql`](schema/agent.sql). For `ChatAgent`/`ChatAgentHarness`, use [`schema/chat.sql`](schema/chat.sql) (includes the conversations table).
+3. Bind it in `wrangler.jsonc`:
 
-Override `fastModel` on your subclass. Compaction runs automatically with a default threshold of 30 messages — no per-call config needed:
-
-```typescript
-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();
-  }
-}
+```jsonc
+"d1_databases": [
+  { "binding": "AGENT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
+]
 ```
 
-### Customising the threshold
+4. For local dev, apply the schema to your local D1 (from your app’s directory), e.g. `wrangler d1 execute <database_name> --local --file=node_modules/@economic/agents/schema/chat.sql`. You can wrap that in a `db:setup` npm script if you prefer.
 
-Pass `maxMessagesBeforeCompaction` to override the default of 30:
+#### Providing userId
 
-```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:
+The client's `chatId` becomes the Durable Object name. Use `userId:uniqueChatId` so the first segment is your stable user id (audit and conversations key off `getUserId()`, i.e. the substring before the first `:`). If that segment is empty (e.g. `:chat-1`), the connection is rejected. Same idea as [Quick Start](#quick-start) (`chatId`).
 
 ```typescript
-const params = await this.buildLLMParams({
-  options,
-  onFinish,
-  model: openai("gpt-4o"),
-  maxMessagesBeforeCompaction: undefined, // compaction off
+import { useAIChatAgent } from "@economic/agents-react";
+
+const { agent, chat } = useAIChatAgent({
+  agent: "MyAgent",
+  host: "localhost:8787",
+  chatId: "148583_matt:conversation-1",
 });
 ```
 
-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`
+### Chat Features
 
-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.
+Compaction and the conversation list (below) require `getFastModel()` on your subclass.
 
-- 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.
-
----
+#### Compaction
 
-## 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:
+Compaction summarises older messages before each turn. Full history in DO SQLite is unaffected — compaction is in-memory only. The default threshold is **15** recent messages (`maxMessagesBeforeCompaction` on the class).
 
 ```typescript
-// types.ts
-import type { AgentContext } from "@economic/agents";
+export class MyAgent extends ChatAgentHarness<Env> {
+  getModel() {
+    return openai("gpt-4o");
+  }
 
-interface AgentBody {
-  authorization: string;
-  userId: string;
-}
+  getFastModel() {
+    return openai("gpt-4o-mini");
+  }
 
-export type ToolContext = AgentContext<AgentBody>;
-```
+  getSystemPrompt() {
+    return "You are a helpful assistant.";
+  }
 
-```typescript
-// Client
-useAgentChat({ body: { authorization: token, userId: "u_123" } });
+  // Optional: keep more messages verbatim before summarising (default 15).
+  // protected maxMessagesBeforeCompaction = 50;
 
-// 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;
-};
+  // Optional: disable compaction (still uses fastModel for conversation title/summary).
+  // protected maxMessagesBeforeCompaction = undefined;
+}
 ```
 
-`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
+#### Conversations (D1)
 
-`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.
+`ChatAgent` and `ChatAgentHarness` maintain a `conversations` table in `AGENT_DB`. One row per Durable Object instance, upserted automatically after every turn. Requires [`schema/chat.sql`](schema/chat.sql).
 
-### 1. Create the D1 database
+**Automatic title and summary** — On the first turn, title and summary are generated and inserted. On subsequent turns, only `updated_at` is refreshed. Title and summary are regenerated periodically as the conversation grows.
 
-In the [Cloudflare dashboard](https://dash.cloudflare.com) → **Workers & Pages** → **D1** → **Create database**. Note the database name and ID.
+**Retention** — Set `conversationRetentionDays` to auto-delete inactive conversations:
 
-### 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:
+```typescript
+export class MyAgent extends ChatAgentHarness<Env> {
+  getModel() {
+    return openai("gpt-4o");
+  }
+  getFastModel() {
+    return openai("gpt-4o-mini");
+  }
+  getSystemPrompt() {
+    return "You are a helpful assistant.";
+  }
 
-```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);
+  // ChatAgentHarness defaults to 90 days. Override or set to undefined to disable.
+  protected conversationRetentionDays = 30;
+}
 ```
 
-Safe to re-run — all statements use `IF NOT EXISTS`.
+When the retention period expires, the D1 row is deleted, WebSocket connections are closed, and the DO's SQLite storage is wiped.
 
-### 3. Bind it in `wrangler.jsonc`
+**Querying** — From a connected client:
 
-```jsonc
-"d1_databases": [
-  { "binding": "AGENT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
-]
+```typescript
+const conversations = await agent.call("getConversations");
 ```
 
-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.
+## Hono
 
-If `AGENT_DB` is not bound, all `log()` calls are silent no-ops — the agent works without it.
+Hono tooling is exported on `@economic/agents/hono`.
 
-### Providing `userId`
+### JWT Auth Middleware
 
-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`:
+Bearer JWT verification middleware for Hono, imported from `@economic/agents/hono`. Verifies tokens via JWKS derived from the token's `iss` claim.
 
 ```typescript
-useAgentChat({
-  agent,
-  body: {
-    userId: "148583_matt", // compose from agreement number + user identifier
-    // ...other fields
-  },
-});
+import { jwtAuth } from "@economic/agents/hono";
+
+app.use(
+  "/api/*",
+  jwtAuth({
+    allowedIssuers: ["https://login.example.com"],
+    audience: "my-api",
+    requiredScopes: ["read", "write"],
+  }),
+);
 ```
 
-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
+## API Reference
 
-`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.
+### `@economic/agents`
 
-The `conversations` table is created by the same `schema/schema.sql` file used for audit events — no separate setup step needed.
+| Export                 | Description                                                                |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `Agent`                | Abstract DO base for non-chat agents with audit logging and buildLLMParams |
+| `ChatAgent`            | Abstract chat DO with compaction, conversations, and custom onChatMessage  |
+| `ChatAgentHarness`     | Opinionated chat harness with getModel/getSystemPrompt/getTools/getSkills  |
+| `buildLLMParams`       | Standalone function to build streamText/generateText params                |
+| `Skill`                | Type: named group of tools with optional guidance                          |
+| `AgentToolContext`     | Type: request body merged with `logEvent` for tool context                 |
+| `OnChatMessageOptions` | Type: options passed to `onChatMessage`                                    |
+| `BuildLLMParamsConfig` | Type: config for standalone `buildLLMParams`                               |
 
-### Upsert behaviour
+### `@economic/agents-react`
 
-- **First turn**: `AIChatAgent` generates `title` and `summary` first, then inserts the row with `created_at` and `updated_at` both set to now and `title`/`summary` already populated.
-- **Subsequent turns**: the upsert only refreshes `updated_at`. `created_at`, `title`, and `summary` are preserved by the upsert path.
-- Every `SUMMARY_CONTEXT_MESSAGES` messages, `AIChatAgent` separately re-generates `title` and `summary` and writes them back without changing `created_at`.
+React hooks are in a separate package. See [`@economic/agents-react`](../react/README.md) for full documentation.
 
-### Automatic title and summary generation
+| Export                  | Description                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `useAIChatAgent`        | React hook wrapping `useAgent` + `useAgentChat`                                                                           |
+| `UseAIChatAgentOptions` | Type: options for `useAIChatAgent` (`agent`, `host`, `chatId`, optional `basePath`, `toolContext`, `connectionParams`, …) |
+| `AgentConnectionStatus` | Type: `"connecting" \| "connected" \| "disconnected" \| "unauthorized"`                                                   |
 
-On the first persisted turn, `AIChatAgent` generates a title and summary from the current conversation and inserts them into the new D1 row.
+### `@economic/agents/hono`
 
-On later turns, it always refreshes `updated_at`, and it re-generates the title/summary every `SUMMARY_CONTEXT_MESSAGES` messages using the latest window plus the previous summary.
+| Export          | Description                                 |
+| --------------- | ------------------------------------------- |
+| `jwtAuth`       | Hono middleware for Bearer JWT verification |
+| `JwtAuthConfig` | Type: config for `jwtAuth`                  |
 
-No subclass code is needed — this runs automatically when `AGENT_DB` is bound and `fastModel` is set on the class.
+### CLI
 
-### Automatic conversation retention
+| Command                                      | Description                              |
+| -------------------------------------------- | ---------------------------------------- |
+| `npx @economic/agents generate skill <name>` | Scaffold a new skill with tools          |
+| `npx @economic/agents generate tool <name>`  | Scaffold a new tool (global or in skill) |
 
-Set `conversationRetentionDays` on your subclass to automatically delete inactive conversations after that many days:
+---
 
-```typescript
-export class MyAgent extends AIChatAgent<Env> {
-  protected fastModel = openai("gpt-4o-mini");
-  protected conversationRetentionDays = 90;
-}
-```
+## CLI
 
-After each persisted turn, the base class resets a per-conversation scheduled callback on the Durable Object. When it fires, the callback:
+The package includes a CLI for scaffolding skills and tools.
 
-1. Deletes the matching row from the D1 `conversations` table.
-2. Closes any active WebSocket connections for that conversation.
-3. Wipes the Durable Object's SQLite storage with `deleteAll()`.
+### Generate a Skill
 
-If `conversationRetentionDays` is `undefined`, retention cleanup is disabled and old conversation URLs stay resumable indefinitely.
+```bash
+npx @economic/agents generate skill weather
+```
 
-### Querying conversation lists
+This will:
 
-From a connected agent client, prefer the built-in callable (see **`getConversations` (callable)** under [`AIChatAgent`](#aichatagent)): `await agent.call("getConversations")`.
+1. Prompt for a skill description
+2. Ask for initial tool names (comma-separated)
+3. Prompt for each tool's description and whether it needs `AgentToolContext`
+4. Create the skill file at `src/skills/weather/weather.ts`
+5. Create tool files at `src/skills/weather/tools/*.ts`
+6. Auto-register the skill in your agent's `getSkills()` method
 
-To query D1 directly (same logic as the callable), filter by `durable_object_name` prefix — one row per chat, keyed as `userId:chatId`:
+### Generate a Tool
 
-```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;
+```bash
+npx @economic/agents generate tool geocode
 ```
 
-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
+This will:
 
-| 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. |
+1. Prompt for a tool description
+2. Ask where to create it (global `src/tools/` or within an existing skill)
+3. Ask whether it needs `AgentToolContext`
+4. Create the tool file
+5. Auto-register the tool in your agent's `getTools()` or the skill's `tools` object
 
-### Functions
+### Auto-registration
 
-| 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`.                                   |
+The CLI automatically detects agent files by scanning `src/` for classes extending `ChatAgentHarness`, `ChatAgent`, or `Agent` from `@economic/agents`. If one agent is found, it's used automatically. If multiple are found, you'll be prompted to select one.
 
-### Types
+For `ChatAgentHarness`, the CLI modifies `getSkills()` or `getTools()` methods. For `ChatAgent` or `Agent`, it modifies `buildLLMParams()` calls.
 
-| 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.                                                        |
+If the CLI detects complex patterns (spread operators, function calls, variables), it will print manual registration instructions instead.
 
 ---
 
 ## Development
 
 ```bash
-npm install   # install dependencies
-npm test      # run tests
-npm pack      # build
+npm install
+npm test
+npm pack
 ```