@economic/agents 0.0.1-alpha.10

package/README.md

@@ -0,0 +1,87 @@
+# @economic/agents
+
+Base classes and utilities for building LLM agents on Cloudflare's Agents SDK with lazy tool loading.
+
+## Exports
+
+- **`AIChatAgent`** — base class that owns the full `onChatMessage` lifecycle. Implement `getModel()`, `getTools()`, `getSkills()`, and `getSystemPrompt()`. Compaction is **enabled by default** (uses `getModel()` for summarisation).
+- **`AIChatAgentBase`** — base class for when you need full control over `streamText`. Implement `getTools()`, `getSkills()`, and your own `onChatMessage` decorated with `@withSkills`. Compaction is **disabled by default**.
+- **`withSkills`** — method decorator used with `AIChatAgentBase`.
+- **`createSkills`** — lower-level factory for wiring lazy skill loading into any agent subclass yourself.
+- **`filterEphemeralMessages`**, **`injectGuidance`** — utilities used internally, exported for custom wiring.
+- **`compactIfNeeded`**, **`compactMessages`**, **`estimateMessagesTokens`**, **`COMPACT_TOKEN_THRESHOLD`** — compaction utilities, exported for use with `AIChatAgentBase` or fully custom agents.
+- Types: `Tool`, `Skill`, `SkillsConfig`, `SkillsResult`, `SkillContext`.
+
+See [COMPARISON.md](./COMPARISON.md) for a side-by-side code example of both base classes.
+
+See [src/features/skills/README.md](./src/features/skills/README.md) for full `createSkills` documentation.
+
+## Development
+
+```bash
+vp install   # install dependencies
+vp test      # run tests
+vp pack      # build
+```
+
+---
+
+## Implementing your own agent
+
+Extend `AIChatAgent` and implement the four required methods:
+
+```typescript
+import { AIChatAgent } from "@economic/agents";
+
+export class MyAgent extends AIChatAgent {
+  getModel() {
+    return openai("gpt-4o");
+  }
+  getTools() {
+    return [myAlwaysOnTool];
+  }
+  getSkills() {
+    return [searchSkill, codeSkill];
+  }
+  getSystemPrompt() {
+    return "You are a helpful assistant.";
+  }
+
+  // Return the D1 binding — typed in Cloudflare.Env after `wrangler types`
+  protected getDB() {
+    return this.env.AGENT_DB;
+  }
+}
+```
+
+If you need control over the response — custom model options, middleware, varying the model per request — use `AIChatAgentBase` with the `@withSkills` decorator instead. See [COMPARISON.md](./COMPARISON.md) for a side-by-side example and `src/features/skills/README.md` for full `createSkills` documentation.
+
+### Message compaction
+
+`AIChatAgent` automatically compacts the conversation history when it approaches the token limit (140k tokens). Older messages are summarised by the LLM into a single system message; the most recent messages are kept verbatim. The verbatim tail size is `maxPersistedMessages - 1` (default: 49 messages + 1 summary message).
+
+The compaction model defaults to `getModel()`. To use a cheaper model for summarisation, override `getCompactionModel()`:
+
+```typescript
+protected override getCompactionModel(): LanguageModel {
+  return openai("gpt-4o-mini"); // cheaper model for summarisation
+}
+```
+
+To disable compaction entirely, override `getCompactionModel()` to return `undefined`:
+
+```typescript
+protected override getCompactionModel(): LanguageModel | undefined {
+  return undefined; // no compaction — older messages are dropped at maxPersistedMessages
+}
+```
+
+`AIChatAgentBase` does not enable compaction by default. To add it, override `getCompactionModel()` to return a model — the `persistMessages` override will pick it up automatically:
+
+```typescript
+protected override getCompactionModel(): LanguageModel {
+  return openai("gpt-4o-mini");
+}
+```
+
+Alternatively, import `compactIfNeeded` and `COMPACT_TOKEN_THRESHOLD` from `@economic/agents` and call them yourself inside a custom `persistMessages` override for full control over the compaction logic.

package/dist/index.d.mts

