@economic/agents 0.0.1-beta.6 → 1.0.0

package/dist/index.d.mts

@@ -1,7 +1,26 @@
-import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/ai-chat";
-import { LanguageModel, ToolSet, UIMessage, generateText, streamText } from "ai";
-import { Connection, ConnectionContext } from "agents";
+import { Agent as Agent$1, Connection, ConnectionContext } from "agents";
+import { AIChatAgent, OnChatMessageOptions } from "@cloudflare/ai-chat";
+import { LanguageModel, StreamTextOnFinishCallback, ToolSet, UIMessage, generateText, streamText } from "ai";
 
+//#region src/server/types.d.ts
+/**
+ * The context object available throughout an agent's lifetime — passed via
+ * `experimental_context` to tool `execute` functions. Contains the typed
+ * request body merged with platform capabilities like `logEvent`.
+ *
+ * Define your own body shape and compose:
+ * ```typescript
+ * interface MyBody { userTier: "free" | "pro" }
+ * type MyContext = AgentToolContext<MyBody>;
+ * ```
+ */
+type AgentToolContext<TBody = Record<string, unknown>> = TBody & {
+  logEvent: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
+};
+interface AgentEnv {
+  AGENT_DB: D1Database;
+}
+//#endregion
 //#region src/server/features/skills/index.d.ts
 /**
  * A named group of related tools that can be loaded together on demand.
@@ -26,60 +45,82 @@ interface Skill {
 //#endregion
 //#region src/server/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. */
