@economic/agents 2.1.6 → 2.2.0

package/README.md

@@ -1,584 +1,396 @@
 # @economic/agents
 
-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.
+Our agents SDK for building AI agents on Cloudflare Workers. Each agent is a Durable Object running an LLM loop — model, system prompt, tools, skills, auth, telemetry — on [`@cloudflare/think`](https://www.npmjs.com/package/@cloudflare/think) and the [`ai`](https://www.npmjs.com/package/ai) SDK.
 
-For chat agents, extend `ChatAgentHarness` (recommended) or `ChatAgent` (lower-level). For headless agents, extend `Agent`.
+React client: [`@economic/agents-react`](../react/README.md).
 
-For React integration, see [`@economic/agents-react`](../react/README.md).
+> The v1 (`@economic/agents/v1`) API (`ChatAgentHarness`, `buildLLMParams`) is deprecated, kept only for migration, and removed in v3.
+
+## The three classes
+
+- **`Agent`** — the core. Runs the agent loop and keeps message history. Drive it over a WebSocket or programmatically (schedule, alarm, RPC). Most agents stop here.
+- **`ChatAgent`** — `Agent` plus conversation features: compaction and message feedback.
+- **`Assistant`** — per-user shell over `ChatAgent`: create/list/delete conversations, titles, summaries, retention.
+
+```
+Agent            ← LLM + tools + skills (most agents stop here)
+ └─ ChatAgent     ← one persistent conversation
+     └─ Assistant ← one user, many conversations
+```
 
 ## Install
 
 ```sh
-npm install @economic/agents @cloudflare/ai-chat ai agents
+npm install @economic/agents ai
 ```
 
-## Quick Start
+`jose` is an optional peer dependency, needed only for JWT auth.
+
+## Quick start: an agent
 
-### Server
+Subclass `Agent` and implement `getModel` and `getSystemPrompt`. Add tools with `getTools`, skills with `getSkills`. Expose a `@callable` method to run a turn — `saveMessages` injects a message, runs the turn, and persists the result:
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
-import { tool } from "ai";
+import { callable } from "agents";
+import { Agent, tool, type ToolSet } from "@economic/agents";
 import { z } from "zod";
-import { ChatAgentHarness, type AgentToolContext, 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 ChatAgentHarness<Env> {
-  getModel(ctx: AgentToolContext) {
+export class SupportAgent extends Agent {
+  getModel() {
     return openai("gpt-4o");
   }
 
-  getFastModel() {
-    return openai("gpt-4o-mini");
+  getSystemPrompt() {
+    return "You help customers with their orders. Be concise.";
   }
 
-  getSystemPrompt(ctx: AgentToolContext) {
-    return "You are a helpful assistant.";
+  getTools(): ToolSet {
+    return {
+      get_order: tool({
+        description: "Look up an order by id",
+        inputSchema: z.object({ orderId: z.string() }),
+        execute: async ({ orderId }) => fetchOrder(orderId),
+      }),
+    };
   }
 
-  getSkills(ctx: AgentToolContext) {
-    return [searchSkill];
+  @callable()
+  async checkOrder(orderId: string) {
+    await this.saveMessages([
+      {
+        id: crypto.randomUUID(),
+        role: "user",
+        parts: [{ type: "text", text: `What's the status of order ${orderId}?` }],
+      },
+    ]);
   }
 }
 ```
 
-For lower-level control (custom `onChatMessage` implementations), extend `ChatAgent` directly — see [ChatAgent](#chatagent).
+Route requests and export the class:
+
+```typescript
+import { routeAgentRequest } from "@economic/agents";
+
+export { SupportAgent } from "./agent";
 
-### Wrangler Config
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return (await routeAgentRequest(request, env)) ?? new Response("Not found", { status: 404 });
+  },
+};
+```
 
 ```jsonc
+// wrangler.jsonc — binding name must match the class name
 {
+  "compatibility_date": "2026-04-16",
+  "compatibility_flags": ["nodejs_compat", "experimental"],
   "durable_objects": {
-    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
+    "bindings": [{ "name": "SupportAgent", "class_name": "SupportAgent" }],
   },
-  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SupportAgent"] }],
+  // see "Bindings"
+  "r2_buckets": [{ "binding": "AGENTS_AUDIT_LOGS", "bucket_name": "agents-audit-logs" }],
+  "analytics_engine_datasets": [{ "binding": "AGENTS_ANALYTICS", "dataset": "agents-analytics" }],
 }
 ```
 
-Run `wrangler types` after to generate typed `Env` bindings.
-
-### Client
+Run `wrangler types` for a typed `Env`.
 
-```typescript
-import { useAIChatAgent, type AgentConnectionStatus } from "@economic/agents-react";
-import { useState } from "react";
+### Calling it from the client
 
-const [connectionStatus, setConnectionStatus] = useState<AgentConnectionStatus>("connecting");
+Connect with [`useAgent`](../react/README.md#useagent) and invoke any `@callable` method with `agent.call`:
 
-const { agent, chat } = useAIChatAgent({
-  agent: "MyAgent",
+```tsx
+const agent = useAgent({
   host: "localhost:8787",
-  chatId: "user_123:session-1",
-  toolContext: {},
-  connectionParams: { userId: "…" },
-  onConnectionStatusChange: setConnectionStatus,
+  agentName: "SupportAgent",
+  name: `${userId}:support`,
 });
 
-const { messages, sendMessage, status, stop } = chat;
+await agent.call("checkOrder", ["1234"]);
 ```
 
-`chatId` is the Durable Object name — use `userId:uniqueChatId` (see [Providing userId](#providing-userid)).
+You can also drive turns server-side — call `saveMessages` from a schedule or alarm.
 
-> **Note:** React hooks are in a separate package. Install with `npm install @economic/agents-react`.
+## A chat agent
 
----
-
-## 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
-
-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.
+For a chat UI, extend `ChatAgent` instead of `Agent`. It adds compaction and message feedback, and connects to a browser with [`useChat`](../react/README.md#usechat) — no `Assistant` required. The DO name is the conversation; address one per user, ticket, or whatever fits.
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
-import { ChatAgentHarness, type AgentToolContext, type Skill } from "@economic/agents";
-
-interface RequestBody {
-  userTier: "free" | "pro";
-}
-
-export class MyAgent extends ChatAgentHarness<Env, RequestBody> {
-  getModel(ctx: AgentToolContext<RequestBody>) {
-    return ctx.userTier === "pro" ? openai("gpt-4o") : openai("gpt-4o-mini");
-  }
+import { ChatAgent } from "@economic/agents";
+import { weatherSkill } from "./skills/weather";
 
-  getFastModel() {
-    return openai("gpt-4o-mini");
+export class MyChatAgent extends ChatAgent {
+  getModel() {
+    return openai("gpt-4o");
   }
 
-  getSystemPrompt(ctx: AgentToolContext<RequestBody>) {
+  getSystemPrompt() {
     return "You are a helpful assistant.";
   }
 
-  getTools(ctx: AgentToolContext<RequestBody>) {
-    return { myTool };
-  }
-
-  getSkills(ctx: AgentToolContext<RequestBody>) {
-    return [searchSkill, calculatorSkill];
+  getSkills() {
+    return [weatherSkill];
   }
 }
 ```
 
-- `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.
-
-#### Binding Name
-
-`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:**
-
-```typescript
-// Class name is "MyAgent"
-export class MyAgent extends ChatAgentHarness<Env> {
-  /* ... */
-}
+```tsx
+const { chat } = useChat({
+  host: "localhost:8787",
+  agentName: "MyChatAgent",
+  name: `${userId}:weather`,
+});
 ```
 
-```jsonc
-// wrangler.jsonc — binding name must be "MyAgent" to match
-{
-  "durable_objects": {
-    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
-  },
-}
-```
+What `ChatAgent` adds over `Agent`:
 
-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:
+- **Compaction** — past 100,000 tokens, older messages are summarised (with `getModel()`) while recent ones are kept verbatim. Storage keeps the full history.
+- **Message feedback** — thumbs up/down with an optional comment, in the conversation's SQLite (`assistant_messages_feedback`, created automatically):
 
-````typescript
-export class MyAgent extends ChatAgentHarness<Env> {
-  protected get binding() {
-    return this.env.CUSTOM_BINDING_NAME;
-  }
-  // ...
-}
+  | Method                                               | Description                                                  |
+  | ---------------------------------------------------- | ------------------------------------------------------------ |
+  | `submitMessageFeedback(messageId, rating, comment?)` | `rating` is `1` (up) or `-1` (down). Upserts on the message. |
+  | `getMessageFeedback()`                               | All feedback for the conversation, keyed by message id.      |
 
----
+  Surfaced by the client as `chat.submitMessageFeedback` / `chat.getMessageFeedback`.
 
-### ChatAgent
+## Many chats per user: Assistant
 
-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.
+When one user needs a list of conversations — a sidebar, titles, summaries — add an `Assistant`. It owns the chat list and routes to a `ChatAgent` per conversation.
 
 ```typescript
-import { streamText } from "ai";
 import { openai } from "@ai-sdk/openai";
-import { ChatAgent } from "@economic/agents";
-
-export class MyAgent extends ChatAgent<Env> {
-  protected get binding() {
-    return this.env.MyAgent;
-  }
-
-  protected getFastModel() {
-    return openai("gpt-4o-mini");
-  }
+import { Assistant } from "@economic/agents";
+import { MyChatAgent } from "./chat-agent";
 
-  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();
-  }
+export class MyAssistant extends Assistant {
+  protected agent = MyChatAgent;
+  protected fastModel = openai("gpt-4o-mini"); // titles and summaries
 }
-````
+```
 
-- `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.
+Bind both classes (binding name = class name) with a `new_sqlite_classes` migration each. On the client, use [`useAssistant`](../react/README.md#useassistant) — it manages the chat list and connects to the active conversation:
 
----
+```tsx
+const { status, chats, assistant, chat } = useAssistant({
+  host: "localhost:8787",
+  agentName: "MyAssistant",
+  name: userId, // the Assistant is keyed by user
+});
+```
 
-### Agent
+The `Assistant` keeps the chat list in its own SQLite (a `chats` table, created automatically) and exposes three callable methods:
 
-Abstract Durable Object base for non-chat agents. Use for headless workflows driven from HTTP handlers, schedules, or alarms.
+| Method           | Returns  | Description                                            |
+| ---------------- | -------- | ------------------------------------------------------ |
+| `createChat()`   | `string` | Creates a conversation and returns its id.             |
+| `getChats()`     | `Chat[]` | The user's conversations, most recently updated first. |
+| `deleteChat(id)` | `void`   | Deletes a conversation and its record.                 |
 
-```typescript
-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;
-  }
-}
-```
+- **Titles and summaries** — generated with `fastModel` after each turn (on the first turn, then refreshed as the conversation grows).
+- **Retention** — inactive conversations are deleted after 90 days, via a Durable Object alarm.
 
-- `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.
+## Bindings
 
----
+Checked in `Agent.onStart` when a connection opens:
 
-### Tool context
+| Binding             | Type             | Required | Notes                                                                     |
+| ------------------- | ---------------- | -------- | ------------------------------------------------------------------------- |
+| `AGENTS_AUDIT_LOGS` | R2               | Yes      | Connection rejected if missing. One [audit log](#observability) per turn. |
+| `AGENTS_ANALYTICS`  | Analytics Engine | No       | Per-turn/per-tool [analytics](#observability). Warns if missing.          |
+| `SKILLS_BUCKET`     | R2               | No       | Source for [remote skills](#remote-skills).                               |
 
-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:
+## Tools
+
+`tool()` wraps an `ai` SDK tool with an optional `authorize(ctx)`. Return always-on tools from `getTools()`:
 
 ```typescript
-import type { AgentToolContext } from "@economic/agents";
+import { tool, type ToolSet } from "@economic/agents";
+import { z } from "zod";
 
-interface AgentBody {
-  authorization: string;
-  userId: string;
+getTools(): ToolSet {
+  return {
+    search_web: tool({
+      description: "Search the web",
+      inputSchema: z.object({ query: z.string() }),
+      execute: async ({ query }) => search(query),
+      authorize: (ctx) => ctx._userContext?.canSearch !== false,
+    }),
+  };
 }
-
-type ToolContext = AgentToolContext<AgentBody>;
-
-// 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);
-};
 ```
 
-`logEvent` is a no-op when `AGENT_DB` is not bound.
-
----
+`authorize` returning `false` hides the tool for that request.
 
-### JWT Authentication
+### Tool context
 
-Authenticate WebSocket connections by implementing `getJwtAuthConfig` on your agent. When defined, JWT verification runs in `onConnect` — failed auth closes the connection, successful auth stores claims in `session`.
+The tool context is the second argument to `execute` — `experimental_context`:
 
 ```typescript
-import type { JWTPayload } from "jose";
-import { ChatAgentHarness, type AgentToolContext } from "@economic/agents";
+import { tool, type ToolContext } from "@economic/agents";
+import { z } from "zod";
 
-interface Session {
-  clientId: string;
-  userGuid: string;
-  agreementNumber: number;
+interface RequestBody {
+  tokens: Record<string, string>;
 }
 
-export class MyAgent extends ChatAgentHarness<Env, RequestBody> {
-  getJwtAuthConfig(request: Request) {
-    const origin = request.headers.get("Origin") ?? "";
-    const isStaging = origin.includes("staging");
-
-    return {
-      allowedIssuers: isStaging
-        ? [/^https:\/\/auth\.staging\.example\.com$/]
-        : ["https://auth.example.com"],
-      audience: "my-api",
-      requiredScopes: ["read"],
-      getClaims: (payload: JWTPayload): Session => ({
-        clientId: payload.client_id as string,
-        userGuid: payload.user_guid as string,
-        agreementNumber: payload.agreement_number as number,
-      }),
-    };
-  }
-
-  // Session is available in tool context
-  getModel(ctx: AgentToolContext<RequestBody>) {
-    console.log(ctx.session); // { clientId, userGuid, agreementNumber }
-    return openai("gpt-4o");
-  }
-}
+const call_api = tool({
+  description: "Call the API for the user",
+  inputSchema: z.object({ path: z.string() }),
+  execute: async ({ path }, { experimental_context }) => {
+    const ctx = experimental_context as ToolContext<RequestBody>;
+    return fetchWithAuth(ctx.tokens, path);
+  },
+});
 ```
 
-- `allowedIssuers` — array of strings or RegExp patterns for trusted issuers
-- `audience` — expected `aud` claim
-- `requiredScopes` — optional array of required OAuth scopes
-- `getClaims(payload)` — extract claims from verified JWT payload
-
-Claims are available as `ctx.session` in `getModel`, `getSystemPrompt`, `getTools`, `getSkills`, and tool `execute` functions.
+`ToolContext<RequestContext, UserContext>` is `RequestContext & { _userContext?: UserContext }`. Request context comes from the client (`toolContext` in the hooks); `_userContext` comes from [`getUserContext`](#user-context) when using JWT Authentication (via `getJwtAuthConfig`).
 
-If `getJwtAuthConfig` is not implemented, no authentication is performed and `ctx.session` is `undefined`.
+## Skills
 
----
-
-### Source URLs from Tools
-
-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.
+A skill bundles markdown `instructions` with optional tools. Only `description` sits in the system prompt; the model loads the instructions and tools on demand via the built-in `load_context` tool.
 
 ```typescript
-execute: async ({ query }) => {
-  const data = await fetchResults(query);
-  return {
-    results: data.results,
-    sources: data.results.map((r) => ({ url: r.url, title: r.title })),
-  };
-};
-```
-
-Each source entry: `{ url: string, title?: string }`.
-
----
+import { skill, tool } from "@economic/agents";
+import { z } from "zod";
 
-### Skills
+export const weatherSkill = skill({
+  name: "weather",
+  description: "Look up current weather and forecasts. Use for any weather question.",
+  instructions: `
+# Weather
 
-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`.
+## When to use
+Use this skill whenever the user asks about current conditions or a forecast.
 
-```typescript
-import { tool } from "ai";
-import { z } from "zod";
-import type { Skill } from "@economic/agents";
-
-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.",
+## Workflow
+1. Resolve the location to coordinates if needed.
+2. Call \`get_forecast\` with the coordinates.
+3. Summarise the result; never invent values.
+`,
   tools: {
-    calculate: tool({
-      description: "Evaluate a mathematical expression",
-      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}`;
-      },
+    get_forecast: tool({
+      description: "Get the forecast for a set of coordinates",
+      inputSchema: z.object({ lat: z.number(), lon: z.number() }),
+      execute: async ({ lat, lon }) => fetchForecast(lat, lon),
     }),
   },
-};
-```
-
-When `skills` are provided to `buildLLMParams`, two meta-tools are registered automatically:
-
-- **`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.
-
-The `activate_skill` and `list_capabilities` meta-tools are stripped from message history before persistence.
-
----
-
-### Audit Logging (D1)
-
-All agent base classes write audit events to a D1 database when `AGENT_DB` is bound. If not bound, `logEvent` is a no-op.
-
-#### D1 Setup
-
-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`:
-
-```jsonc
-"d1_databases": [
-  { "binding": "AGENT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
-]
-```
-
-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.
-
-#### Providing userId
-
-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
-import { useAIChatAgent } from "@economic/agents-react";
-
-const { agent, chat } = useAIChatAgent({
-  agent: "MyAgent",
-  host: "localhost:8787",
-  chatId: "148583_matt:conversation-1",
 });
 ```
 
----
+Return skills from `getSkills()`. Add `authorize(ctx)` to gate a skill (and its tools). `skill()` throws if `description` or `instructions` is missing.
 
-### Chat Features
+### Remote skills
 
-Compaction and the conversation list (below) require `getFastModel()` on your subclass.
-
-#### Compaction
-
-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).
+Store skills in R2 to edit without redeploying and share across agents. Return keys from `getRemoteSkills()`:
 
 ```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.";
-  }
-
-  // Optional: keep more messages verbatim before summarising (default 15).
-  // protected maxMessagesBeforeCompaction = 50;
-
-  // Optional: disable compaction (still uses fastModel for conversation title/summary).
-  // protected maxMessagesBeforeCompaction = undefined;
+protected getRemoteSkills() {
+  return ["billing.md", "tax.md"];
 }
 ```
 
-#### Conversations (D1)
+Loaded from `SKILLS_BUCKET` under the `skills/` prefix — the object's `description` metadata shows up front, the body loads on demand. Skipped (with a logged error) if `SKILLS_BUCKET` isn't bound.
 
-`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).
+## Authentication
 
-**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.
+### JWT
 
-**Retention** — Set `conversationRetentionDays` to auto-delete inactive conversations:
+Override the static `getJwtAuthConfig(env)` to verify a JWT on connect (static so an `Assistant` can check before routing). Return `undefined` to skip.
 
 ```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.";
+export class SupportAgent extends Agent {
+  static getJwtAuthConfig(env: Cloudflare.Env) {
+    return {
+      allowedIssuers: [env.IDENTITY_ENDPOINT], // strings or RegExp
+      audience: "my-api",
+      requiredScopes: ["support.read"],
+      getClaims: (payload) => ({
+        userGuid: payload.user_guid as string,
+        agreementNumber: payload.agreement_number as number,
+      }),
+    };
   }
 
-  // ChatAgentHarness defaults to 90 days. Override or set to undefined to disable.
-  protected conversationRetentionDays = 30;
+  // ...
 }
 ```
 
-When the retention period expires, the D1 row is deleted, WebSocket connections are closed, and the DO's SQLite storage is wiped.
+On failure the socket closes (`4001` unauthorized, `4003` forbidden) and status becomes `"unauthorized"`. The token is read from `Authorization: Bearer …`, then the `Sec-WebSocket-Protocol: bearer, <token>` header.
 
-**Querying** — From a connected client:
+### User context
 
-```typescript
-const conversations = await agent.call("getConversations");
-```
-
-#### Message Ratings (D1)
-
-Users can rate individual messages with thumbs up/down. Ratings are stored in D1 and can be updated if the user changes their mind.
+Implement `getUserContext(jwtToken)` to load per-user data after auth. It's exposed as `ctx._userContext` in `getModel`, `getSystemPrompt`, tools, and skill `authorize`. Runs only when JWT auth is configured.
 
 ```typescript
-// Rate a message (1 = thumbs up, -1 = thumbs down)
-await agent.call("rateMessage", [messageId, 1]);
-
-// Change rating
-await agent.call("rateMessage", [messageId, -1]);
-
-// Get all ratings for the current conversation
-const ratings = await agent.call("getMessageRatings");
-// Returns: { "message_id_1": 1, "message_id_2": -1, ... }
+protected async getUserContext(jwtToken: string) {
+  const profile = await fetchProfile(jwtToken);
+  return { role: profile.role, tokens: profile.tokens };
+}
 ```
 
-Ratings are stored per message and upserted on conflict — calling `rateMessage` on an already-rated message updates the rating. Requires [`schema/chat.sql`](schema/chat.sql) which includes the `message_ratings` table.
-
----
-
-## API Reference
-
-### `@economic/agents`
-
-| 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 `session` and `logEvent` for tool context   |
-| `OnChatMessageOptions` | Type: options passed to `onChatMessage`                                    |
-| `BuildLLMParamsConfig` | Type: config for standalone `buildLLMParams`                               |
-
-### `@economic/agents-react`
-
-React hooks are in a separate package. See [`@economic/agents-react`](../react/README.md) for full documentation.
+## Observability
 
-| 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"`                                                   |
+Emitted per turn from the `ai` SDK's OpenTelemetry spans, no setup beyond bindings:
 
-### CLI
+- **Audit logs** → one JSON object per turn in `AGENTS_AUDIT_LOGS` (model, actor, IP, prompt, response, tool calls).
+- **Analytics** → per-turn and per-tool data points in `AGENTS_ANALYTICS`.
 
-| 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) |
+## API reference
 
----
+Imported from `@economic/agents` unless noted.
 
-## CLI
-
-The package includes a CLI for scaffolding skills and tools.
-
-### Generate a Skill
-
-```bash
-npx @economic/agents generate skill weather
-```
-
-This will:
-
-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
-
-### Generate a Tool
-
-```bash
-npx @economic/agents generate tool geocode
-```
+### Classes
 
-This will:
+| Export      | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| `Agent`     | Core agent base. Implement `getModel`/`getSystemPrompt`. |
+| `ChatAgent` | `Agent` + compaction and message feedback.               |
+| `Assistant` | Per-user manager of `ChatAgent` conversations.           |
 
-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
+### Helpers and types
 
-### Auto-registration
+| Export                                                                   | Description                                                                     |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `tool(def)` / `Tool` / `ToolSet`                                         | Define a tool with an optional `authorize(ctx)` guard.                          |
+| `skill(def)` / `Skill`                                                   | Define a skill (`name`, `description`, `instructions`, `tools?`, `authorize?`). |
+| `ToolContext`                                                            | `RequestContext & { _userContext?: UserContext }`.                              |
+| `AgentEnv`                                                               | The bindings the runtime expects.                                               |
+| `AgentConnectionState` / `AgentConnectionStatus` / `AgentConnectionType` | Connection state shared with the client.                                        |
 
-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.
+### Members
 
-For `ChatAgentHarness`, the CLI modifies `getSkills()` or `getTools()` methods. For `ChatAgent` or `Agent`, it modifies `buildLLMParams()` calls.
+| Member                                         | On          | Description                                 |
+| ---------------------------------------------- | ----------- | ------------------------------------------- |
+| `getModel(ctx?)`                               | `Agent`     | Required. Model for inference.              |
+| `getSystemPrompt(ctx?)`                        | `Agent`     | Required. System prompt.                    |
+| `getTools()`                                   | `Agent`     | Always-on tools (default `{}`).             |
+| `getSkills()`                                  | `Agent`     | Local skills (default `[]`).                |
+| `getRemoteSkills()`                            | `Agent`     | R2 skill keys (default `[]`).               |
+| `static getJwtAuthConfig(env)`                 | `Agent`     | Optional JWT verification config.           |
+| `getUserContext(jwtToken)`                     | `Agent`     | Optional per-user context after auth.       |
+| `submitMessageFeedback` / `getMessageFeedback` | `ChatAgent` | Callable message feedback.                  |
+| `agent`                                        | `Assistant` | Required. Your `ChatAgent` subclass.        |
+| `fastModel`                                    | `Assistant` | Required. Cheap model for titles/summaries. |
+| `createChat` / `getChats` / `deleteChat`       | `Assistant` | Callable conversation management.           |
 
-If the CLI detects complex patterns (spread operators, function calls, variables), it will print manual registration instructions instead.
+### Package root (`@economic/agents`)
 
----
+| Export              | Description                                                              |
+| ------------------- | ------------------------------------------------------------------------ |
+| `routeAgentRequest` | Routes a request to the right Durable Object; echoes the WS subprotocol. |
 
 ## Development
 
 ```bash
 npm install
 npm test
-npm pack
+npm run build
 ```
 
 .