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

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",
@@ -43,17 +44,14 @@ const searchSkill: Skill = {
 
 export class MyAgent extends AIChatAgent<Env> {
   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 +81,44 @@ 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()`
+- `log` injected into `experimental_context` alongside `options.body`
+- Automatic error logging for non-clean finish reasons
+
+Config is everything accepted by the standalone `buildLLMParams` except `messages` and `activeSkills`.
+
 ### `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 +126,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 +136,49 @@ 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:
+## `buildLLMParams` (standalone)
 
-| 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)
+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.                |
+| `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.
 
 ---
 
@@ -252,7 +244,7 @@ export const datetimeSkill: Skill = {
 
 ## Compaction
 
-When `compact` is provided to `streamText` / `generateText`, the wrapper compacts `messages` before converting and sending to the model:
+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.
@@ -260,17 +252,17 @@ When `compact` is provided to `streamText` / `generateText`, the wrapper compact
 4. Full history in DO SQLite is unaffected — compaction is in-memory only.
 
 ```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
   },
-  onFinish,
 });
-return stream.toUIMessageStreamResponse();
+return streamText(params).toUIMessageStreamResponse();
 ```
 
 ---
@@ -296,7 +288,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 +310,95 @@ 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;
 };
-
-// In onChatMessage — forward body to tools
-const stream = await streamText({
-  ...
-  experimental_context: options?.body,
-});
-return stream.toUIMessageStreamResponse();
 ```
 
+`log` is a no-op when `AUDIT_DB` is not bound — so no changes are needed in tools when running without a D1 database.
+
 ---
 
-## Advanced: `createSkills` directly
+## Audit logging — 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` 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.
 
-```typescript
-import { createSkills, filterEphemeralMessages } from "@economic/agents";
+### 1. Create the D1 database
 
-const skillsCtx = createSkills({
-  tools: alwaysOnTools,
-  skills: permittedSkills,
-  initialLoadedSkills: await getLoadedSkills(), // from storage
-  systemPrompt: "You are a helpful assistant.",
-});
+In the [Cloudflare dashboard](https://dash.cloudflare.com) → **Workers & Pages** → **D1** → **Create database**. Note the database name and ID.
 
-const result = aiStreamText({
-  model,
-  system: skillsCtx.getSystem(),
-  messages: convertToModelMessages(messages),
-  tools: skillsCtx.tools,
-  activeTools: skillsCtx.activeTools,
-  prepareStep: skillsCtx.prepareStep,
-});
+### 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" }
+]
 ```
 
+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 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.                                  |
+| `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
-vp install   # install dependencies
-vp test      # run tests
-vp pack      # build
+npm install   # install dependencies
+npm test      # run tests
+npm pack      # build
 ```

package/dist/index.d.mts

@@ -1,49 +1,7 @@
-import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
-import { LanguageModel, ToolSet, UIMessage, generateText as generateText$1, streamText as streamText$1 } from "ai";
+import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/ai-chat";
+import { LanguageModel, ToolSet, UIMessage, generateText, streamText } from "ai";
 
