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

package/README.md

@@ -1,87 +1,393 @@
 # @economic/agents
 
-Base classes and utilities for building LLM agents on Cloudflare's Agents SDK with lazy tool loading.
+Base class and AI SDK wrappers for building LLM chat agents on Cloudflare's Agents SDK with lazy skill loading and optional message compaction.
 
-## 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` and call our `streamText` wrapper.
+- **`streamText` / `generateText`** — wrappers around the Vercel AI SDK functions that accept `UIMessage[]` directly, add a `skills` / `activeSkills` pair for lazy tool loading, and a `compact` option for message compaction.
 
-```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 { AIChatAgent, streamText } from "@economic/agents";
+import type { Skill } from "@economic/agents";
+import { openai } from "@ai-sdk/openai";
+import { stepCountIs, tool } from "ai";
+import { z } from "zod";
+
+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 stream = await streamText({
+      model: openai("gpt-4o"),
+      messages: await convertToModelMessages(this.messages),
+      system: "You are a helpful assistant.",
+      skills: [searchSkill],
+      activeSkills: await this.getLoadedSkills(),
+      stopWhen: stepCountIs(20),
+      abortSignal: options?.abortSignal,
+      onFinish,
+    });
+    return stream.toUIMessageStreamResponse();
+  }
+}
+```
+
+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.
+
 ---
 
-## Implementing your own agent
+## `AIChatAgent`
 
-Extend `AIChatAgent` and implement the four required methods:
+Extend this class and implement `onChatMessage`. Call our `streamText` wrapper — which accepts `UIMessage[]`, skills, and compaction — and return the response.
 
 ```typescript
-import { AIChatAgent } from "@economic/agents";
+import { AIChatAgent, streamText } from "@economic/agents";
+import type { RequestBody } from "./types";
 
-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 RequestBody;
+    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 stream = await streamText({
+      model,
+      messages: await convertToModelMessages(this.messages),
+      system: "You are a helpful assistant.",
+      skills: [searchSkill, calcSkill], // available for on-demand loading
+      activeSkills: await this.getLoadedSkills(), // loaded from DO SQLite
+      tools: { alwaysOnTool }, // always active
+      stopWhen: stepCountIs(20),
+      abortSignal: options?.abortSignal,
+      onFinish,
+    });
+    return stream.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.
+### `getLoadedSkills()`
+
+Protected method on `AIChatAgent`. Returns skill names persisted from previous turns (read from DO SQLite). Pass the result as `activeSkills`.
+
+### `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. Strips all `activate_skill` and `list_capabilities` messages from history.
+4. Delegates to the CF base `persistMessages` for message storage and WS broadcast.
 
-### Message compaction
+### `onConnect` (automatic)
 
-`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).
+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.
 
-The compaction model defaults to `getModel()`. To use a cheaper model for summarisation, override `getCompactionModel()`:
+---
+
+## `streamText` wrapper
+
+Drop-in replacement for `streamText` from `ai` with three extra params:
+
+| Extra param    | Type                                            | Description                                                                    |
+| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `messages`     | `UIMessage[]`                                   | Converted to `ModelMessage[]` internally. Pass `this.messages`.                |
+| `skills`       | `Skill[]`                                       | Skills available for on-demand loading. Wires up meta-tools automatically.     |
+| `activeSkills` | `string[]`                                      | Names of skills loaded in previous turns. Pass `await this.getLoadedSkills()`. |
+| `compact`      | `{ model: LanguageModel; maxMessages: number }` | When provided, compacts old messages before sending to the model.              |
+
+When `skills` are provided the wrapper:
+
+- 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
+- Merges any `activeTools` / `prepareStep` you also pass (additive)
 
 ```typescript
-protected override getCompactionModel(): LanguageModel {
-  return openai("gpt-4o-mini"); // cheaper model for summarisation
-}
+// With skills and compaction
+const stream = await streamText({
+  model: openai("gpt-4o"),
+  messages: await convertToModelMessages(this.messages),
+  system: "You are a helpful assistant.",
+  skills: [searchSkill, codeSkill],
+  activeSkills: await this.getLoadedSkills(),
+  tools: { myAlwaysOnTool },
+  compact: { model: openai("gpt-4o-mini"), maxMessages: 30 },
+  onFinish,
+});
+return stream.toUIMessageStreamResponse();
+
+// Without skills — identical to AI SDK, no API breakage
+const stream = await streamText({
+  model: openai("gpt-4o"),
+  messages: await convertToModelMessages(this.messages),
+  tools: { myTool },
+  activeTools: ["myTool"],
+  onFinish,
+});
+return stream.toUIMessageStreamResponse();
 ```
 
-To disable compaction entirely, override `getCompactionModel()` to return `undefined`:
+---
+
+## `generateText` wrapper
+
+Same additions as `streamText` — accepts `UIMessage[]`, `skills` / `activeSkills`, and `compact`.
 
 ```typescript
