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

package/README.md

@@ -43,6 +43,9 @@ 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 params = await this.buildLLMParams({
       options,
@@ -111,10 +114,27 @@ Protected method on `AIChatAgent`. Wraps the standalone `buildLLMParams` functio
 
 - `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`.
 
-Config is everything accepted by the standalone `buildLLMParams` except `messages` and `activeSkills`.
+When `fastModel` is `undefined` (the default), compaction is disabled regardless of `maxMessagesBeforeCompaction`.
 
 ### `getLoadedSkills()`
 
@@ -152,7 +172,6 @@ const params = await buildLLMParams({
   system: "You are a helpful assistant.",
   skills: [searchSkill, codeSkill],
   tools: { myAlwaysOnTool },
-  compact: { model: openai("gpt-4o-mini"), maxMessages: 30 },
   stopWhen: stepCountIs(20), // defaults to stepCountIs(20)
 });
 
@@ -160,18 +179,18 @@ return streamText(params).toUIMessageStreamResponse();
 // or: generateText(params);
 ```
 
-| 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)`.                                 |
+| 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`:
 
@@ -244,27 +263,62 @@ export const datetimeSkill: Skill = {
 
 ## Compaction
 
-When `compact` is provided to `buildLLMParams`, it 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 params = await this.buildLLMParams({
   options,
   onFinish,
   model: openai("gpt-4o"),
-  system: "...",
-  compact: {
-    model: openai("gpt-4o-mini"), // cheaper model for summarisation
-    maxMessages: 30, // keep last 30 messages verbatim
-  },
+  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 streamText(params).toUIMessageStreamResponse();
 ```
 
+Compaction is always off when `fastModel` is `undefined` (the base class default).
+
 ---
 
 ## Built-in meta tools
@@ -317,13 +371,13 @@ execute: async (args, { experimental_context }) => {
 };
 ```
 
-`log` is a no-op when `AUDIT_DB` is not bound — so no changes are needed in tools when running without a D1 database.
+`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 `AUDIT_DB` is bound on the environment. The table is shared across all agent workers — create it once.
+`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
 
@@ -336,14 +390,15 @@ Open the database in the D1 dashboard, select **Console**, and run the contents
 ```sql
 CREATE TABLE IF NOT EXISTS audit_events (
   id                TEXT PRIMARY KEY,
-  agent_name        TEXT NOT NULL,
   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_do ON audit_events(durable_object_id);
-CREATE INDEX IF NOT EXISTS audit_events_ts ON audit_events(created_at);
+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`.
@@ -352,7 +407,7 @@ Safe to re-run — all statements use `IF NOT EXISTS`.
 
 ```jsonc
 "d1_databases": [
-  { "binding": "AUDIT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
+  { "binding": "AGENT_DB", "database_name": "agents", "database_id": "YOUR_DB_ID" }
 ]
 ```
 
@@ -366,7 +421,81 @@ 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.
+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
+  },
+});
+```
+
+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.
+
+---
+
+## Conversations — D1 setup
+
+`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.
+
+### Schema
+
+Run the contents of [`schema/conversations.sql`](schema/conversations.sql) in the D1 dashboard console (same database as `audit_events`):
+
+```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.
 
 ---
 
@@ -389,7 +518,6 @@ If `AUDIT_DB` is not bound, all `log()` calls are silent no-ops — the agent wo
 | 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.                       |
 

package/dist/index.d.mts

@@ -22,20 +22,32 @@ interface Skill {
   tools: ToolSet;
 }
 //#endregion
-//#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;
-};
-//#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;
+  skills?: Skill[];
+  /**
+   * Number of recent messages to keep verbatim during compaction. Older messages
+   * beyond this count are summarised by `fastModel` before being sent to the LLM.
+   *
+   * Defaults to `DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION` (30) when not provided.
+   * Set explicitly to `undefined` to disable compaction entirely.
+   *
+   * Compaction only runs when `fastModel` is also set on the agent class.
+   *
+   * @internal Injected by `AIChatAgent.buildLLMParams` — do not set this directly.
+   */
+  maxMessagesBeforeCompaction?: number;
+  /**
+   * The fast/cheap model used for compaction and background summarization.
+   * Provided automatically from `AIChatAgent.fastModel` — do not set this directly.
+   *
+   * @internal
+   */
+  fastModel?: LanguageModel;
 };
 /**
  * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
@@ -67,7 +79,32 @@ declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams
  */
 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,
+   * Composed user identifier extracted from `options.body.userId` during
+   * `buildLLMParams`. Expected format: `{agreementNumber}_{userId}`, e.g. `148583_matt`.
+   * Undefined if the client did not include `userId` in the request body.
+   */
+  protected _userId: string | undefined;
+  /**
+   * Fast/cheap language model used for background tasks: compaction and conversation summarization.
+   *
+   * Declare this on every subclass:
+   *
+   * ```typescript
+   * protected fastModel = google("gemini-2.0-flash");
+   * ```
+   *
+   * To disable compaction for a specific call, pass `maxMessagesBeforeCompaction: undefined`
+   * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
+   */
+  protected abstract fastModel: LanguageModel;
+  /**
+   * Resolves the D1 database binding and userId required for all D1 writes.
+   * Returns null and silently no-ops if AGENT_DB is not bound.
+   * Returns null and logs an error if userId is missing from the request body.
+   */
+  private resolveD1Context;
+  /**
+   * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
    * otherwise silently does nothing.
    *
    * Called automatically after every turn (from `persistMessages`) and on
@@ -75,17 +112,53 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    * `experimental_context.log` in tool `execute` functions.
    */
   protected log(message: string, payload?: Record<string, unknown>): Promise<void>;
+  /**
+   * Records this conversation in the `conversations` D1 table and resets
+   * the idle summarization timer. Called automatically from `persistMessages`
+   * after every turn.
+   *
+   * After each upsert, any pending `generateSummary` schedule is cancelled
+   * and a new one is set for 30 minutes from now. If the user sends another
+   * message before the timer fires, the schedule is cancelled and reset again
+   * (debounce). When the conversation goes idle, `generateSummary` fires and
+   * writes the LLM-generated title and summary to D1.
+   */
+  private recordConversation;
+  /**
+   * Generates a title and summary for the conversation after 30 minutes of
+   * inactivity. Invoked automatically by the Cloudflare Agents SDK scheduler
+   * — do not call this directly.
+   *
+   * Delegates to `generateConversationSummary` in `features/conversations`,
+   * which fetches the previous summary, slices to the last
+   * `SUMMARY_CONTEXT_MESSAGES` messages, calls `fastModel` with a structured
+   * output schema, and writes the result back to D1.
+   */
+  generateSummary(): Promise<void>;
   /**
    * Builds the parameter object for a `streamText` or `generateText` call,
-   * pre-filling `messages` and `activeSkills` from this agent instance.
+   * pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
    * Injects `log` into `experimental_context` and logs non-clean finish reasons.
    *
+   * **Compaction** runs automatically when `fastModel` is set on the class, using
+   * `DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION` (30) as the threshold. Override the
+   * threshold by passing `maxMessagesBeforeCompaction`. Disable compaction entirely
+   * by passing `maxMessagesBeforeCompaction: undefined` explicitly.
+   *
    * ```typescript
+   * // Compaction on (default threshold):
    * const params = await this.buildLLMParams({ options, onFinish, model, system: "..." });
+   *
+   * // Compaction with custom threshold:
+   * const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: 50 });
+   *
+   * // Compaction off:
+   * const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: undefined });
+   *
    * return streamText(params).toUIMessageStreamResponse();
    * ```
    */
-  protected buildLLMParams(config: Omit<BuildLLMParamsConfig, "messages" | "activeSkills">): ReturnType<typeof buildLLMParams>;
+  protected buildLLMParams(config: Omit<BuildLLMParamsConfig, "messages" | "activeSkills" | "fastModel">): ReturnType<typeof buildLLMParams>;
   /**
    * Skill names persisted from previous turns, read from DO SQLite.
    * Returns an empty array if no skills have been loaded yet.
@@ -108,9 +181,16 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
   persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
     _deleteStaleRows?: boolean;
   }): Promise<void>;
-  private ensureSkillTableExists;
 }
 //#endregion
+//#region src/features/compaction/index.d.ts
+/**
+ * Number of recent messages to keep verbatim when compaction runs.
+ * Older messages beyond this count are summarised into a single system message.
+ * Used as the default when `maxMessagesBeforeCompaction` is not provided to `buildLLMParams`.
+ */
+declare const DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION = 30;
+//#endregion
 //#region src/types.d.ts
 /**
  * The context object available throughout an agent's lifetime — passed via
@@ -127,4 +207,4 @@ type AgentContext<TBody = Record<string, unknown>> = TBody & {
   log: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
 };
 //#endregion
-export { AIChatAgent, type AgentContext, type BuildLLMParamsConfig, type CompactOptions, type Skill, buildLLMParams };
+export { AIChatAgent, type AgentContext, type BuildLLMParamsConfig, DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION, type Skill, buildLLMParams };