@economic/agents 0.0.1-alpha.2 → 0.0.1-alpha.21

package/dist/index.d.mts

@@ -1,95 +1,7 @@
-import * as ai from "ai";
-import { LanguageModel, ModelMessage, PrepareStepFunction, StreamTextOnFinishCallback, ToolSet, UIMessage } from "ai";
 import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/ai-chat";
+import { LanguageModel, ToolSet, UIMessage, generateText, streamText } from "ai";
 
-//#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 single tool with a name, JSON Schema parameters, and an execute function.
- *
- * Tools are defined in this SDK-agnostic format and converted to the
- * target SDK's format by the adapter layer (createSkills).
- */
-interface Tool {
-  name: string;
-  description: string;
-  /** JSON Schema object describing the tool's input parameters */
-  parameters: Record<string, unknown>;
-  execute(args: Record<string, unknown>, options: {
-    toolCallId: string;
-  }): Promise<string>;
-}
+//#region src/features/skills/index.d.ts
 /**
  * A named group of related tools that can be loaded together on demand.
  *
@@ -103,459 +15,220 @@ interface Skill {
   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.
+   * when to use each tool. Appended to the `system` prompt each turn for any
+   * skill that is loaded, keeping `system` mostly cacheable.
    */
   guidance?: string;
-  tools: Tool[];
+  tools: ToolSet;
 }
-/**
- * Configuration passed to createSkills().
- */
-interface SkillsConfig {
-  /** Tools that are always active regardless of loaded skills */
-  tools: Tool[];
-  /** All available skills that can be loaded on demand */
-  skills: Skill[];
-  /**
-   * 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[];
+//#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[];
   /**
-   * 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.
+   * 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.
    */
-  onSkillsChanged?: (skills: string[]) => Promise<void>;
+  maxMessagesBeforeCompaction?: number;
   /**
-   * Optional permission hook. Return false to deny access to a skill.
-   * Defaults to allow-all if not provided.
+   * The fast/cheap model used for compaction and background summarization.
+   * Provided automatically from `AIChatAgent.fastModel` — do not set this directly.
+   *
+   * @internal
    */
-  filterSkill?: (skillName: string) => Promise<boolean> | boolean;
-}
+  fastModel?: LanguageModel;
+};
 /**
- * Skill context injected by the @withSkills decorator.
+ * 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.
  *
- * Spread the context fields directly into streamText — messages already has
- * guidance injected at the correct position:
+ * The returned object can be spread directly into `streamText` or `generateText`:
  *
  * ```typescript
- * const { messages, ...skillArgs } = ctx;
- * return streamText({
- *   model: this.getModel(),
- *   system: "Your base prompt — static, never includes guidance",
- *   messages,
- *   ...skillArgs,
- *   onFinish,
- *   stopWhen: stepCountIs(20),
- * }).toUIMessageStreamResponse();
+ * const params = await buildLLMParams({ ... });
+ * return streamText(params).toUIMessageStreamResponse();
  * ```
  */
