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

package/README.md

@@ -1,6 +1,6 @@
 # @economic/agents
 
-Base class and AI SDK wrappers for building LLM chat agents on Cloudflare's Agents SDK with lazy skill loading and optional message compaction.
+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.
 
 ```bash
 npm install @economic/agents ai @cloudflare/ai-chat
@@ -12,8 +12,8 @@ npm install @economic/agents ai @cloudflare/ai-chat
 
 `@economic/agents` provides:
 
-- **`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.
+- **`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.
 
 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.
 
@@ -22,11 +22,12 @@ Skills and compaction are AI SDK concerns — they control what goes to the LLM.
 ## Quick start
 
 ```typescript
-import { AIChatAgent, streamText } from "@economic/agents";
-import type { Skill } from "@economic/agents";
+import { streamText } from "ai";
 import { openai } from "@ai-sdk/openai";
-import { stepCountIs, tool } from "ai";
+import { tool } from "ai";
 import { z } from "zod";
+import { AIChatAgent } from "@economic/agents";
+import type { Skill } from "@economic/agents";
 
 const searchSkill: Skill = {
   name: "search",
@@ -42,18 +43,18 @@ 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 stream = await streamText({
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
       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();
+    return streamText(params).toUIMessageStreamResponse();
   }
 }
 ```
@@ -83,36 +84,61 @@ Run `wrangler types` after to generate typed `Env` bindings.
 
 ## `AIChatAgent`
 
-Extend this class and implement `onChatMessage`. Call our `streamText` wrapper — which accepts `UIMessage[]`, skills, and compaction — and return the response.
+Extend this class and implement `onChatMessage`. Call `this.buildLLMParams()` to prepare the call, then pass the result to `streamText` or `generateText`.
 
 ```typescript
-import { AIChatAgent, streamText } from "@economic/agents";
-import type { RequestBody } from "./types";
+import { streamText } from "ai";
+import { AIChatAgent } from "@economic/agents";
 
 export class ChatAgent extends AIChatAgent<Env> {
   async onChatMessage(onFinish, options) {
-    const body = (options?.body ?? {}) as RequestBody;
+    const body = (options?.body ?? {}) as { userTier: "free" | "pro" };
     const model = body.userTier === "pro" ? openai("gpt-4o") : openai("gpt-4o-mini");
 
-    const stream = await streamText({
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
       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,
+      tools: { alwaysOnTool }, // always active, regardless of loaded skills
     });
-    return stream.toUIMessageStreamResponse();
+    return streamText(params).toUIMessageStreamResponse();
   }
 }
 ```
 
+### `this.buildLLMParams(config)`
+
+Protected method on `AIChatAgent`. Wraps the standalone `buildLLMParams` function with:
+
+- `messages` pre-filled from `this.messages`
+- `activeSkills` pre-filled from `await this.getLoadedSkills()`
+- `fastModel` injected from `this.fastModel`
+- `log` injected into `experimental_context` alongside `options.body`
+- Automatic error logging for non-clean finish reasons
+- Compaction threshold defaulting: when `maxMessagesBeforeCompaction` is not in the config, defaults to `30`. Pass `maxMessagesBeforeCompaction: undefined` explicitly to disable compaction.
+
+Config is everything accepted by the standalone `buildLLMParams` except `messages`, `activeSkills`, and `fastModel`.
+
+### `fastModel` property
+
+Override `fastModel` on your subclass to enable automatic compaction and future background conversation summarization:
+
+```typescript
+export class MyAgent extends AIChatAgent<Env> {
+  protected fastModel = openai("gpt-4o-mini");
+  // ...
+}
+```
+
+When `fastModel` is set, compaction runs automatically with a default threshold of 30 messages. No per-call configuration is needed in the common case. You can still customise or disable it per-call via `maxMessagesBeforeCompaction`.
+
+When `fastModel` is `undefined` (the default), compaction is disabled regardless of `maxMessagesBeforeCompaction`.
+
 ### `getLoadedSkills()`
 
-Protected method on `AIChatAgent`. Returns skill names persisted from previous turns (read from DO SQLite). Pass the result as `activeSkills`.
+Protected method on `AIChatAgent`. Returns skill names persisted from previous turns (read from DO SQLite). Used internally by `this.buildLLMParams()`.
 
 ### `persistMessages` (automatic)
 
@@ -120,8 +146,9 @@ 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.
+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)
 
@@ -129,64 +156,48 @@ Replays the full message history to newly connected clients — without this, a
 
 ---
 
-## `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.              |
+## `buildLLMParams` (standalone)
 
-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)
+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
-// With skills and compaction
-const stream = await streamText({
-  model: openai("gpt-4o"),
-  messages: await convertToModelMessages(this.messages),
+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],
-  activeSkills: await this.getLoadedSkills(),
   tools: { myAlwaysOnTool },
-  compact: { model: openai("gpt-4o-mini"), maxMessages: 30 },
-  onFinish,
+  stopWhen: stepCountIs(20), // defaults to stepCountIs(20)
 });