-//#region src/agents/AIChatAgent.d.ts
-/**
- * Base class for Cloudflare Agents SDK chat agents with lazy skill loading.
- *
- * Handles CF infrastructure concerns only: DO SQLite persistence for loaded
- * skill state, stripping skill meta-tool messages before persistence, and
- * history replay to newly connected clients.
- *
- * Skill loading, compaction, and LLM communication are delegated to the
- * `streamText` / `generateText` wrappers from `@economic/agents`, which you
- * call directly inside `onChatMessage`.
- */
-declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent$1<Env> {
-  /**
-   * Skill names persisted from previous turns, read from DO SQLite.
-   * Pass as `activeSkills` to `streamText` or `generateText`.
-   * Returns an empty array if no skills have been loaded yet.
-   */
-  protected getLoadedSkills(): Promise<string[]>;
-  /**
-   * Extracts skill state from activate_skill results, persists to DO SQLite,
-   * then strips all skill meta-tool messages before delegating to super.
-   *
-   * Three things happen here:
-   *
-   * 1. Scan activate_skill tool results for the SKILL_STATE_SENTINEL. When
-   *    found, the embedded JSON array of loaded skill names is written to DO
-   *    SQLite (`this.sql`). This replaces D1 — no extra binding needed.
-   *
-   * 2. All activate_skill and list_capabilities messages are stripped entirely.
-   *    Skill state is restored from DO SQLite at turn start via getLoadedSkills(),
-   *    so these messages are not needed for future turns.
-   *
-   * 3. super.persistMessages writes the cleaned message list to DO SQLite and
-   *    broadcasts to connected clients.
-   */
-  persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
-    _deleteStaleRows?: boolean;
-  }): Promise<void>;
-  private ensureSkillTableExists;
-}
-//#endregion
-//#region src/ai/skills.d.ts
+//#region src/features/skills/index.d.ts
 /**
  * A named group of related tools that can be loaded together on demand.
  *
@@ -63,63 +21,110 @@ interface Skill {
   guidance?: string;
   tools: ToolSet;
 }
-type SkillsCallSettings = {
-  /**
-   * Skills available for on-demand loading this turn. When provided, the wrapper
-   * automatically wires up activate_skill, list_capabilities, activeTools, and
-   * prepareStep. Skills are additive — any activeTools you also pass are merged.
-   */
-  skills?: Skill[];
-  /**
-   * Names of skills loaded in previous turns. Pass `await this.getLoadedSkills()`
-   * from your AIChatAgent subclass.
-   */
-  activeSkills?: string[];
-};
 //#endregion
-//#region src/ai/compaction.d.ts
+//#region src/features/compaction/index.d.ts
 type CompactOptions = {
   /** Model used to generate the compaction summary */model: LanguageModel; /** Number of recent messages to keep verbatim; older messages are summarised */
   maxMessages: number;
 };