+type BuildLLMParamsConfig = Omit<LLMParams, "prompt"> & {
+  /** Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`. */activeSkills?: string[]; /** Skills available for on-demand loading this turn. */
   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.
  *
- * Handles message conversion, optional compaction, skill wiring (`activate_skill`,
- * `list_capabilities`, `prepareStep`), and context/abort signal extraction from
- * the Cloudflare Agents SDK `options` object.
+ * Handles skill wiring (`activate_skill`, `list_capabilities`, `prepareStep`).
  *
  * The returned object can be spread directly into `streamText` or `generateText`:
  *
  * ```typescript
- * const params = await buildLLMParams({ ... });
+ * const params = buildLLMParams({ ... });
  * return streamText(params).toUIMessageStreamResponse();
  * ```
  */
-declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams>;
+declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
+//#endregion
+//#region src/server/agents/Agent.d.ts
+/**
+ * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
+ * audit logging, and `buildLLMParams` wiring.
+ *
+ * Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state
+ * and writing audit events to D1.
+ *
+ * For chat agents with message history, compaction, and conversation recording,
+ * extend {@link ChatAgent} instead.
+ */
+declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env> extends Agent$1<Env & AgentEnv> {
+  /**
+   * Returns the user ID from the durable object name.
+   */
+  protected getUserId(): string;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  /**
+   * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
+   * otherwise silently does nothing.
+   *
+   * Called automatically at the end of each LLM turn (from `onFinish` in
+   * `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
+   * `execute` functions.
+   */
+  protected logEvent(message: string, payload?: Record<string, unknown>): Promise<void>;
+  /**
+   * Builds the parameter object for a `streamText` or `generateText` call,
+   * pre-filling `activeSkills` from this agent instance.
+   * Injects `logEvent` into `experimental_context` and wires `onFinish` for
+   * turn-completed audit events.
+   */
+  protected buildLLMParams<TBody = Record<string, unknown>>(config: Omit<BuildLLMParamsConfig, "messages"> & {
+    options?: OnChatMessageOptions;
+  }): Promise<LLMParams>;
+}
 //#endregion
-//#region src/server/agents/AIChatAgent.d.ts
+//#region src/server/agents/ChatAgent.d.ts
 /**
- * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
- * and built-in audit logging.
+ * Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,
+ * message persistence, compaction, and conversation metadata in D1.
  *
- * 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.
+ * Handles CF infrastructure concerns: DO SQLite for loaded skill state,
+ * stripping skill meta-tool messages before persistence, history replay to
+ * newly connected clients, and audit events to D1.
  *
- * Skill loading, compaction, and LLM communication are delegated to
- * `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
+ * Skill loading, compaction, and LLM calls use `buildLLMParams` from
+ * `@economic/agents` inside `onChatMessage`.
  */
-declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent$1<Env> {
+declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent<Env & AgentEnv> {
+  /**
+   * The binding of the Durable Object instance for this agent.
+   */
+  protected abstract get binding(): {
+    getByName(name: string): {
+      destroy(): Promise<void>;
+    };
+  };
   /**
    * Fast/cheap language model used for background tasks: compaction and conversation summarization.
    *
@@ -92,101 +133,115 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    * To disable compaction for a specific call, pass `maxMessagesBeforeCompaction: undefined`
    * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
    */
-  protected abstract fastModel: LanguageModel;
-  protected getUserId(): string;
-  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  protected abstract getFastModel(): LanguageModel;
   /**
-   * Resolves the D1 database binding required for all D1 writes.
-   * Returns null and silently no-ops if AGENT_DB is not bound.
+   * Number of days of inactivity before the full conversation is deleted.
+   *
+   * Leave `undefined` to disable automatic retention cleanup.
    */
-  private resolveD1Context;
+  protected conversationRetentionDays?: number;
   /**
-   * Returns all conversations for the current user.
+   * 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`.
+   *
+   * Default is 15.
    */
-  getConversations(): Promise<Record<string, unknown>[] | undefined>;
+  protected maxMessagesBeforeCompaction?: number | undefined;
   /**
-   * 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
-   * non-clean finish reasons (from `buildLLMParams`). Also available via
-   * `experimental_context.log` in tool `execute` functions.
+   * Returns the user ID from the durable object name.
    */
-  protected log(message: string, payload?: Record<string, unknown>): Promise<void>;
+  protected getUserId(): string;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
-   * Records this conversation in the `conversations` D1 table and triggers
-   * LLM-based title/summary generation when appropriate. Called automatically
-   * from `persistMessages` after every turn.
+   * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
+   * otherwise silently does nothing.
    *
-   * 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.
+   * Called automatically at the end of each LLM turn (from `onFinish` in
+   * `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
+   * `execute` functions.
    */
-  private recordConversation;
+  protected logEvent(message: string, payload?: Record<string, unknown>): Promise<void>;
   /**
    * 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.
+   * Injects `logEvent` into `experimental_context` and wires `onFinish` for
+   * turn-completed audit events and conversation recording.
    *
    * **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();
-   * ```
+   * threshold by setting `maxMessagesBeforeCompaction` on the class. Disable compaction
+   * entirely by setting `maxMessagesBeforeCompaction = undefined` explicitly.
    */
-  protected buildLLMParams<TBody = Record<string, unknown>>(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.
-   */
-  protected getLoadedSkills(): Promise<string[]>;
+  protected buildLLMParams<TBody = Record<string, unknown>>(config: BuildLLMParamsConfig & {
+    options?: OnChatMessageOptions;
+  }): Promise<LLMParams>;
   /**
    * 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.
+   * then strips all skill meta-tool messages before delegating to super.
    *
    * 1. Scans activate_skill tool results for SKILL_STATE_SENTINEL. When found,
    *    the embedded JSON array of loaded skill names is written to DO SQLite.
    *
-   * 2. Logs a turn summary via `log()`. Best-effort: fire-and-forget.
-   *
-   * 3. Strips all activate_skill and list_capabilities messages from history.
+   * 2. Strips all activate_skill and list_capabilities messages from history.
    *
-   * 4. Delegates to super.persistMessages for message storage and WS broadcast.
+   * 3. Delegates to super.persistMessages for message storage and WS broadcast.
    */
   persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
     _deleteStaleRows?: boolean;
   }): Promise<void>;
+  getConversations(): Promise<Record<string, unknown>[]>;
+  deleteConversation(id: string): Promise<boolean>;
+  destroy(): Promise<void>;
+  /**
+   * Records this conversation in the `conversations` D1 table and triggers
+   * LLM-based title/summary generation when appropriate. Called automatically
+   * from `onFinish` in `buildLLMParams` after each completed LLM turn.
+   *
+   * 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.
+   */
+  private recordConversation;
+  private deleteConversationCallback;
+  private scheduleConversationForDeletion;
 }
 //#endregion
-//#region src/server/types.d.ts
-/**
- * The context object available throughout an agent's lifetime — passed via
- * `experimental_context` to tool `execute` functions. Contains the typed
- * request body merged with platform capabilities like `log`.
- *
- * Define your own body shape and compose:
- * ```typescript
- * interface MyBody { userTier: "free" | "pro" }
- * type MyContext = AgentToolContext<MyBody>;
- * ```
- */
-type AgentToolContext<TBody = Record<string, unknown>> = TBody & {
-  log: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
-};
+//#region src/server/harnesses/ChatAgentHarness.d.ts
+declare abstract class ChatAgentHarness<Env extends Cloudflare.Env, RequestBody extends Record<string, unknown> = Record<string, unknown>> extends ChatAgent<Env> {
+  get binding(): {
+    getByName(name: string): {
+      destroy(): Promise<void>;
+    };
+  };
+  conversationRetentionDays: number;
+  /**
+   * Returns the model for the agent.
+   * @param ctx - The context object for the agent built from the request body.
+   * @returns The model for the agent.
+   */
+  abstract getModel(ctx: AgentToolContext<RequestBody>): LanguageModel;
+  /**
+   * Returns the system prompt for the agent.
+   * @param ctx - The context object for the agent built from the request body.
+   * @returns The system prompt for the agent.
+   */
+  abstract getSystemPrompt(ctx: AgentToolContext<RequestBody>): string;
+  /**
+   * Returns the tools for the agent.
+   * @param ctx - The context object for the agent built from the request body.
+   * @returns The tools for the agent.
+   */
+  getTools(_ctx: AgentToolContext<RequestBody>): ToolSet;
+  /**
+   * Returns the skills for the agent.
+   * @param ctx - The context object for the agent built from the request body.
+   * @returns The skills for the agent.
+   */
+  getSkills(_ctx: AgentToolContext<RequestBody>): Skill[];
+  onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response>;
+}
 //#endregion
-export { AIChatAgent, type AgentToolContext, type BuildLLMParamsConfig, type Skill, buildLLMParams };
+export { Agent, type AgentToolContext, type BuildLLMParamsConfig, ChatAgent, ChatAgentHarness, type Skill, buildLLMParams };