-interface SkillContext {
-  /** All registered tools — spread into streamText */
-  tools: ai.ToolSet;
-  /** Currently active tool names — spread into streamText */
-  activeTools: string[];
-  /**
-   * Updates active tools and the guidance system message before each LLM step.
-   * Spread into streamText.
-   */
-  prepareStep: ai.PrepareStepFunction;
-  /**
-   * Conversation messages read from D1 with current skill guidance already
-   * injected just before the last message (the current user turn). 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[];
-}
+declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams>;
 //#endregion
-//#region src/agents/chat/AIChatAgentBase.d.ts
+//#region src/agents/AIChatAgent.d.ts
 /**
- * Base class for chat agents with lazy skill loading.
+ * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
+ * and built-in audit logging.
  *
- * 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
+ * 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.
  *
- * 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.
+ * Skill loading, compaction, and LLM communication are delegated to
+ * `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
  */
-declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent$1<Env> {
+declare abstract class AIChatAgent<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.
+   * 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.
    */
-  maxPersistedMessages: number;
-  /** Tools that are always active regardless of loaded skills */
-  abstract getTools(): Tool[];
-  /** All skills available for on-demand loading */
-  abstract getSkills(): Skill[];
+  protected _userId: string | undefined;
   /**
-   * 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.
+   * Fast/cheap language model used for background tasks: compaction and conversation summarization.
    *
-   * 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.
+   * Declare this on every subclass:
    *
-   * Override in your subclass to return the binding from env:
    * ```typescript
-   * protected getDB() { return this.env.AGENT_DB; }
+   * protected fastModel = google("gemini-2.0-flash");
    * ```
    *
-   * 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.
+   * To disable compaction for a specific call, pass `maxMessagesBeforeCompaction: undefined`
+   * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
    */
-  protected _pendingSkills: string[] | undefined;
+  protected abstract fastModel: LanguageModel;
   /**
-   * 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.
+   * 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.
    */
-  protected _readSkillState(): Promise<string[]>;
+  private resolveD1Context;
   /**
-   * Writes loaded skill names to D1 for this agent.
+   * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
+   * otherwise silently does nothing.
    *
-   * 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).
+   * 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 _writeSkillState(skills: string[]): Promise<void>;
+  protected log(message: string, payload?: Record<string, unknown>): 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.
+   * Records this conversation in the `conversations` D1 table and triggers
+   * LLM-based title/summary generation when appropriate. Called automatically
+   * from `persistMessages` after every turn.
    *
-   * Skips replay when a stream is active — CF_AGENT_STREAM_RESUMING handles
-   * that case and replays in-progress chunks via its own protocol.
+   * On the first turn (no existing row), awaits `generateTitleAndSummary` and
+   * inserts the row with title and summary already populated. On subsequent
+   * turns, upserts the timestamp and fire-and-forgets a summary refresh every
+   * `SUMMARY_CONTEXT_MESSAGES` messages (when the context window fully turns
+   * over). Neither path blocks the response to the client.
    */
-  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  private recordConversation;
   /**
-   * Strips ephemeral content, conditionally saves skill state to D1, then
-   * delegates to super for DO SQLite persistence and WebSocket broadcast.
+   * Builds the parameter object for a `streamText` or `generateText` call,
+   * pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
+   * Injects `log` into `experimental_context` and logs non-clean finish reasons.
    *
-   * 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.
+   * **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.
    *
-   * Two things happen here:
+   * ```typescript
+   * // Compaction on (default threshold):
+   * const params = await this.buildLLMParams({ options, onFinish, model, system: "..." });
    *
-   * 1. Ephemeral tool calls are stripped — list_capabilities (always) and
-   *    activate_skill when nothing was newly loaded (no state change).
+   * // Compaction with custom threshold:
+   * const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: 50 });
    *
-   * 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.
+   * // Compaction off:
+   * const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: undefined });
    *
-   * Message persistence itself is handled by super.persistMessages, which
-   * writes to DO SQLite — no D1 write needed for messages.
+   * return streamText(params).toUIMessageStreamResponse();
+   * ```
    */
-  persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
-    _deleteStaleRows?: boolean;
-  }): Promise<void>;
+  protected buildLLMParams(config: Omit<BuildLLMParamsConfig, "messages" | "activeSkills" | "fastModel">): ReturnType<typeof buildLLMParams>;
   /**
-   * 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.
+   * Skill names persisted from previous turns, read from DO SQLite.
+   * Returns an empty array if no skills have been loaded yet.
    */
-  onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, ctxOrOptions?: SkillContext | OnChatMessageOptions): Promise<Response | undefined>;
+  protected getLoadedSkills(): Promise<string[]>;
   /**
-   * Called by the @withSkills decorator at the start of each turn.
+   * 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.
    *
-   * Reads loaded skill state from D1, seeds createSkills, injects guidance,
-   * and returns a SkillContext ready to use in a streamText call.
+   * 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.
    *
-   * The returned `messages` already has guidance injected just before the
-   * current user turn — pass it directly as the `messages` param of streamText.
-   * Guidance is never stored in DO SQLite, so loaded_skills in D1 is the
-   * single source of truth for which skills are active.
-   */
-  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, ...skillArgs } = ctx;
- *   return streamText({
- *     model: this.getModel(),
- *     system: "Your base prompt — static, never includes guidance",
- *     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 []; }
- *   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(): Tool[];
-  /** 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.
+   * 2. Logs a turn summary via `log()`. Best-effort: fire-and-forget.
    *
-   * 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).
+   * 3. Strips all activate_skill and list_capabilities messages from history.
    *
-   * To opt out of message compaction: override and return undefined.
+   * 4. Delegates to super.persistMessages for message storage and WS broadcast.
    */
-  protected getCompactionModel(): LanguageModel;
-  onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response | undefined>;
+  persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
+    _deleteStaleRows?: boolean;
+  }): Promise<void>;
 }
 //#endregion