-type CompactionCallSettings = {
-  /**
-   * When provided, compacts messages before sending to the model. Older messages
-   * are summarised into a single system message using the given model.
-   */
+//#endregion
+//#region src/llm.d.ts
+type LLMParams = Parameters<typeof streamText>[0] & Parameters<typeof generateText>[0];
+type BuildLLMParamsConfig = Omit<LLMParams, "messages" | "experimental_context" | "abortSignal"> & {
+  /** CF options object — extracts `abortSignal` and `experimental_context` (from `body`). */options: OnChatMessageOptions | undefined; /** Conversation history (`this.messages`). Converted to `ModelMessage[]` internally. */
+  messages: UIMessage[]; /** Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`. */
+  activeSkills?: string[]; /** Skills available for on-demand loading this turn. */
+  skills?: Skill[]; /** When provided, compacts old messages before sending to the model. */
   compact?: CompactOptions;
 };
-//#endregion
-//#region src/ai/wrappers.d.ts
-type AiStreamTextParams = Parameters<typeof streamText$1>[0];
-type AiGenerateTextParams = Parameters<typeof generateText$1>[0];
-type StreamTextParams = AiStreamTextParams & SkillsCallSettings & CompactionCallSettings;
-type GenerateTextParams = AiGenerateTextParams & SkillsCallSettings & CompactionCallSettings;
 /**
- * Drop-in replacement for `streamText` from the AI SDK with added support for
- * lazy skill loading and message compaction.
+ * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
  *
- * All standard AI SDK parameters are accepted and passed through unchanged.
+ * Handles message conversion, optional compaction, skill wiring (`activate_skill`,
+ * `list_capabilities`, `prepareStep`), and context/abort signal extraction from
+ * the Cloudflare Agents SDK `options` object.
  *
- * @param params.skills - Skills available for on-demand loading this turn. Wires up
- *   `activate_skill`, `list_capabilities`, `activeTools`, and `prepareStep` automatically.
- * @param params.activeSkills - Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`.
- * @param params.compact - When provided, compacts messages before the model call. Older messages
- *   are summarised into a single system message using the given model.
+ * The returned object can be spread directly into `streamText` or `generateText`:
+ *
+ * ```typescript
+ * const params = await buildLLMParams({ ... });
+ * return streamText(params).toUIMessageStreamResponse();
+ * ```
  */
-declare function streamText(params: StreamTextParams): Promise<ReturnType<typeof streamText$1>>;
+declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams>;
+//#endregion
+//#region src/agents/AIChatAgent.d.ts
 /**
- * Drop-in replacement for `generateText` from the AI SDK with added support for
- * lazy skill loading and message compaction.
+ * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
+ * and built-in audit logging.
  *
- * All standard AI SDK parameters are accepted and passed through unchanged.
+ * Handles CF infrastructure concerns only: DO SQLite persistence for loaded
+ * skill state, stripping skill meta-tool messages before persistence, history
+ * replay to newly connected clients, and writing audit events to D1.
  *
- * @param params.skills - Skills available for on-demand loading this turn. Wires up
- *   `activate_skill`, `list_capabilities`, `activeTools`, and `prepareStep` automatically.
- * @param params.activeSkills - Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`.
- * @param params.compact - When provided, compacts messages before the model call. Older messages
- *   are summarised into a single system message using the given model.
+ * Skill loading, compaction, and LLM communication are delegated to
+ * `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
  */
-declare function generateText(params: GenerateTextParams): Promise<ReturnType<typeof generateText$1>>;
+declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent$1<Env> {
+  /**
+   * Writes an audit event to D1 if `AUDIT_DB` is bound on the environment,
+   * otherwise silently does nothing.
+   *
+   * Called automatically after every turn (from `persistMessages`) and on
+   * non-clean finish reasons (from `buildLLMParams`). Also available via
+   * `experimental_context.log` in tool `execute` functions.
+   */
+  protected log(message: string, payload?: Record<string, unknown>): Promise<void>;
+  /**
+   * Builds the parameter object for a `streamText` or `generateText` call,
+   * pre-filling `messages` and `activeSkills` from this agent instance.
+   * Injects `log` into `experimental_context` and logs non-clean finish reasons.
+   *
+   * ```typescript
+   * const params = await this.buildLLMParams({ options, onFinish, model, system: "..." });
+   * return streamText(params).toUIMessageStreamResponse();
+   * ```
+   */
+  protected buildLLMParams(config: Omit<BuildLLMParamsConfig, "messages" | "activeSkills">): ReturnType<typeof buildLLMParams>;
+  /**
+   * Skill names persisted from previous turns, read from DO SQLite.
+   * Returns an empty array if no skills have been loaded yet.
+   */
+  protected getLoadedSkills(): Promise<string[]>;
+  /**
+   * Extracts skill state from activate_skill results, persists to DO SQLite,
+   * logs a turn summary, then strips all skill meta-tool messages before
+   * delegating to super.
+   *
+   * 1. Scans activate_skill tool results for SKILL_STATE_SENTINEL. When found,
+   *    the embedded JSON array of loaded skill names is written to DO SQLite.
+   *
+   * 2. Logs a turn summary via `log()`. Best-effort: fire-and-forget.
+   *
+   * 3. Strips all activate_skill and list_capabilities messages from history.
+   *
+   * 4. Delegates to super.persistMessages for message storage and WS broadcast.
+   */
+  persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
+    _deleteStaleRows?: boolean;
+  }): Promise<void>;
+  private ensureSkillTableExists;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * The context object available throughout an agent's lifetime — passed via
+ * `experimental_context` to tool `execute` functions. Contains the typed
+ * request body merged with platform capabilities like `log`.
+ *
+ * Define your own body shape and compose:
+ * ```typescript
+ * interface MyBody { userId: string; userTier: "free" | "pro" }
+ * type MyContext = AgentContext<MyBody>;
+ * ```
+ */
+type AgentContext<TBody = Record<string, unknown>> = TBody & {
+  log: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
+};
 //#endregion
-export { AIChatAgent, type CompactOptions, type GenerateTextParams, type Skill, type StreamTextParams, generateText, streamText };
+export { AIChatAgent, type AgentContext, type BuildLLMParamsConfig, type CompactOptions, type Skill, buildLLMParams };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
-import { generateText as generateText$1, jsonSchema, streamText as streamText$1, tool } from "ai";
-//#region src/ai/skills.ts
+import { convertToModelMessages, generateText, jsonSchema, stepCountIs, tool } from "ai";
+//#region src/features/skills/index.ts
 const ACTIVATE_SKILL = "activate_skill";
 const LIST_CAPABILITIES = "list_capabilities";
 function buildActivateSkillDescription(skills) {
@@ -122,94 +122,6 @@ function createSkills(config) {
 	};
 }
 const ALREADY_LOADED_OUTPUT = "All requested skills were already loaded.";