-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();
+return streamText(params).toUIMessageStreamResponse();
+// or: generateText(params);
 ```
 
----
-
-## `generateText` wrapper
-
-Same additions as `streamText` — accepts `UIMessage[]`, `skills` / `activeSkills`, and `compact`.
-
-```typescript
-const result = await generateText({
-  model: openai("gpt-4o"),
-  messages: await convertToModelMessages(this.messages),
-  skills: [searchSkill],
-  activeSkills: await this.getLoadedSkills(),
-});
-```
+| 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.
 
 ---
 
@@ -252,27 +263,62 @@ export const datetimeSkill: Skill = {
 
 ## Compaction
 
-When `compact` is provided to `streamText` / `generateText`, the wrapper compacts `messages` before converting and sending to the model:
+When `fastModel` is set on the agent class, compaction runs automatically before each turn:
 
-1. The message list is split into an older window and a recent verbatim tail (`maxMessages`).
-2. A model call generates a concise summary of the older window.
+1. The message list is split into an older window and a recent verbatim tail.
+2. `fastModel` generates a concise summary of the older window.
 3. That summary + the verbatim tail is what gets sent to the LLM.
 4. Full history in DO SQLite is unaffected — compaction is in-memory only.
 
+### Enabling compaction
+
+Override `fastModel` on your subclass. Compaction runs automatically with a default threshold of 30 messages — no per-call config needed:
+
+```typescript
+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();
+  }
+}
+```
+
+### Customising the threshold
+
+Pass `maxMessagesBeforeCompaction` to override the default of 30:
+
 ```typescript
