@economic/agents 0.0.1 → 1.0.0

package/dist/index.d.mts

@@ -1,7 +1,26 @@
-import { Connection, ConnectionContext } from "agents";
-import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/ai-chat";
-import { LanguageModel, ToolSet, UIMessage, generateText, streamText } from "ai";
+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.
@@ -44,22 +63,64 @@ type BuildLLMParamsConfig = Omit<LLMParams, "prompt"> & {
  */
 declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
 //#endregion
-//#region src/server/agents/AIChatAgent.d.ts
-interface AIChatAgentEnv {
-  AGENT_DB: D1Database;
+//#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/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 & AIChatAgentEnv = Cloudflare.Env & AIChatAgentEnv> 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.
    *
@@ -72,7 +133,7 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env & AIChatAgentEnv =
    * To disable compaction for a specific call, pass `maxMessagesBeforeCompaction: undefined`
    * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
    */
-  protected abstract fastModel: LanguageModel;
+  protected abstract getFastModel(): LanguageModel;
   /**
    * Number of days of inactivity before the full conversation is deleted.
    *
@@ -96,47 +157,46 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env & AIChatAgentEnv =
    * 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.
+   * Called automatically at the end of each LLM turn (from `onFinish` in
+   * `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
+   * `execute` functions.
    */
-  protected log(message: string, payload?: Record<string, unknown>): Promise<void>;
+  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 setting `maxMessagesBeforeCompaction` on the class. Disable compaction
    * entirely by setting `maxMessagesBeforeCompaction = undefined` explicitly.
-   * ```
    */
   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.
+   * 2. Strips all activate_skill and list_capabilities messages from history.
    *
-   * 3. 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 `persistMessages` after every turn.
+   * 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
@@ -145,25 +205,43 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env & AIChatAgentEnv =
    * over). Neither path blocks the response to the client.
    */
   private recordConversation;
-  private deleteConversation;
+  private deleteConversationCallback;
   private scheduleConversationForDeletion;
-  private clearConversationMemoryState;
 }
 //#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 };