-//#endregion
-//#region src/agents/AIChatAgent.ts
-/**
-* Base class for Cloudflare Agents SDK chat agents with lazy skill loading.
-*
-* Handles CF infrastructure concerns only: DO SQLite persistence for loaded
-* skill state, stripping skill meta-tool messages before persistence, and
-* history replay to newly connected clients.
-*
-* Skill loading, compaction, and LLM communication are delegated to the
-* `streamText` / `generateText` wrappers from `@economic/agents`, which you
-* call directly inside `onChatMessage`.
-*/
-var AIChatAgent = class extends AIChatAgent$1 {
-	/**
-	* Skill names persisted from previous turns, read from DO SQLite.
-	* Pass as `activeSkills` to `streamText` or `generateText`.
-	* Returns an empty array if no skills have been loaded yet.
-	*/
-	async getLoadedSkills() {
-		try {
-			this.ensureSkillTableExists();
-			const rows = this.sql`SELECT active_skills FROM skill_state WHERE id = 1`;
-			if (rows.length === 0) return [];
-			return JSON.parse(rows[0].active_skills);
-		} catch {
-			return [];
-		}
-	}
-	/**
-	* Extracts skill state from activate_skill results, persists to DO SQLite,
-	* then strips all skill meta-tool messages before delegating to super.
-	*
-	* Three things happen here:
-	*
-	* 1. Scan activate_skill tool results for the SKILL_STATE_SENTINEL. When
-	*    found, the embedded JSON array of loaded skill names is written to DO
-	*    SQLite (`this.sql`). This replaces D1 — no extra binding needed.
-	*
-	* 2. All activate_skill and list_capabilities messages are stripped entirely.
-	*    Skill state is restored from DO SQLite at turn start via getLoadedSkills(),
-	*    so these messages are not needed for future turns.
-	*
-	* 3. super.persistMessages writes the cleaned message list to DO SQLite and
-	*    broadcasts to connected clients.
-	*/
-	async persistMessages(messages, excludeBroadcastIds = [], options) {
-		let latestSkillState;
-		for (const msg of messages) {
-			if (msg.role !== "assistant" || !msg.parts) continue;
-			for (const part of msg.parts) {
-				if (!("toolCallId" in part)) continue;
-				const { type, output } = part;
-				if (type !== `tool-activate_skill` || typeof output !== "string") continue;
-				const sentinelIdx = output.indexOf(SKILL_STATE_SENTINEL);
-				if (sentinelIdx !== -1) try {
-					const stateJson = output.slice(sentinelIdx + 18);
-					latestSkillState = JSON.parse(stateJson);
-				} catch {}
-			}
-		}
-		if (latestSkillState !== void 0) {
-			this.ensureSkillTableExists();
-			this.sql`INSERT OR REPLACE INTO skill_state(id, active_skills) VALUES(1, ${JSON.stringify(latestSkillState)})`;
-		}
-		const filtered = stripSkillMessages(messages);
-		return super.persistMessages(filtered, excludeBroadcastIds, options);
-	}
-	ensureSkillTableExists() {
-		this.sql`CREATE TABLE IF NOT EXISTS skill_state (id INTEGER PRIMARY KEY, active_skills TEXT NOT NULL DEFAULT '[]')`;
-	}
-};
-function stripSkillMessages(messages) {
-	return messages.flatMap((msg) => {
-		if (msg.role !== "assistant" || !msg.parts?.length) return [msg];
-		const filtered = msg.parts.filter((part) => {
-			if (!("toolCallId" in part)) return true;
-			const { type } = part;
-			return type !== `tool-activate_skill` && type !== `tool-list_capabilities`;
-		});
-		if (filtered.length === 0) return [];
-		if (filtered.length === msg.parts.length) return [msg];
-		return [{
-			...msg,
-			parts: filtered
-		}];
-	});
-}
 const TOOL_RESULT_PREVIEW_CHARS = 200;
 const SUMMARY_MAX_TOKENS = 4e3;
 /**
@@ -277,7 +189,7 @@ ${formatMessagesForSummary(recentMessages)}
 
 Write a concise summary:`;
 	try {
-		const { text } = await generateText$1({
+		const { text } = await generateText({
 			model,
 			messages: [{
 				role: "user",
@@ -314,71 +226,221 @@ async function compactIfNeeded(messages, model, tailSize) {
 	return compactMessages(messages, model, tailSize);
 }
 //#endregion
-//#region src/ai/wrappers.ts
-async function resolveCallSettings(params) {
-	const { messages, skills, activeSkills, compact, activeTools, prepareStep, ...rest } = params;
-	const processedMessages = compact && messages ? await compactIfNeeded(messages, compact.model, compact.maxMessages) : messages;
-	let callSettings = {
+//#region src/llm.ts
+/**
+* Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
+*
+* Handles message conversion, optional compaction, skill wiring (`activate_skill`,
+* `list_capabilities`, `prepareStep`), and context/abort signal extraction from
+* the Cloudflare Agents SDK `options` object.
+*
+* The returned object can be spread directly into `streamText` or `generateText`:
+*
+* ```typescript
+* const params = await buildLLMParams({ ... });
+* return streamText(params).toUIMessageStreamResponse();
+* ```
+*/
+async function buildLLMParams(config) {
+	const { options, messages, activeSkills = [], skills, compact, ...rest } = config;
+	const rawMessages = await convertToModelMessages(messages);
+	const processedMessages = compact ? await compactIfNeeded(rawMessages, compact.model, compact.maxMessages) : rawMessages;
+	const baseParams = {
 		...rest,
 		messages: processedMessages,
-		activeTools,
-		prepareStep
+		experimental_context: options?.body,
+		abortSignal: options?.abortSignal,
+		stopWhen: rest.stopWhen ?? stepCountIs(20)
 	};
-	if (skills?.length) {
-		const skillsCtx = createSkills({
-			tools: rest.tools ?? {},
-			skills,
-			initialLoadedSkills: activeSkills ?? [],
-			systemPrompt: typeof rest.system === "string" ? rest.system : void 0
-		});
-		const mergedPrepareStep = async (options) => {
-			const consumerResult = (prepareStep ? await prepareStep(options) : void 0) ?? {};
-			const skillsResult = await skillsCtx.prepareStep(options) ?? {};
-			return {
-				...consumerResult,
-				activeTools: [...new Set([...skillsResult.activeTools ?? [], ...activeTools ?? []])],
-				system: skillsResult.system ?? consumerResult.system
-			};
-		};
-		callSettings = {
-			...callSettings,
-			system: skillsCtx.getSystem() || (typeof rest.system === "string" ? rest.system : void 0),
-			tools: skillsCtx.tools,
-			activeTools: [...new Set([...skillsCtx.activeTools, ...activeTools ?? []])],
-			prepareStep: mergedPrepareStep
+	if (!skills?.length) return baseParams;
+	const skillsCtx = createSkills({
+		tools: rest.tools ?? {},
+		skills,
+		initialLoadedSkills: activeSkills,
+		systemPrompt: typeof rest.system === "string" ? rest.system : void 0
+	});
+	const prepareStep = async (stepOptions) => {
+		const skillsResult = await skillsCtx.prepareStep(stepOptions) ?? {};
+		return {
+			activeTools: skillsResult.activeTools ?? [],
+			system: skillsResult.system
 		};
-	}
-	return callSettings;
+	};
+	return {
+		...baseParams,
+		system: skillsCtx.getSystem() || rest.system,
+		tools: skillsCtx.tools,
+		activeTools: skillsCtx.activeTools,
+		prepareStep
+	};
 }
+//#endregion
+//#region src/features/audit/index.ts
 /**
-* Drop-in replacement for `streamText` from the AI SDK with added support for
-* lazy skill loading and message compaction.
+* Inserts a single audit event row into the shared `audit_events` D1 table.
 *
-* All standard AI SDK parameters are accepted and passed through unchanged.
+* Called by `AIChatAgent.log()`. Not intended for direct use.
+*/
+async function insertAuditEvent(db, agentName, durableObjectId, message, payload) {
+	await db.prepare(`INSERT INTO audit_events (id, agent_name, durable_object_id, message, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`).bind(crypto.randomUUID(), agentName, durableObjectId, message, payload ? JSON.stringify(payload) : null, (/* @__PURE__ */ new Date()).toISOString()).run();
+}
+/**
+* Builds the payload for a "turn completed" audit event from the final message list.
 *
-* @param params.skills - Skills available for on-demand loading this turn. Wires up
-*   `activate_skill`, `list_capabilities`, `activeTools`, and `prepareStep` automatically.
-* @param params.activeSkills - Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`.
-* @param params.compact - When provided, compacts messages before the model call. Older messages
-*   are summarised into a single system message using the given model.
+* Extracts the last user and assistant message texts (truncated to 200 chars),
+* all non-meta tool call names used this turn, and the current loaded skill set.
 */
-async function streamText(params) {
-	return streamText$1(await resolveCallSettings(params));
+function buildTurnSummary(messages, loadedSkills) {
+	const toolCallNames = [];
+	for (const msg of messages) {
+		if (msg.role !== "assistant" || !msg.parts) continue;
+		for (const part of msg.parts) {
+			if (!("toolCallId" in part)) continue;
+			const { type } = part;
+			if (!type.startsWith("tool-")) continue;
+			const name = type.slice(5);
+			if (name !== "activate_skill" && name !== "list_capabilities" && !toolCallNames.includes(name)) toolCallNames.push(name);
+		}
+	}
+	const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+	const lastAssistantMsg = [...messages].reverse().find((m) => m.role === "assistant");
+	return {
+		userMessage: extractMessageText(lastUserMsg).slice(0, 200),
+		toolCalls: toolCallNames,
+		loadedSkills,
+		assistantMessage: extractMessageText(lastAssistantMsg).slice(0, 200)
+	};
+}
+function extractMessageText(msg) {
+	if (!msg?.parts) return "";
+	return msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ").trim();
 }
+//#endregion
+//#region src/agents/AIChatAgent.ts
 /**
-* Drop-in replacement for `generateText` from the AI SDK with added support for
-* lazy skill loading and message compaction.
+* Base class for Cloudflare Agents SDK chat agents with lazy skill loading
+* and built-in audit logging.
 *
-* All standard AI SDK parameters are accepted and passed through unchanged.
+* Handles CF infrastructure concerns only: DO SQLite persistence for loaded
+* skill state, stripping skill meta-tool messages before persistence, history
+* replay to newly connected clients, and writing audit events to D1.
 *
-* @param params.skills - Skills available for on-demand loading this turn. Wires up
-*   `activate_skill`, `list_capabilities`, `activeTools`, and `prepareStep` automatically.
-* @param params.activeSkills - Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`.
-* @param params.compact - When provided, compacts messages before the model call. Older messages
-*   are summarised into a single system message using the given model.
+* Skill loading, compaction, and LLM communication are delegated to
+* `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
 */
-async function generateText(params) {
-	return generateText$1(await resolveCallSettings(params));
+var AIChatAgent = class extends AIChatAgent$1 {
+	/**
+	* Writes an audit event to D1 if `AUDIT_DB` is bound on the environment,
+	* otherwise silently does nothing.
+	*
+	* Called automatically after every turn (from `persistMessages`) and on
+	* non-clean finish reasons (from `buildLLMParams`). Also available via
+	* `experimental_context.log` in tool `execute` functions.
+	*/
+	async log(message, payload) {
+		const db = this.env.AUDIT_DB;
+		if (!db) return;
+		await insertAuditEvent(db, this.constructor.name, this.ctx.id.toString(), message, payload);
+	}
+	/**
+	* Builds the parameter object for a `streamText` or `generateText` call,
+	* pre-filling `messages` and `activeSkills` from this agent instance.
+	* Injects `log` into `experimental_context` and logs non-clean finish reasons.
+	*
+	* ```typescript
+	* const params = await this.buildLLMParams({ options, onFinish, model, system: "..." });
+	* return streamText(params).toUIMessageStreamResponse();
+	* ```
+	*/
+	async buildLLMParams(config) {
+		const onFinishWithErrorLogging = async (result) => {
+			if (result.finishReason !== "stop" && result.finishReason !== "tool-calls") await this.log("turn error", { finishReason: result.finishReason });
+			return config.onFinish?.(result);
+		};
+		return {
+			...await buildLLMParams({
+				...config,
+				onFinish: onFinishWithErrorLogging,
+				messages: this.messages,
+				activeSkills: await this.getLoadedSkills()
+			}),
+			experimental_context: {
+				...config.options?.body,
+				log: this.log.bind(this)
+			}
+		};
+	}
+	/**
+	* Skill names persisted from previous turns, read from DO SQLite.
+	* Returns an empty array if no skills have been loaded yet.
+	*/
+	async getLoadedSkills() {
+		try {
+			this.ensureSkillTableExists();
+			const rows = this.sql`SELECT active_skills FROM skill_state WHERE id = 1`;
+			if (rows.length === 0) return [];
+			return JSON.parse(rows[0].active_skills);
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Extracts skill state from activate_skill results, persists to DO SQLite,
+	* logs a turn summary, then strips all skill meta-tool messages before
+	* delegating to super.
+	*
+	* 1. Scans activate_skill tool results for SKILL_STATE_SENTINEL. When found,
+	*    the embedded JSON array of loaded skill names is written to DO SQLite.
+	*
+	* 2. Logs a turn summary via `log()`. Best-effort: fire-and-forget.
+	*
+	* 3. Strips all activate_skill and list_capabilities messages from history.
+	*
+	* 4. Delegates to super.persistMessages for message storage and WS broadcast.
+	*/
+	async persistMessages(messages, excludeBroadcastIds = [], options) {
+		let latestSkillState;
+		for (const msg of messages) {
+			if (msg.role !== "assistant" || !msg.parts) continue;
+			for (const part of msg.parts) {
+				if (!("toolCallId" in part)) continue;
+				const { type, output } = part;
+				if (type !== `tool-activate_skill` || typeof output !== "string") continue;
+				const sentinelIdx = output.indexOf(SKILL_STATE_SENTINEL);
+				if (sentinelIdx !== -1) try {
+					const stateJson = output.slice(sentinelIdx + 18);
+					latestSkillState = JSON.parse(stateJson);
+				} catch {}
+			}
+		}
+		if (latestSkillState !== void 0) {
+			this.ensureSkillTableExists();
+			this.sql`INSERT OR REPLACE INTO skill_state(id, active_skills) VALUES(1, ${JSON.stringify(latestSkillState)})`;
+		}
+		this.log("turn completed", buildTurnSummary(messages, latestSkillState ?? []));
+		const filtered = stripSkillMessages(messages);
+		return super.persistMessages(filtered, excludeBroadcastIds, options);
+	}
+	ensureSkillTableExists() {
+		this.sql`CREATE TABLE IF NOT EXISTS skill_state (id INTEGER PRIMARY KEY, active_skills TEXT NOT NULL DEFAULT '[]')`;
+	}
+};
+function stripSkillMessages(messages) {
+	return messages.flatMap((msg) => {
+		if (msg.role !== "assistant" || !msg.parts?.length) return [msg];
+		const filtered = msg.parts.filter((part) => {
+			if (!("toolCallId" in part)) return true;
+			const { type } = part;
+			return type !== `tool-activate_skill` && type !== `tool-list_capabilities`;
+		});
+		if (filtered.length === 0) return [];
+		if (filtered.length === msg.parts.length) return [msg];
+		return [{
+			...msg,
+			parts: filtered
+		}];
+	});
 }
 //#endregion
-export { AIChatAgent, generateText, streamText };
+export { AIChatAgent, buildLLMParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-alpha.11",
+  "version": "0.0.1-alpha.12",
   "description": "A starter for creating a TypeScript package.",
   "homepage": "https://github.com/author/library#readme",
   "bugs": {
@@ -13,7 +13,8 @@
     "url": "git+https://github.com/author/library.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "schema"
   ],
   "type": "module",
   "exports": {

package/schema/audit_events.sql

@@ -0,0 +1,15 @@
+-- Audit events table for @economic/agents.
+-- This is a shared global table — create it once in the Cloudflare D1 portal.
+-- Safe to re-run: all statements use IF NOT EXISTS.
+
+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,           -- JSON, nullable
+  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);