-//#region src/features/skills/index.d.ts
+//#region src/decorators/guard.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";
+ * Function run before a guarded handler (e.g. `onChatMessage`). Receives the
+ * custom request body from chat options (`options.body`, same shape as
+ * `OnChatMessageOptions` from `@cloudflare/ai-chat`).
  *
- * // 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());
+ * Return a {@link Response} to short-circuit and skip the decorated method.
+ * Return nothing (or `undefined`) to allow the method to run.
  *
- * 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),
- * });
- * ```
+ * Typical uses include auth, rate limits, or feature flags — all logic lives here;
+ * the `guard` decorator only forwards `body` and handles the return shape.
  */
-declare function createSkills(config: SkillsConfig): SkillsResult & {
-  tools: ToolSet;
-  activeTools: string[];
-  prepareStep: PrepareStepFunction;
-};
+type GuardFn<TBody = Record<string, unknown>> = (body: TBody | undefined) => Response | void | Promise<Response | void>;
 /**
- * Removes ephemeral messages from the conversation before it is saved to D1.
- *
- * Three kinds of messages are stripped:
+ * Method decorator (TypeScript 5+ stage-3) that runs `guardFn` with the second
+ * argument's `body` (the chat request body). If `guardFn` returns a
+ * {@link Response}, that value is returned and the original method is not called.
  *
- * 1. list_capabilities tool calls — always stripped. Capability discovery is
- *    only relevant within the current turn; it adds no useful context for
- *    future turns.
+ * Intended for `onChatMessage(onFinish, options?)` on subclasses of
+ * `AIChatAgent`; `options` is read as `{ body?: TBody }`.
  *
- * 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.
+ * @param guardFn - Called with `options?.body` (cast to `TBody`) before the method body.
  *
- * 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).
+ * @example
+ * ```ts
+ * interface RequestBody { token: string }
  *
- * 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());
+ * const requireToken: GuardFn<RequestBody> = async (body) => {
+ *   if (!await isValidToken(body?.token)) {
+ *     return new Response("Unauthorized", { status: 401 });
+ *   }
+ * };
  *
- * // prepareStep — remove stale guidance then re-inject updated guidance
- * const messages = injectGuidance(stepMessages, newGuidance, previousGuidance);
+ * class MyAgent extends AIChatAgent<Env> {
+ *   @guard(requireToken)
+ *   async onChatMessage(onFinish, options) {
+ *     // ...
+ *   }
+ * }
  * ```
  */
-declare function injectGuidance(messages: ModelMessage[], guidance: string, previousGuidance?: string): ModelMessage[];
+declare function guard<TBody = Record<string, unknown>>(guardFn: GuardFn<TBody>): (target: (...args: unknown[]) => Promise<Response>, _context: ClassMethodDecoratorContext) => (this: unknown, ...args: unknown[]) => Promise<Response>;
 //#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[]>;
+//#region src/types.d.ts
 /**
- * Entry point called from persistMessages once per turn.
+ * 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`.
  *
- * Returns messages unchanged when:
- * - model is undefined (compaction disabled on this agent)
- * - estimated token count is under COMPACT_TOKEN_THRESHOLD
- *
- * Otherwise delegates to compactMessages.
+ * Define your own body shape and compose:
+ * ```typescript
+ * interface MyBody { userId: string; userTier: "free" | "pro" }
+ * type MyContext = AgentContext<MyBody>;
+ * ```
  */
-declare function compactIfNeeded(messages: UIMessage[], model: LanguageModel | undefined, tailSize: number): Promise<UIMessage[]>;
+type AgentContext<TBody = Record<string, unknown>> = TBody & {
+  log: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
+};
 //#endregion
-export { AIChatAgent, AIChatAgentBase, COMPACT_TOKEN_THRESHOLD, type Skill, type SkillContext, type SkillsConfig, type SkillsResult, type Tool, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };
+export { AIChatAgent, type AgentContext, type BuildLLMParamsConfig, type GuardFn, type Skill, buildLLMParams, guard };