@economic/agents 0.0.1-alpha.10 → 0.0.1-alpha.12

package/README.md

@@ -1,87 +1,404 @@
 # @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
+```
 
-- **`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.
+- **`buildLLMParams`** — the standalone version of the above, for use outside of `AIChatAgent` or in custom agent implementations.
 
-```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.
+
+---
+
+## 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";
+
+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> {
+  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();
+  }
+}
 ```
 
+No D1 database needed — skill state is persisted to Durable Object SQLite automatically.
+
 ---
 
-## Implementing your own agent
+## 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"] }],
+}
+```
 
-Extend `AIChatAgent` and implement the four required methods:
+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 MyAgent extends AIChatAgent {
-  getModel() {
-    return openai("gpt-4o");
-  }
-  getTools() {
-    return [myAlwaysOnTool];
-  }
-  getSkills() {
-    return [searchSkill, codeSkill];
-  }
-  getSystemPrompt() {
-    return "You are a helpful assistant.";
-  }
+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");
 
-  // Return the D1 binding — typed in Cloudflare.Env after `wrangler types`
-  protected getDB() {
-    return this.env.AGENT_DB;
+    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();
   }
 }
 ```
 
-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.
+### `this.buildLLMParams(config)`
+
+Protected method on `AIChatAgent`. Wraps the standalone `buildLLMParams` function with:
 
-### Message compaction
+- `messages` pre-filled from `this.messages`
+- `activeSkills` pre-filled from `await this.getLoadedSkills()`
+- `log` injected into `experimental_context` alongside `options.body`
+- Automatic error logging for non-clean finish reasons
 
-`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).
+Config is everything accepted by the standalone `buildLLMParams` except `messages` and `activeSkills`.
 
-The compaction model defaults to `getModel()`. To use a cheaper model for summarisation, override `getCompactionModel()`:
+### `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
-protected override getCompactionModel(): LanguageModel {
-  return openai("gpt-4o-mini"); // cheaper model for summarisation
-}
+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 },
+  compact: { model: openai("gpt-4o-mini"), maxMessages: 30 },
+  stopWhen: stepCountIs(20), // defaults to stepCountIs(20)
+});
+
+return streamText(params).toUIMessageStreamResponse();
+// or: generateText(params);
 ```
 
-To disable compaction entirely, override `getCompactionModel()` to return `undefined`:
+| 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.                |
+| `compact`      | `{ model: LanguageModel; maxMessages: number }` | No       | When provided, compacts old messages before sending to the model.              |
+| `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
-protected override getCompactionModel(): LanguageModel | undefined {
-  return undefined; // no compaction — older messages are dropped at maxPersistedMessages
-}
+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",
+        }),
+    }),
+  },
+};
 ```
 
-`AIChatAgentBase` does not enable compaction by default. To add it, override `getCompactionModel()` to return a model — the `persistMessages` override will pick it up automatically:
+### `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 `compact` is provided to `buildLLMParams`, it compacts `messages` before converting and sending to the model:
+
+1. The message list is split into an older window and a recent verbatim tail (`maxMessages`).
+2. A model call 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.
 
 ```typescript
-protected override getCompactionModel(): LanguageModel {
-  return openai("gpt-4o-mini");
+const params = await this.buildLLMParams({
+  options,
+  onFinish,
+  model: openai("gpt-4o"),
+  system: "...",
+  compact: {
+    model: openai("gpt-4o-mini"), // cheaper model for summarisation
+    maxMessages: 30, // keep last 30 messages verbatim
+  },
+});
+return streamText(params).toUIMessageStreamResponse();
+```
+
+---
+
+## 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 `AUDIT_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 `AUDIT_DB` is bound on the environment. The table is shared across all agent workers — create it once.
+
+### 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/audit_events.sql`](schema/audit_events.sql):
+
+```sql
+CREATE TABLE IF NOT EXISTS audit_events (
+  id                TEXT PRIMARY KEY,
+  agent_name        TEXT NOT NULL,
+  durable_object_id TEXT NOT NULL,
+  message           TEXT NOT NULL,
+  payload           TEXT,
+  created_at        TEXT NOT NULL
+);
+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);
+```
+
+Safe to re-run — all statements use `IF NOT EXISTS`.
+
+### 3. Bind it in `wrangler.jsonc`
+
+```jsonc
+"d1_databases": [
+  { "binding": "AUDIT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
+]
 ```
 
-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.
+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 `AUDIT_DB` is not bound, all `log()` calls are silent no-ops — the agent works without it.
+
+---
+
+## API reference
+
+### Classes
+
+| Export        | Description                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state, history replay, and audit log. |
+
+### Functions
+
+| Export           | Signature                              | Description                                                          |
+| ---------------- | -------------------------------------- | -------------------------------------------------------------------- |
+| `buildLLMParams` | `async (config) => Promise<LLMParams>` | Builds the full parameter object for `streamText` or `generateText`. |
+
+### Types
+
+| Export                 | Description                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `Skill`                | A named group of tools with optional guidance.                                  |
+| `CompactOptions`       | `{ model: LanguageModel; maxMessages: number }`                                 |
+| `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
+```