@@ -0,0 +1,567 @@
+import * as ai from "ai";
+import { LanguageModel, ModelMessage, PrepareStepFunction, StreamTextOnFinishCallback, ToolSet, UIMessage } from "ai";
+import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/ai-chat";
+
+//#region ../../node_modules/partyserver/dist/index.d.ts
+//#region src/types.d.ts
+type ImmutablePrimitive = undefined | null | boolean | string | number;
+type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
+type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
+type ConnectionState<T> = ImmutableObject<T> | null;
+type ConnectionSetStateFn<T> = (prevState: ConnectionState<T>) => T;
+type ConnectionContext = {
+  request: Request;
+};
+/** A WebSocket connected to the Server */
+type Connection<TState = unknown> = WebSocket & {
+  /** Connection identifier */id: string;
+  /**
+   * Arbitrary state associated with this connection.
+   * Read-only — use {@link Connection.setState} to update.
+   *
+   * This property is configurable, meaning it can be redefined via
+   * `Object.defineProperty` by downstream consumers (e.g. the Cloudflare
+   * Agents SDK) to namespace or wrap internal state storage.
+   */
+  state: ConnectionState<TState>;
+  /**
+   * Update the state associated with this connection.
+   *
+   * Accepts either a new state value or an updater function that receives
+   * the previous state and returns the next state.
+   *
+   * This property is configurable, meaning it can be redefined via
+   * `Object.defineProperty` by downstream consumers. If you redefine
+   * `state` and `setState`, you are responsible for calling
+   * `serializeAttachment` / `deserializeAttachment` yourself if you need
+   * the state to survive hibernation.
+   */
+  setState(state: TState | ConnectionSetStateFn<TState> | null): ConnectionState<TState>;
+  /**
+   * @deprecated use {@link Connection.setState} instead.
+   *
+   * Low-level method to persist data in the connection's attachment storage.
+   * This property is configurable and can be redefined by downstream
+   * consumers that need to wrap or namespace the underlying storage.
+   */
+  serializeAttachment<T = unknown>(attachment: T): void;
+  /**
+   * @deprecated use {@link Connection.state} instead.
+   *
+   * Low-level method to read data from the connection's attachment storage.
+   * This property is configurable and can be redefined by downstream
+   * consumers that need to wrap or namespace the underlying storage.
+   */
+  deserializeAttachment<T = unknown>(): T | null;
+  /**
+   * Tags assigned to this connection via {@link Server.getConnectionTags}.
+   * Always includes the connection id as the first tag.
+   */
+  tags: readonly string[];
+  /**
+   * @deprecated Use `this.name` on the Server instead.
+   * The server name. Populated from `Server.name` after initialization.
+   */
+  server: string;
+}; //#endregion
+//#region src/index.d.ts
+//#endregion
+//#region ../../node_modules/zod/v4/core/schemas.d.cts
+declare global {
+  interface File {}
+}
+//#endregion
+//#region src/features/skills/types.d.ts
+/**
+ * A named group of related tools that can be loaded together on demand.
+ *
+ * The agent starts with only its always-on tools active. When the LLM calls
+ * activate_skill with a skill name, that skill's tools become available for
+ * the rest of the conversation.
+ *
+ * Define tools using the AI SDK's `tool()` helper — Zod schemas are supported
+ * natively via the `parameters` field.
+ */
+interface Skill {
+  name: string;
+  /** One-line description shown in the activate_skill tool schema */
+  description: string;
+  /**
+   * Guidance text for this skill — e.g. rate limits, preferred patterns,
+   * when to use each tool. Injected as a system message each turn for any
+   * skill that is loaded, keeping the `system` prompt static and cacheable.
+   */
+  guidance?: string;
+  tools: ToolSet;
+}
+/**
+ * Configuration passed to createSkills().
+ */
+interface SkillsConfig {
+  /** Tools that are always active regardless of loaded skills */
+  tools: ToolSet;
+  /** All available skills that can be loaded on demand */
+  skills: Skill[];
+  /**
+   * The base system prompt for the agent. When provided, createSkills uses
+   * this to compose the full system string (base + guidance) returned by
+   * getSystem() and from prepareStep. Guidance is kept in the system
+   * parameter rather than the messages array — Anthropic/Gemini only allow
+   * system messages at the start of the conversation.
+   */
+  systemPrompt?: string;
+  /**
+   * Skill names that were loaded in previous turns, read from D1 at turn
+   * start. Seeds the in-memory loadedSkills set so prior state is restored
+   * before the first LLM step.
+   */
+  initialLoadedSkills?: string[];
+  /**
+   * Called after activate_skill successfully loads new skills.
+   * Receives the complete current set of loaded skill names. The agent
+   * buffers this value and writes it to D1 at turn end (in persistMessages),
+   * keeping the write co-located with message persistence — aligned with
+   * how slack-bot saves loaded_categories alongside messages.
+   */
+  onSkillsChanged?: (skills: string[]) => Promise<void>;
+  /**
+   * Optional permission hook. Return false to deny access to a skill.
+   * Defaults to allow-all if not provided.
+   */
+  filterSkill?: (skillName: string) => Promise<boolean> | boolean;
+}
+/**
+ * Skill context injected by the @withSkills decorator.
+ *
+ * Spread the skill fields into streamText:
+ *
+ * ```typescript
+ * const { messages, guidance, ...skillArgs } = ctx;
+ * return streamText({
+ *   model: this.getModel(),
+ *   system: "Your base prompt — static, never includes guidance",
+ *   messages,
+ *   ...skillArgs,
+ *   onFinish,
+ *   stopWhen: stepCountIs(20),
+ * }).toUIMessageStreamResponse();
+ * ```
+ */
+interface SkillContext {
+  /** All registered tools — spread into streamText */
+  tools: ai.ToolSet;
+  /** Currently active tool names — spread into streamText */
+  activeTools: string[];
+  /**
+   * Updates activeTools before each LLM step. Spread into streamText.
+   */
+  prepareStep: ai.PrepareStepFunction;
+  /**
+   * Guidance text from all currently-loaded skills. Compose your system
+   * prompt as: `${myBase}${guidance ? '\n\n' + guidance : ''}`
+   */
+  guidance: string;
+  /**
+   * Plain conversation history from DO SQLite — no guidance injected.
+   * Pass directly as the `messages` param of streamText.
+   */
+  messages: ai.ModelMessage[];
+}
+/**
+ * The object returned by createSkills().
+ * Spread the SDK-specific fields into your streamText call.
+ */
+interface SkillsResult {
+  /** Guidance text for all currently-loaded skills */
+  getLoadedGuidance(): string;
+  /** Current loaded skill names */
+  getLoadedSkills(): string[];
+  /**
+   * Full system string: base system prompt concatenated with guidance from
+   * all currently-loaded skills. Only meaningful when `systemPrompt` was
+   * passed to createSkills. Use as the `system` param of streamText.
+   */
+  getSystem(): string;
+}
+//#endregion
+//#region src/agents/chat/AIChatAgentBase.d.ts
+/**
+ * Base class for chat agents with lazy skill loading.
+ *
+ * Owns:
+ * - D1 persistence for loaded skill state (skill names survive DO eviction)
+ * - Ephemeral message filtering (list_capabilities, no-op activate_skill calls)
+ * - Message compaction (LLM summarisation when history exceeds token threshold)
+ * - History replay to newly connected clients (onConnect override)
+ * - Skill context preparation for use with the @withSkills decorator
+ *
+ * Conversation messages are stored in Durable Object SQLite, managed
+ * automatically by the Cloudflare AIChatAgent — no D1 write needed for messages.
+ *
+ * D1 is written only when skills change (activate_skill was called this turn),
+ * not on every turn.
+ *
+ * ## Usage
+ *
+ * Extend this class when you want full control over `streamText`. Implement
+ * `getTools()`, `getSkills()`, and your own `onChatMessage` decorated with
+ * `@withSkills`:
+ *
+ * ```typescript
+ * export class MyAgent extends AIChatAgentBase {
+ *   getTools()  { return []; }
+ *   getSkills() { return [searchSkill, codeSkill]; }
+ *   getDB()     { return this.env.AGENT_DB; }
+ *
+ *   @withSkills
+ *   async onChatMessage(onFinish, ctx: SkillContext, options?) {
+ *     const { messages, ...skillArgs } = ctx;
+ *     return streamText({
+ *       model: openai("gpt-4o"),
+ *       system: "You are a helpful assistant.",
+ *       messages,
+ *       ...skillArgs,
+ *       onFinish,
+ *       stopWhen: stepCountIs(20),
+ *     }).toUIMessageStreamResponse();
+ *   }
+ * }
+ * ```
+ *
+ * For a batteries-included experience where the base class owns `onChatMessage`,
+ * extend `AIChatAgent` instead.
+ */
+declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent$1<Env> {
+  /**
+   * Maximum number of messages stored in DO SQLite.
+   *
+   * Lowered from the Cloudflare AIChatAgent default of 200. When compaction
+   * is enabled, one slot is reserved for the summary message so the verbatim
+   * tail is maxPersistedMessages - 1 recent messages. Raise or lower per agent.
+   */
+  maxPersistedMessages: number;
+  /** Tools that are always active regardless of loaded skills */
+  abstract getTools(): ToolSet;
+  /** All skills available for on-demand loading */
+  abstract getSkills(): Skill[];
+  /**
+   * Return a LanguageModel to use for compaction summarisation.
+   *
+   * Return undefined (default) to disable compaction — messages are kept up
+   * to maxPersistedMessages and older ones are dropped by the Cloudflare
+   * AIChatAgent's built-in hard cap.
+   *
+   * Override to use a cheaper or faster model for summarisation, or to enable
+   * compaction in subclasses that do not override it automatically.
+   */
+  protected getCompactionModel(): LanguageModel | undefined;
+  /**
+   * Return the D1 database binding for persisting loaded skill state.
+   *
+   * Override in your subclass to return the binding from env:
+   * ```typescript
+   * protected getDB() { return this.env.AGENT_DB; }
+   * ```
+   *
+   * Defaults to undefined — when undefined, loaded skills reset on every new
+   * conversation (skills still work within a turn, just not across turns).
+   */
+  protected getDB(): D1Database | undefined;
+  /**
+   * Optional permission hook. Return false to deny the agent access to a
+   * skill when activate_skill is called. Defaults to allow-all.
+   */
+  protected filterSkill(_skillName: string): Promise<boolean>;
+  /**
+   * Buffered skill state from the current turn.
+   *
+   * Set by the onSkillsChanged callback when activate_skill loads new skills
+   * mid-turn. Flushed to D1 in persistMessages at turn end — only written
+   * when this value is set, so D1 is not touched on turns where no new skills
+   * are loaded.
+   */
+  protected _pendingSkills: string[] | undefined;
+  /**
+   * Reads loaded skill names from D1 for this agent.
+   *
+   * Returns an empty array if no record exists (first turn, or no skills
+   * loaded yet). Conversation messages are not read here — the Cloudflare
+   * AIChatAgent provides those via this.messages from DO SQLite.
+   */
+  protected _readSkillState(): Promise<string[]>;
+  /**
+   * Writes loaded skill names to D1 for this agent.
+   *
+   * Uses INSERT OR REPLACE so the first skill load creates the row and
+   * subsequent loads update it. Only called when skills actually changed
+   * this turn (_pendingSkills is set).
+   */
+  protected _writeSkillState(skills: string[]): Promise<void>;
+  /**
+   * Flush persisted message history to a newly connected client.
+   *
+   * The Cloudflare AIChatAgent broadcasts message updates to existing
+   * connections via persistMessages, but does nothing for connections that
+   * arrive after a conversation has ended. Without this override, a page
+   * refresh produces an empty UI even though the history is intact in DO SQLite.
+   *
+   * Skips replay when a stream is active — CF_AGENT_STREAM_RESUMING handles
+   * that case and replays in-progress chunks via its own protocol.
+   */
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  /**
+   * Strips ephemeral content, conditionally saves skill state to D1, then
+   * delegates to super for DO SQLite persistence and WebSocket broadcast.
+   *
+   * The Cloudflare AIChatAgent calls persistMessages once per turn after all
+   * steps complete, so overriding here is the correct place to act — it runs
+   * after the full assistant message (including all tool results) is assembled.
+   *
+   * Two things happen here:
+   *
+   * 1. Ephemeral tool calls are stripped — list_capabilities (always) and
+   *    activate_skill when nothing was newly loaded (no state change).
+   *
+   * 2. If skills changed this turn (_pendingSkills is set), the updated list
+   *    is written to D1. Turns where no skills were loaded do not touch D1.
+   *
+   * Message persistence itself is handled by super.persistMessages, which
+   * writes to DO SQLite — no D1 write needed for messages.
+   */
+  persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
+    _deleteStaleRows?: boolean;
+  }): Promise<void>;
+  /**
+   * Widened onChatMessage signature that accommodates the @withSkills decorator.
+   *
+   * The decorator transforms the consumer's 3-arg form (onFinish, ctx, options) into
+   * a 2-arg wrapper at runtime. This declaration widens the base class signature so
+   * that TypeScript accepts the consumer's 3-arg override without errors.
+   *
+   * @ts-ignore — intentional: widens the Cloudflare AIChatAgent's (onFinish, options?) signature.
+   */
+  onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, ctxOrOptions?: SkillContext | OnChatMessageOptions): Promise<Response | undefined>;
+  /**
+   * Called by the @withSkills decorator at the start of each turn.
+   *
+   * Reads loaded skill state from D1, seeds createSkills, and returns a
+   * SkillContext ready to use in a streamText call.
+   *
+   * Guidance is exposed as `ctx.guidance` — compose your system prompt as:
+   * `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
+   *
+   * Messages are plain (no guidance injected). Guidance stays out of the
+   * messages array — Anthropic/Gemini only allow system messages at position 0.
+   */
+  protected _prepareSkillContext(): Promise<SkillContext>;
+}
+/**
+ * Method decorator for use with AIChatAgentBase.
+ *
+ * Apply to `onChatMessage` to receive a pre-built SkillContext as the second
+ * argument. The decorator reads loaded skill state from D1, seeds createSkills,
+ * and injects guidance into the conversation history from DO SQLite. Skill state
+ * changes are buffered for D1 write at turn end (only when skills actually change).
+ * Ephemeral cleanup is handled automatically via the persistMessages override —
+ * no wiring needed.
+ *
+ * ```typescript
+ * @withSkills
+ * async onChatMessage(
+ *   onFinish: StreamTextOnFinishCallback<ToolSet>,
+ *   ctx: SkillContext,
+ *   options?: OnChatMessageOptions,
+ * ) {
+ *   const { messages, guidance, ...skillArgs } = ctx;
+ *   const base = "Your base prompt";
+ *   return streamText({
+ *     model: this.getModel(),
+ *     system: guidance ? `${base}\n\n${guidance}` : base,
+ *     messages,
+ *     ...skillArgs,
+ *     onFinish,
+ *     stopWhen: stepCountIs(20),
+ *   }).toUIMessageStreamResponse();
+ * }
+ * ```
+ */
+type WithSkillsFn = (this: AIChatAgentBase, onFinish: StreamTextOnFinishCallback<ToolSet>, ctx: SkillContext, options?: OnChatMessageOptions) => Promise<Response | undefined>;
+declare function withSkills(fn: WithSkillsFn, _context: ClassMethodDecoratorContext): WithSkillsFn;
+//#endregion
+//#region src/agents/chat/AIChatAgent.d.ts
+/**
+ * Batteries-included base class for chat agents with lazy skill loading.
+ *
+ * Owns the full `onChatMessage` lifecycle. Implement four abstract methods and
+ * get lazy skill loading, cross-turn skill persistence, guidance injection,
+ * ephemeral message cleanup, and message compaction for free.
+ *
+ * Conversation messages are stored in Durable Object SQLite by the Cloudflare
+ * AIChatAgent automatically — available as this.messages at the start of each
+ * turn. Loaded skill state is stored in D1 (via getDB()) and read at turn start.
+ * Guidance is injected as a system message just before the current user turn,
+ * keeping the `system` param static and cacheable across all turns.
+ *
+ * ```typescript
+ * export class MyAgent extends AIChatAgent {
+ *   getModel()        { return openai("gpt-4o"); }
+ *   getTools()        { return tools; }
+ *   getSkills()       { return [searchSkill, codeSkill]; }
+ *   getSystemPrompt() { return "You are a helpful assistant."; }
+ *   getDB()           { return this.env.AGENT_DB; }
+ * }
+ * ```
+ *
+ * If you need full control over the `streamText` call (custom model options,
+ * streaming transforms, varying the model per request, etc.) use
+ * `AIChatAgentBase` with the `@withSkills` decorator instead.
+ */
+declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgentBase<Env> {
+  /** Return the Vercel AI SDK LanguageModel to use for this agent */
+  abstract getModel(): LanguageModel;
+  /** Tools that are always active regardless of loaded skills */
+  abstract getTools(): ToolSet;
+  /** All skills available for on-demand loading */
+  abstract getSkills(): Skill[];
+  /**
+   * Build the base system prompt. This string is passed to streamText as-is
+   * and never modified — skill guidance is injected as a separate system
+   * message so this value stays static and cacheable.
+   */
+  abstract getSystemPrompt(): string;
+  /**
+   * Return the model used for compaction summarisation.
+   *
+   * Defaults to getModel() — the agent's primary model — so compaction is
+   * enabled automatically. Override to substitute a cheaper or faster model
+   * for summarisation (e.g. a smaller model when the primary is expensive).
+   *
+   * To opt out of message compaction: override and return undefined.
+   */
+  protected getCompactionModel(): LanguageModel;
+  onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response | undefined>;
+}
+//#endregion
+//#region src/features/skills/index.d.ts
+/**
+ * Creates a skill loading system for use with the Vercel AI SDK.
+ *
+ * The agent starts with only its always-on tools active. The LLM can call
+ * activate_skill to load skill tools on demand. Which skills are loaded is
+ * persisted to D1 across turns — no message-history parsing required.
+ *
+ * Guidance from loaded skills is injected as a system message just before
+ * the current user turn, keeping the `system` prompt static and cacheable.
+ * prepareStep keeps the guidance message updated if new skills load mid-turn.
+ *
+ * Usage with streamText (ai v6):
+ * ```typescript
+ * import { streamText, convertToModelMessages, stepCountIs } from "ai";
+ *
+ * // initialLoadedSkills comes from D1 (read at turn start by the agent).
+ * // onSkillsChanged is called when new skills are loaded; the agent
+ * // buffers the value and writes it to D1 at turn end in persistMessages.
+ * const lt = createSkills({ tools, skills, initialLoadedSkills, onSkillsChanged });
+ * const messages = injectGuidance(modelMessages, lt.getLoadedGuidance());
+ *
+ * const result = streamText({
+ *   model,
+ *   system: baseSystemPrompt, // static — never contains guidance, stays cacheable
+ *   messages,
+ *   tools: lt.tools,
+ *   activeTools: lt.activeTools,
+ *   prepareStep: lt.prepareStep, // keeps guidance message updated mid-turn
+ *   stopWhen: stepCountIs(20),
+ * });
+ * ```
+ */
+declare function createSkills(config: SkillsConfig): SkillsResult & {
+  tools: ToolSet;
+  activeTools: string[];
+  prepareStep: PrepareStepFunction;
+};
+/**
+ * Removes ephemeral messages from the conversation before it is saved to D1.
+ *
+ * Three kinds of messages are stripped:
+ *
+ * 1. list_capabilities tool calls — always stripped. Capability discovery is
+ *    only relevant within the current turn; it adds no useful context for
+ *    future turns.
+ *
+ * 2. activate_skill calls when nothing was newly loaded — stripped when all
+ *    requested skills were already active, or when all were denied. In both
+ *    cases nothing changed, so persisting the call would only add noise.
+ *
+ * 3. Guidance system messages — stripped by exact content match against the
+ *    provided guidance string. Guidance is always recomputed from loaded skill
+ *    definitions at turn start, so persisting it would create a redundant
+ *    second source of truth alongside the loaded_skills D1 column.
+ *
+ * When skills ARE successfully loaded, the short "Loaded: X" result is kept
+ * in history for model context — so the model can see what was loaded in
+ * prior turns. Skill state is restored from D1 loaded_skills, not from these
+ * strings.
+ *
+ * If stripping leaves an assistant message with no parts, the entire message
+ * is dropped (e.g. a step that did nothing but call list_capabilities).
+ */
+declare function filterEphemeralMessages(messages: UIMessage[], guidanceToStrip?: string): UIMessage[];
+/**
+ * Injects loaded skill guidance as a system message just before the last
+ * message in the array (typically the current user turn).
+ *
+ * Guidance is kept separate from the static `system` prompt so that the
+ * system prompt stays identical on every turn and can be prompt-cached.
+ * Positioning just before the last message means guidance survives any
+ * compaction strategy that preserves recent context.
+ *
+ * Pass `previousGuidance` (the string injected on the prior call) to remove
+ * the stale guidance message before inserting the updated one. Removal is by
+ * exact content match — not by role — so other system messages (memories,
+ * user preferences, etc.) are left untouched.
+ *
+ * At turn start, omit `previousGuidance` — guidance is never persisted to D1
+ * (it is stripped by filterEphemeralMessages before saving), so there is
+ * nothing to remove. prepareStep uses previousGuidance within a turn to
+ * handle guidance updates when new skills are loaded mid-turn.
+ *
+ * ```typescript
+ * // Turn start — just inject
+ * const messages = injectGuidance(modelMessages, skills.getLoadedGuidance());
+ *
+ * // prepareStep — remove stale guidance then re-inject updated guidance
+ * const messages = injectGuidance(stepMessages, newGuidance, previousGuidance);
+ * ```
+ */
+declare function injectGuidance(messages: ModelMessage[], guidance: string, previousGuidance?: string): ModelMessage[];
+//#endregion
+//#region src/agents/chat/compaction/index.d.ts
+declare const COMPACT_TOKEN_THRESHOLD = 140000;
+/**
+ * Estimates token count for a message array using a 3.5 chars/token
+ * approximation — the same heuristic used by slack-bot. Counts text from
+ * text parts, tool inputs/outputs, and reasoning parts.
+ */
+declare function estimateMessagesTokens(messages: UIMessage[]): number;
+/**
+ * Summarizes older messages into a single system message and appends the
+ * recent verbatim tail. Returns messages unchanged if the history is already
+ * short enough to fit within tailSize.
+ */
+declare function compactMessages(messages: UIMessage[], model: LanguageModel, tailSize: number): Promise<UIMessage[]>;
+/**
+ * Entry point called from persistMessages once per turn.
+ *
+ * Returns messages unchanged when:
+ * - model is undefined (compaction disabled on this agent)
+ * - estimated token count is under COMPACT_TOKEN_THRESHOLD
+ *
+ * Otherwise delegates to compactMessages.
+ */
+declare function compactIfNeeded(messages: UIMessage[], model: LanguageModel | undefined, tailSize: number): Promise<UIMessage[]>;
+//#endregion
+export { AIChatAgent, AIChatAgentBase, COMPACT_TOKEN_THRESHOLD, type Skill, type SkillContext, type SkillsConfig, type SkillsResult, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };

package/dist/index.mjs

@@ -0,0 +1,676 @@
+import { convertToModelMessages, generateText, jsonSchema, stepCountIs, streamText, tool } from "ai";
+import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
+//#region src/features/skills/meta-tools.ts
+/**
+* Names and descriptions for the built-in meta tools.
+*
+* The execute logic for these lives in createSkills() where it has
+* access to the closure state (loadedSkills).
+*/
+const ACTIVATE_SKILL = "activate_skill";
+const LIST_CAPABILITIES = "list_capabilities";
+/**
+* Builds the tool description for activate_skill, including the
+* current list of available skills with their descriptions.
+*/
+function buildActivateSkillDescription(skills) {
+	return [
+		"Load additional skills to help with the user's request.",
+		"Call this BEFORE attempting actions that need tools from unloaded skills.",
+		"",
+		"Available skills:",
+		skills.map((s) => `• ${s.name} — ${s.description}`).join("\n")
+	].join("\n");
+}
+const LIST_CAPABILITIES_DESCRIPTION = "List all tools currently available to you, which skills are loaded, and which can still be loaded. Call this when the user asks about your capabilities or what you can do.";
+//#endregion
+//#region src/features/skills/index.ts
+/**
+* Creates a skill loading system for use with the Vercel AI SDK.
+*
+* The agent starts with only its always-on tools active. The LLM can call
+* activate_skill to load skill tools on demand. Which skills are loaded is
+* persisted to D1 across turns — no message-history parsing required.
+*
+* Guidance from loaded skills is injected as a system message just before
+* the current user turn, keeping the `system` prompt static and cacheable.
+* prepareStep keeps the guidance message updated if new skills load mid-turn.
+*
+* Usage with streamText (ai v6):
+* ```typescript
+* import { streamText, convertToModelMessages, stepCountIs } from "ai";
+*
+* // initialLoadedSkills comes from D1 (read at turn start by the agent).
+* // onSkillsChanged is called when new skills are loaded; the agent
+* // buffers the value and writes it to D1 at turn end in persistMessages.
+* const lt = createSkills({ tools, skills, initialLoadedSkills, onSkillsChanged });
+* const messages = injectGuidance(modelMessages, lt.getLoadedGuidance());
+*
+* const result = streamText({
+*   model,
+*   system: baseSystemPrompt, // static — never contains guidance, stays cacheable
+*   messages,
+*   tools: lt.tools,
+*   activeTools: lt.activeTools,
+*   prepareStep: lt.prepareStep, // keeps guidance message updated mid-turn
+*   stopWhen: stepCountIs(20),
+* });
+* ```
+*/
+function createSkills(config) {
+	const { tools: alwaysOnTools, skills, filterSkill, onSkillsChanged } = config;
+	const loadedSkills = new Set(config.initialLoadedSkills ?? []);
+	const skillMap = new Map(skills.map((s) => [s.name, s]));
+	const allTools = {};
+	Object.assign(allTools, alwaysOnTools);
+	for (const skill of skills) Object.assign(allTools, skill.tools);
+	function getActiveToolNames() {
+		const names = [
+			ACTIVATE_SKILL,
+			LIST_CAPABILITIES,
+			...Object.keys(alwaysOnTools)
+		];
+		for (const skillName of loadedSkills) {
+			const skill = skillMap.get(skillName);
+			if (!skill) continue;
+			for (const toolName of Object.keys(skill.tools)) if (!names.includes(toolName)) names.push(toolName);
+		}
+		return names;
+	}
+	function getLoadedGuidance() {
+		return [...loadedSkills].map((name) => skillMap.get(name)?.guidance).filter((g) => Boolean(g)).join("\n\n");
+	}
+	function getSystem() {
+		const guidance = getLoadedGuidance();
+		if (!config.systemPrompt) return guidance;
+		return guidance ? `${config.systemPrompt}\n\n${guidance}` : config.systemPrompt;
+	}
+	allTools[ACTIVATE_SKILL] = tool({
+		description: buildActivateSkillDescription(skills),
+		inputSchema: jsonSchema({
+			type: "object",
+			properties: { skills: {
+				type: "array",
+				items: {
+					type: "string",
+					enum: skills.map((s) => s.name)
+				},
+				description: "Skills to load"
+			} },
+			required: ["skills"]
+		}),
+		execute: async ({ skills: requested }) => {
+			const newlyLoaded = [];
+			const denied = [];
+			for (const skillName of requested) {
+				if (!skillMap.get(skillName)) continue;
+				if (loadedSkills.has(skillName)) continue;
+				if (!(filterSkill ? await filterSkill(skillName) : true)) {
+					denied.push(skillName);
+					continue;
+				}
+				loadedSkills.add(skillName);
+				newlyLoaded.push(skillName);
+			}
+			if (newlyLoaded.length > 0 && onSkillsChanged) await onSkillsChanged([...loadedSkills]);
+			if (newlyLoaded.length > 0) {
+				let result = `Loaded: ${newlyLoaded.join(", ")}.`;
+				if (denied.length > 0) result += ` Access denied for: ${denied.join(", ")}.`;
+				return result;
+			}
+			if (denied.length > 0) return `Access denied for: ${denied.join(", ")}.`;
+			return ALREADY_LOADED_OUTPUT;
+		}
+	});
+	allTools[LIST_CAPABILITIES] = tool({
+		description: LIST_CAPABILITIES_DESCRIPTION,
+		inputSchema: jsonSchema({
+			type: "object",
+			properties: {},
+			required: []
+		}),
+		execute: async () => {
+			const activeNames = getActiveToolNames();
+			const loadedNames = [...loadedSkills];
+			const unloaded = skills.filter((s) => !loadedSkills.has(s.name)).map((s) => s.name);
+			return [
+				`Active tools (${activeNames.length}): ${activeNames.join(", ")}`,
+				`Loaded skills: ${loadedNames.length > 0 ? loadedNames.join(", ") : "none"}`,
+				`Available to load: ${unloaded.length > 0 ? unloaded.join(", ") : "none"}`
+			].join("\n");
+		}
+	});
+	const prepareStep = async () => {
+		return {
+			activeTools: getActiveToolNames(),
+			...config.systemPrompt !== void 0 && { system: getSystem() }
+		};
+	};
+	return {
+		tools: allTools,
+		activeTools: getActiveToolNames(),
+		prepareStep,
+		getLoadedGuidance,
+		getSystem,
+		getLoadedSkills() {
+			return [...loadedSkills];
+		}
+	};
+}
+const ALREADY_LOADED_OUTPUT = "All requested skills were already loaded.";
+const DENIED_OUTPUT_PREFIX = "Access denied for:";
+/**
+* Removes ephemeral messages from the conversation before it is saved to D1.
+*
+* Three kinds of messages are stripped:
+*
+* 1. list_capabilities tool calls — always stripped. Capability discovery is
+*    only relevant within the current turn; it adds no useful context for
+*    future turns.
+*
+* 2. activate_skill calls when nothing was newly loaded — stripped when all
+*    requested skills were already active, or when all were denied. In both
+*    cases nothing changed, so persisting the call would only add noise.
+*
+* 3. Guidance system messages — stripped by exact content match against the
+*    provided guidance string. Guidance is always recomputed from loaded skill
+*    definitions at turn start, so persisting it would create a redundant
+*    second source of truth alongside the loaded_skills D1 column.
+*
+* When skills ARE successfully loaded, the short "Loaded: X" result is kept
+* in history for model context — so the model can see what was loaded in
+* prior turns. Skill state is restored from D1 loaded_skills, not from these
+* strings.
+*
+* If stripping leaves an assistant message with no parts, the entire message
+* is dropped (e.g. a step that did nothing but call list_capabilities).
+*/
+function filterEphemeralMessages(messages, guidanceToStrip) {
+	return messages.flatMap((msg) => {
+		if (msg.role === "system" && guidanceToStrip) {
+			if (msg.parts?.some((p) => "text" in p && p.text === guidanceToStrip)) return [];
+		}
+		if (msg.role !== "assistant" || !msg.parts?.length) return [msg];
+		const filtered = msg.parts.filter((part) => {
+			if (!("toolCallId" in part)) return true;
+			const { type, output } = part;
+			if (type === `tool-list_capabilities`) return false;
+			if (type === `tool-activate_skill`) {
+				if (typeof output !== "string") return true;
+				return output !== ALREADY_LOADED_OUTPUT && !output.startsWith(DENIED_OUTPUT_PREFIX);
+			}
+			return true;
+		});
+		if (filtered.length === 0) return [];
+		if (filtered.length === msg.parts.length) return [msg];
+		return [{
+			...msg,
+			parts: filtered
+		}];
+	});
+}
+/**
+* Injects loaded skill guidance as a system message just before the last
+* message in the array (typically the current user turn).
+*
+* Guidance is kept separate from the static `system` prompt so that the
+* system prompt stays identical on every turn and can be prompt-cached.
+* Positioning just before the last message means guidance survives any
+* compaction strategy that preserves recent context.
+*
+* Pass `previousGuidance` (the string injected on the prior call) to remove
+* the stale guidance message before inserting the updated one. Removal is by
+* exact content match — not by role — so other system messages (memories,
+* user preferences, etc.) are left untouched.
+*
+* At turn start, omit `previousGuidance` — guidance is never persisted to D1
+* (it is stripped by filterEphemeralMessages before saving), so there is
+* nothing to remove. prepareStep uses previousGuidance within a turn to
+* handle guidance updates when new skills are loaded mid-turn.
+*
+* ```typescript
+* // Turn start — just inject
+* const messages = injectGuidance(modelMessages, skills.getLoadedGuidance());
+*
+* // prepareStep — remove stale guidance then re-inject updated guidance
+* const messages = injectGuidance(stepMessages, newGuidance, previousGuidance);
+* ```
+*/
+function injectGuidance(messages, guidance, previousGuidance) {
+	if (!guidance) return messages;
+	const base = previousGuidance ? messages.filter((m) => !(m.role === "system" && m.content === previousGuidance)) : messages;
+	const insertAt = base.findLastIndex((m) => m.role === "user");
+	return [
+		...base.slice(0, insertAt),
+		{
+			role: "system",
+			content: guidance
+		},
+		...base.slice(insertAt)
+	];
+}
+//#endregion
+//#region src/agents/chat/compaction/index.ts
+/**
+* Message compaction for long-running conversations.
+*
+* When the stored conversation history exceeds COMPACT_TOKEN_THRESHOLD, older
+* messages are summarised via an LLM call and replaced with a single system
+* message containing the summary, followed by the recent verbatim tail.
+*
+* Entry point: compactIfNeeded() — called once per turn from persistMessages.
+*
+* To remove compaction entirely: delete this directory, remove the import in
+* AIChatAgentBase, and change `toSave` back to `filtered`.
+*/
+const COMPACT_TOKEN_THRESHOLD = 14e4;
+const TOOL_RESULT_PREVIEW_CHARS = 200;
+const SUMMARY_MAX_TOKENS = 4e3;
+/**
+* Estimates token count for a message array using a 3.5 chars/token
+* approximation — the same heuristic used by slack-bot. Counts text from
+* text parts, tool inputs/outputs, and reasoning parts.
+*/
+function estimateMessagesTokens(messages) {
+	let totalChars = 0;
+	for (const msg of messages) {
+		if (!msg.parts) continue;
+		for (const part of msg.parts) {
+			if ((part.type === "text" || part.type === "reasoning") && "text" in part) {
+				totalChars += part.text.length;
+				continue;
+			}
+			if ("toolCallId" in part) {
+				const toolPart = part;
+				if (toolPart.input) totalChars += JSON.stringify(toolPart.input).length;
+				if (toolPart.output !== void 0) {
+					const outputStr = typeof toolPart.output === "string" ? toolPart.output : JSON.stringify(toolPart.output);
+					totalChars += outputStr.length;
+				}
+			}
+		}
+	}
+	return Math.ceil(totalChars / 3.5);
+}
+/**
+* Renders messages as human-readable text for the compaction summary prompt.
+* Text parts are included verbatim; tool calls show name and a truncated result.
+* step-start and empty messages are omitted.
+*/
+function formatMessagesForSummary(messages) {
+	const lines = [];
+	for (const msg of messages) {
+		const roleLabel = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
+		const parts = [];
+		for (const part of msg.parts ?? []) {
+			if (part.type === "step-start") continue;
+			if ((part.type === "text" || part.type === "reasoning") && "text" in part) {
+				const text = part.text.trim();
+				if (text) parts.push(text);
+				continue;
+			}
+			if ("toolCallId" in part) {
+				const toolPart = part;
+				const toolName = toolPart.type.startsWith("tool-") ? toolPart.type.slice(5) : toolPart.type;
+				const rawOutput = toolPart.output === void 0 ? "no result" : typeof toolPart.output === "string" ? toolPart.output : JSON.stringify(toolPart.output);
+				const preview = rawOutput.slice(0, TOOL_RESULT_PREVIEW_CHARS);
+				const ellipsis = rawOutput.length > TOOL_RESULT_PREVIEW_CHARS ? "..." : "";
+				parts.push(`[Tool: ${toolName}, result: ${preview}${ellipsis}]`);
+			}
+		}
+		if (parts.length > 0) lines.push(`${roleLabel}: ${parts.join(" ")}`);
+	}
+	return lines.join("\n\n");
+}
+/**
+* Calls the LLM to produce a concise summary of old + recent message windows.
+* Weights the prompt toward recent exchanges, matching slack-bot's approach.
+*/
+async function generateCompactionSummary(oldMessages, recentMessages, model) {
+	const prompt = `Summarize this conversation history concisely for an AI assistant to continue the conversation.
+Focus MORE on recent exchanges (what the user was working on, what tools were used, what was found).
+Include key facts, decisions, and context needed to continue the conversation.
+Keep entity names, numbers, file paths, and specific details that might be referenced later.
+Do NOT include pleasantries or meta-commentary - just the essential context.
+
+OLDER MESSAGES (summarize briefly):
+${formatMessagesForSummary(oldMessages)}
+
+RECENT MESSAGES (summarize with more detail - this is where the user currently is):
+${formatMessagesForSummary(recentMessages)}
+
+Write a concise summary:`;
+	try {
+		const { text } = await generateText({
+			model,
+			messages: [{
+				role: "user",
+				content: prompt
+			}],
+			maxOutputTokens: SUMMARY_MAX_TOKENS
+		});
+		return text || "Unable to summarize conversation history.";
+	} catch (error) {
+		console.error("Compaction summarization error:", error);
+		return "Unable to summarize conversation history.";
+	}
+}
+/**
+* Summarizes older messages into a single system message and appends the
+* recent verbatim tail. Returns messages unchanged if the history is already
+* short enough to fit within tailSize.
+*/
+async function compactMessages(messages, model, tailSize) {
+	if (messages.length <= tailSize) return messages;
+	const splitIndex = messages.length - tailSize;
+	const oldMessages = messages.slice(0, splitIndex);
+	const recentTail = messages.slice(splitIndex);
+	const summary = await generateCompactionSummary(oldMessages, recentTail, model);
+	return [{
+		id: `compact_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+		role: "system",
+		parts: [{
+			type: "text",
+			text: `[Conversation summary - older context was compacted]\n${summary}`,
+			state: "done"
+		}]
+	}, ...recentTail];
+}
+/**
+* Entry point called from persistMessages once per turn.
+*
+* Returns messages unchanged when:
+* - model is undefined (compaction disabled on this agent)
+* - estimated token count is under COMPACT_TOKEN_THRESHOLD
+*
+* Otherwise delegates to compactMessages.
+*/
+async function compactIfNeeded(messages, model, tailSize) {
+	if (!model || estimateMessagesTokens(messages) <= 14e4) return messages;
+	return compactMessages(messages, model, tailSize);
+}
+//#endregion
+//#region src/agents/chat/AIChatAgentBase.ts
+/**
+* Base class for chat agents with lazy skill loading.
+*
+* Owns:
+* - D1 persistence for loaded skill state (skill names survive DO eviction)
+* - Ephemeral message filtering (list_capabilities, no-op activate_skill calls)
+* - Message compaction (LLM summarisation when history exceeds token threshold)
+* - History replay to newly connected clients (onConnect override)
+* - Skill context preparation for use with the @withSkills decorator
+*
+* Conversation messages are stored in Durable Object SQLite, managed
+* automatically by the Cloudflare AIChatAgent — no D1 write needed for messages.
+*
+* D1 is written only when skills change (activate_skill was called this turn),
+* not on every turn.
+*
+* ## Usage
+*
+* Extend this class when you want full control over `streamText`. Implement
+* `getTools()`, `getSkills()`, and your own `onChatMessage` decorated with
+* `@withSkills`:
+*
+* ```typescript
+* export class MyAgent extends AIChatAgentBase {
+*   getTools()  { return []; }
+*   getSkills() { return [searchSkill, codeSkill]; }
+*   getDB()     { return this.env.AGENT_DB; }
+*
+*   @withSkills
+*   async onChatMessage(onFinish, ctx: SkillContext, options?) {
+*     const { messages, ...skillArgs } = ctx;
+*     return streamText({
+*       model: openai("gpt-4o"),
+*       system: "You are a helpful assistant.",
+*       messages,
+*       ...skillArgs,
+*       onFinish,
+*       stopWhen: stepCountIs(20),
+*     }).toUIMessageStreamResponse();
+*   }
+* }
+* ```
+*
+* For a batteries-included experience where the base class owns `onChatMessage`,
+* extend `AIChatAgent` instead.
+*/
+var AIChatAgentBase = class extends AIChatAgent$1 {
+	/**
+	* Maximum number of messages stored in DO SQLite.
+	*
+	* Lowered from the Cloudflare AIChatAgent default of 200. When compaction
+	* is enabled, one slot is reserved for the summary message so the verbatim
+	* tail is maxPersistedMessages - 1 recent messages. Raise or lower per agent.
+	*/
+	maxPersistedMessages = 50;
+	/**
+	* Return a LanguageModel to use for compaction summarisation.
+	*
+	* Return undefined (default) to disable compaction — messages are kept up
+	* to maxPersistedMessages and older ones are dropped by the Cloudflare
+	* AIChatAgent's built-in hard cap.
+	*
+	* Override to use a cheaper or faster model for summarisation, or to enable
+	* compaction in subclasses that do not override it automatically.
+	*/
+	getCompactionModel() {}
+	/**
+	* Return the D1 database binding for persisting loaded skill state.
+	*
+	* Override in your subclass to return the binding from env:
+	* ```typescript
+	* protected getDB() { return this.env.AGENT_DB; }
+	* ```
+	*
+	* Defaults to undefined — when undefined, loaded skills reset on every new
+	* conversation (skills still work within a turn, just not across turns).
+	*/
+	getDB() {}
+	/**
+	* Optional permission hook. Return false to deny the agent access to a
+	* skill when activate_skill is called. Defaults to allow-all.
+	*/
+	async filterSkill(_skillName) {
+		return true;
+	}
+	/**
+	* Buffered skill state from the current turn.
+	*
+	* Set by the onSkillsChanged callback when activate_skill loads new skills
+	* mid-turn. Flushed to D1 in persistMessages at turn end — only written
+	* when this value is set, so D1 is not touched on turns where no new skills
+	* are loaded.
+	*/
+	_pendingSkills;
+	/**
+	* Reads loaded skill names from D1 for this agent.
+	*
+	* Returns an empty array if no record exists (first turn, or no skills
+	* loaded yet). Conversation messages are not read here — the Cloudflare
+	* AIChatAgent provides those via this.messages from DO SQLite.
+	*/
+	async _readSkillState() {
+		const row = await this.getDB()?.prepare("SELECT loaded_skills FROM agent_state WHERE agent_id = ?").bind(this.name).first();
+		if (!row?.loaded_skills) return [];
+		return JSON.parse(row.loaded_skills);
+	}
+	/**
+	* Writes loaded skill names to D1 for this agent.
+	*
+	* Uses INSERT OR REPLACE so the first skill load creates the row and
+	* subsequent loads update it. Only called when skills actually changed
+	* this turn (_pendingSkills is set).
+	*/
+	async _writeSkillState(skills) {
+		await this.getDB()?.prepare("INSERT OR REPLACE INTO agent_state (agent_id, loaded_skills, last_updated) VALUES (?, ?, ?)").bind(this.name, JSON.stringify(skills), Date.now()).run();
+	}
+	/**
+	* Flush persisted message history to a newly connected client.
+	*
+	* The Cloudflare AIChatAgent broadcasts message updates to existing
+	* connections via persistMessages, but does nothing for connections that
+	* arrive after a conversation has ended. Without this override, a page
+	* refresh produces an empty UI even though the history is intact in DO SQLite.
+	*
+	* Skips replay when a stream is active — CF_AGENT_STREAM_RESUMING handles
+	* that case and replays in-progress chunks via its own protocol.
+	*/
+	async onConnect(connection, ctx) {
+		await super.onConnect(connection, ctx);
+		if (!this._activeStreamId && this.messages.length > 0) connection.send(JSON.stringify({
+			type: "cf_agent_chat_messages",
+			messages: this.messages
+		}));
+	}
+	/**
+	* Strips ephemeral content, conditionally saves skill state to D1, then
+	* delegates to super for DO SQLite persistence and WebSocket broadcast.
+	*
+	* The Cloudflare AIChatAgent calls persistMessages once per turn after all
+	* steps complete, so overriding here is the correct place to act — it runs
+	* after the full assistant message (including all tool results) is assembled.
+	*
+	* Two things happen here:
+	*
+	* 1. Ephemeral tool calls are stripped — list_capabilities (always) and
+	*    activate_skill when nothing was newly loaded (no state change).
+	*
+	* 2. If skills changed this turn (_pendingSkills is set), the updated list
+	*    is written to D1. Turns where no skills were loaded do not touch D1.
+	*
+	* Message persistence itself is handled by super.persistMessages, which
+	* writes to DO SQLite — no D1 write needed for messages.
+	*/
+	async persistMessages(messages, excludeBroadcastIds = [], options) {
+		const filtered = filterEphemeralMessages(messages);
+		if (this._pendingSkills !== void 0) {
+			await this._writeSkillState(this._pendingSkills);
+			this._pendingSkills = void 0;
+		}
+		const toSave = await compactIfNeeded(filtered, this.getCompactionModel(), this.maxPersistedMessages - 1);
+		return super.persistMessages(toSave, excludeBroadcastIds, options);
+	}
+	/**
+	* Widened onChatMessage signature that accommodates the @withSkills decorator.
+	*
+	* The decorator transforms the consumer's 3-arg form (onFinish, ctx, options) into
+	* a 2-arg wrapper at runtime. This declaration widens the base class signature so
+	* that TypeScript accepts the consumer's 3-arg override without errors.
+	*
+	* @ts-ignore — intentional: widens the Cloudflare AIChatAgent's (onFinish, options?) signature.
+	*/
+	onChatMessage(onFinish, ctxOrOptions) {
+		return super.onChatMessage(onFinish, ctxOrOptions);
+	}
+	/**
+	* Called by the @withSkills decorator at the start of each turn.
+	*
+	* Reads loaded skill state from D1, seeds createSkills, and returns a
+	* SkillContext ready to use in a streamText call.
+	*
+	* Guidance is exposed as `ctx.guidance` — compose your system prompt as:
+	* `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
+	*
+	* Messages are plain (no guidance injected). Guidance stays out of the
+	* messages array — Anthropic/Gemini only allow system messages at position 0.
+	*/
+	async _prepareSkillContext() {
+		const loadedSkills = await this._readSkillState();
+		const skills = createSkills({
+			tools: this.getTools(),
+			skills: this.getSkills(),
+			initialLoadedSkills: loadedSkills,
+			onSkillsChanged: async (updated) => {
+				this._pendingSkills = updated;
+			},
+			filterSkill: (name) => this.filterSkill(name)
+		});
+		return {
+			tools: skills.tools,
+			activeTools: skills.activeTools,
+			prepareStep: skills.prepareStep,
+			guidance: skills.getLoadedGuidance(),
+			messages: await convertToModelMessages(this.messages)
+		};
+	}
+};
+function withSkills(fn, _context) {
+	const wrapper = async function(onFinish, maybeOptions) {
+		const ctx = await this._prepareSkillContext();
+		return fn.call(this, onFinish, ctx, maybeOptions);
+	};
+	return wrapper;
+}
+//#endregion
+//#region src/agents/chat/AIChatAgent.ts
+/**
+* Batteries-included base class for chat agents with lazy skill loading.
+*
+* Owns the full `onChatMessage` lifecycle. Implement four abstract methods and
+* get lazy skill loading, cross-turn skill persistence, guidance injection,
+* ephemeral message cleanup, and message compaction for free.
+*
+* Conversation messages are stored in Durable Object SQLite by the Cloudflare
+* AIChatAgent automatically — available as this.messages at the start of each
+* turn. Loaded skill state is stored in D1 (via getDB()) and read at turn start.
+* Guidance is injected as a system message just before the current user turn,
+* keeping the `system` param static and cacheable across all turns.
+*
+* ```typescript
+* export class MyAgent extends AIChatAgent {
+*   getModel()        { return openai("gpt-4o"); }
+*   getTools()        { return tools; }
+*   getSkills()       { return [searchSkill, codeSkill]; }
+*   getSystemPrompt() { return "You are a helpful assistant."; }
+*   getDB()           { return this.env.AGENT_DB; }
+* }
+* ```
+*
+* If you need full control over the `streamText` call (custom model options,
+* streaming transforms, varying the model per request, etc.) use
+* `AIChatAgentBase` with the `@withSkills` decorator instead.
+*/
+var AIChatAgent = class extends AIChatAgentBase {
+	/**
+	* Return the model used for compaction summarisation.
+	*
+	* Defaults to getModel() — the agent's primary model — so compaction is
+	* enabled automatically. Override to substitute a cheaper or faster model
+	* for summarisation (e.g. a smaller model when the primary is expensive).
+	*
+	* To opt out of message compaction: override and return undefined.
+	*/
+	getCompactionModel() {
+		return this.getModel();
+	}
+	async onChatMessage(onFinish, options) {
+		const loadedSkills = await this._readSkillState();
+		const skills = createSkills({
+			tools: this.getTools(),
+			skills: this.getSkills(),
+			systemPrompt: this.getSystemPrompt(),
+			initialLoadedSkills: loadedSkills,
+			onSkillsChanged: async (updated) => {
+				this._pendingSkills = updated;
+			},
+			filterSkill: (name) => this.filterSkill(name)
+		});
+		return streamText({
+			model: this.getModel(),
+			system: skills.getSystem(),
+			messages: await convertToModelMessages(this.messages),
+			tools: skills.tools,
+			activeTools: skills.activeTools,
+			prepareStep: skills.prepareStep,
+			experimental_context: options?.body,
+			stopWhen: stepCountIs(20),
+			abortSignal: options?.abortSignal,
+			onFinish
+		}).toUIMessageStreamResponse();
+	}
+};
+//#endregion
+export { AIChatAgent, AIChatAgentBase, COMPACT_TOKEN_THRESHOLD, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@economic/agents",
+  "version": "0.0.1-alpha.10",
+  "description": "A starter for creating a TypeScript package.",
+  "homepage": "https://github.com/author/library#readme",
+  "bugs": {
+    "url": "https://github.com/author/library/issues"
+  },
+  "license": "MIT",
+  "author": "Author Name <author.name@mail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/author/library.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@cloudflare/ai-chat": "^0.1.9",
+    "ai": "^6.0.116"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260317.1",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260316.1",
+    "bumpp": "^11.0.1",
+    "typescript": "^5.9.3",
+    "vite-plus": "latest",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "inlinedDependencies": {
+    "partyserver": "0.3.3",
+    "zod": "3.25.76",
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "agents": "0.7.6"
+  }
+}