-protected override getCompactionModel(): LanguageModel | undefined {
-  return undefined; // no compaction — older messages are dropped at maxPersistedMessages
-}
+const result = await generateText({
+  model: openai("gpt-4o"),
+  messages: await convertToModelMessages(this.messages),
+  skills: [searchSkill],
+  activeSkills: await this.getLoadedSkills(),
+});
 ```
 
-`AIChatAgentBase` does not enable compaction by default. To add it, override `getCompactionModel()` to return a model — the `persistMessages` override will pick it up automatically:
+---
+
+## Defining skills
 
 ```typescript
-protected override getCompactionModel(): LanguageModel {
-  return openai("gpt-4o-mini");
-}
+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",
+        }),
+    }),
+  },
+};
 ```
 
-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.
+### `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 `streamText` / `generateText`, the wrapper 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
+const stream = await streamText({
+  model: openai("gpt-4o"),
+  messages: await convertToModelMessages(this.messages),
+  system: "...",
+  compact: {
+    model: openai("gpt-4o-mini"), // cheaper model for summarisation
+    maxMessages: 30, // keep last 30 messages verbatim
+  },
+  onFinish,
+});
+return stream.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:
+
+```typescript
+// Client
+useAgentChat({ body: { authorization: token, userId: "u_123" } });
+
+// Tool
+execute: async (args, { experimental_context }) => {
+  const { authorization } = experimental_context as { authorization: string };
+};
+
+// In onChatMessage — forward body to tools
+const stream = await streamText({
+  ...
+  experimental_context: options?.body,
+});
+return stream.toUIMessageStreamResponse();
+```
+
+---
+
+## Advanced: `createSkills` directly
+
+`createSkills` is the lower-level factory used internally by the `streamText` wrapper. Use it only if you are building a fully custom agent that does not use the wrappers.
+
+```typescript
+import { createSkills, filterEphemeralMessages } from "@economic/agents";
+
+const skillsCtx = createSkills({
+  tools: alwaysOnTools,
+  skills: permittedSkills,
+  initialLoadedSkills: await getLoadedSkills(), // from storage
+  systemPrompt: "You are a helpful assistant.",
+});
+
+const result = aiStreamText({
+  model,
+  system: skillsCtx.getSystem(),
+  messages: convertToModelMessages(messages),
+  tools: skillsCtx.tools,
+  activeTools: skillsCtx.activeTools,
+  prepareStep: skillsCtx.prepareStep,
+});
+```
+
+---
+
+## API reference
+
+### Classes
+
+| Export        | Description                                                                                         |
+| ------------- | --------------------------------------------------------------------------------------------------- |
+| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state in DO SQLite. |
+
+### Functions
+
+| Export                    | Signature                                                                       | Description                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `streamText`              | `async (params: StreamTextParams) => StreamTextResult`                          | Wraps AI SDK `streamText`; accepts `UIMessage[]`, `skills`, `compact`.                                     |
+| `generateText`            | `async (params: GenerateTextParams) => GenerateTextResult`                      | Wraps AI SDK `generateText`; same extra params as `streamText`.                                            |
+| `createSkills`            | `(config: SkillsConfig) => SkillsResult`                                        | Lower-level factory for building the skill loading system.                                                 |
+| `filterEphemeralMessages` | `(messages: UIMessage[]) => UIMessage[]`                                        | Strips all `activate_skill` and `list_capabilities` tool calls.                                            |
+| `injectGuidance`          | `(messages: ModelMessage[], guidance: string, prev?: string) => ModelMessage[]` | Inserts guidance just before the last user message. **Deprecated** — use `system` in the wrappers instead. |
+| `compactIfNeeded`         | `(messages, model, tailSize) => Promise<UIMessage[]>`                           | Compacts if token estimate exceeds threshold; no-op if model is `undefined`.                               |
+| `compactMessages`         | `(messages, model, tailSize) => Promise<UIMessage[]>`                           | Summarises the older window and returns `[summaryMsg, ...verbatimTail]`.                                   |
+| `estimateMessagesTokens`  | `(messages: UIMessage[]) => number`                                             | Character-count heuristic (÷ 3.5) over text, reasoning, and tool parts.                                    |
+
+### Constants
+
+| Export                    | Value     | Description                                          |
+| ------------------------- | --------- | ---------------------------------------------------- |
+| `COMPACT_TOKEN_THRESHOLD` | `140_000` | Token count above which compaction is triggered.     |
+| `SKILL_STATE_SENTINEL`    | `string`  | Delimiter used to embed skill state in tool results. |
+
+### Types
+
+| Export               | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `Skill`              | A named group of tools with optional guidance.  |
+| `SkillsConfig`       | Configuration object for `createSkills()`.      |
+| `SkillsResult`       | Return type of `createSkills()`.                |
+| `StreamTextParams`   | Params for the `streamText` wrapper.            |
+| `GenerateTextParams` | Params for the `generateText` wrapper.          |
+| `CompactOptions`     | `{ model: LanguageModel; maxMessages: number }` |
+
+---
+
+## Development
+
+```bash
+vp install   # install dependencies
+vp test      # run tests
+vp pack      # build
+```