-const stream = await streamText({
+const params = await this.buildLLMParams({
+  options,
+  onFinish,
   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
-  },
+  maxMessagesBeforeCompaction: 50, // keep last 50 messages verbatim
+});
+```
+
+### Disabling compaction
+
+Pass `maxMessagesBeforeCompaction: undefined` explicitly to disable compaction for that call, even when `fastModel` is set:
+
+```typescript
+const params = await this.buildLLMParams({
+  options,
   onFinish,
+  model: openai("gpt-4o"),
+  maxMessagesBeforeCompaction: undefined, // compaction off
 });
-return stream.toUIMessageStreamResponse();
 ```
 
+Compaction is always off when `fastModel` is `undefined` (the base class default).
+
 ---
 
 ## Built-in meta tools
@@ -296,7 +342,21 @@ Returns a summary of active tools, loaded skills, and skills available to load.
 
 ## Passing request context to tools
 
-Pass arbitrary data via the `body` option of `useAgentChat`. It arrives as `experimental_context` in tool `execute` functions:
+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
@@ -304,90 +364,169 @@ useAgentChat({ body: { authorization: token, userId: "u_123" } });
 
 // Tool
 execute: async (args, { experimental_context }) => {
-  const { authorization } = experimental_context as { authorization: string };
+  const ctx = experimental_context as ToolContext;
+  await ctx.log("tool called", { userId: ctx.userId });
+  const data = await fetchSomething(ctx.authorization);
+  return data;
 };
+```
+
+`log` is a no-op when `AGENT_DB` is not bound — so no changes are needed in tools when running without a D1 database.
+
+---
+
+## Audit logging — D1 setup
+
+`AIChatAgent` writes audit events to a Cloudflare D1 database when `AGENT_DB` is bound on the environment. Each agent worker has its own dedicated D1 database.
+
+### 1. Create the D1 database
+
+In the [Cloudflare dashboard](https://dash.cloudflare.com) → **Workers & Pages** → **D1** → **Create database**. Note the database name and ID.
+
+### 2. Create the schema
+
+Open the database in the D1 dashboard, select **Console**, and run the contents of [`schema/audit_events.sql`](schema/audit_events.sql):
+
+```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);
+```
+
+Safe to re-run — all statements use `IF NOT EXISTS`.
+
+### 3. Bind it in `wrangler.jsonc`
+
+```jsonc
+"d1_databases": [
+  { "binding": "AGENT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
+]
+```
 
-// In onChatMessage — forward body to tools
-const stream = await streamText({
-  ...
-  experimental_context: options?.body,
+Then run `wrangler types` to regenerate the `Env` type.
+
+### 4. Seed local development
+
+```bash
+npm run db:setup
+```
+
+This runs the schema SQL against the local D1 SQLite file (`.wrangler/state/`). Re-running is harmless.
+
+If `AGENT_DB` is not bound, all `log()` calls are silent no-ops — the agent works without it.
+
+### Providing `userId`
+
+The `user_id` column is `NOT NULL`. The base class reads `userId` automatically from `options.body` — no subclass override is needed. The client must include it in the `body` passed to `useAgentChat`:
+
+```typescript
+useAgentChat({
+  agent,
+  body: {
+    userId: "148583_matt", // compose from agreement number + user identifier
+    // ...other fields
+  },
 });
-return stream.toUIMessageStreamResponse();
 ```
 
+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.
+
 ---
 
-## Advanced: `createSkills` directly
+## Conversations — D1 setup
 
-`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.
+`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.
 
-```typescript
-import { createSkills, filterEphemeralMessages } from "@economic/agents";
+### Schema
 
-const skillsCtx = createSkills({
-  tools: alwaysOnTools,
-  skills: permittedSkills,
-  initialLoadedSkills: await getLoadedSkills(), // from storage
-  systemPrompt: "You are a helpful assistant.",
-});
+Run the contents of [`schema/conversations.sql`](schema/conversations.sql) in the D1 dashboard console (same database as `audit_events`):
 
-const result = aiStreamText({
-  model,
-  system: skillsCtx.getSystem(),
-  messages: convertToModelMessages(messages),
-  tools: skillsCtx.tools,
-  activeTools: skillsCtx.activeTools,
-  prepareStep: skillsCtx.prepareStep,
-});
+```sql
+CREATE TABLE IF NOT EXISTS conversations (
+  durable_object_id TEXT PRIMARY KEY,
+  user_id           TEXT NOT NULL,
+  title             TEXT,
+  summary           TEXT,
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS conversations_user ON conversations(user_id);
+CREATE INDEX IF NOT EXISTS conversations_ts   ON conversations(updated_at);
 ```
 
+Safe to re-run — all statements use `IF NOT EXISTS`.
+
+### Upsert behaviour
+
+- **First turn**: a new row is inserted with `created_at` and `updated_at` both set to now. `title` and `summary` are `NULL`.
+- **Subsequent turns**: only `user_id` and `updated_at` are updated. `created_at`, `title`, and `summary` are never overwritten by the upsert.
+- `title` and `summary` are populated automatically after the conversation goes idle (see below).
+
+### Automatic title and summary generation
+
+After every turn, `AIChatAgent` schedules a `generateSummary` callback to fire 30 minutes in the future. If another message arrives before the timer fires, the schedule is cancelled and reset — so the callback only runs once the conversation has been idle for 30 minutes.
+
+When `generateSummary` fires it:
+
+1. Fetches the current summary from D1 (if any).
+2. Takes the last 30 messages (`SUMMARY_CONTEXT_MESSAGES`) to keep the prompt bounded.
+3. Calls `fastModel` with `Output.object()` to generate a structured `{ title, summary }`.
+4. If a previous summary exists, it is included in the prompt so the model can detect direction changes.
+5. Writes the result back to the `conversations` row.
+
+No subclass code is needed — this runs automatically when `AGENT_DB` is bound and `fastModel` is set on the class.
+
+### Querying conversation lists
+
+To fetch all conversations for a user, ordered by most recent:
+
+```sql
+SELECT durable_object_id, title, summary, created_at, updated_at
+FROM conversations
+WHERE user_id = '148583_matt'
+ORDER BY updated_at DESC;
+```
+
+If `userId` is not set on the request body, the upsert is skipped and a `console.error` is emitted — the same behaviour as audit logging.
+
 ---
 
 ## API reference
 
 ### Classes
 
-| Export        | Description                                                                                         |
-| ------------- | --------------------------------------------------------------------------------------------------- |
-| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state in DO SQLite. |
+| Export        | Description                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state, history replay, and audit log. |
 
 ### 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. |
+| 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.  |
-| `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 }` |
+| Export                 | Description                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `Skill`                | A named group of tools with optional guidance.                                  |
+| `AgentContext<TBody>`  | Request body type merged with `log`. Use as the type of `experimental_context`. |
+| `BuildLLMParamsConfig` | Config type for the standalone `buildLLMParams` function.                       |
 
 ---
 
 ## Development
 
 ```bash
-vp install   # install dependencies
-vp test      # run tests
-vp pack      # build
+npm install   # install dependencies
+npm test      # run tests
+npm pack      # build
 ```