@economic/agents 2.1.6 → 2.2.0

package/dist/v1.d.mts

@@ -0,0 +1,278 @@
+import { t as JwtAuthConfig } from "./index-DzOC3mNl.mjs";
+import { LanguageModel, StreamTextOnFinishCallback, ToolSet, UIMessage, generateText, streamText } from "ai";
+import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext } from "agents";
+import { AIChatAgent, ChatResponseResult, OnChatMessageOptions } from "@cloudflare/ai-chat";
+
+//#region src/server/shared/features/skills/index.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.
+ */
+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 into the `## Tools` section of the
+   * system prompt via `buildSystemPrompt` in `llm.ts` whenever this skill
+   * is loaded.
+   */
+  guidance?: string;
+  tools: ToolSet;
+}
+//#endregion
+//#region src/server/shared/util/llm.d.ts
+type LLMParams = Parameters<typeof streamText>[0] & Parameters<typeof generateText>[0];
+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[];
+};
+/**
+ * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
+ *
+ * Handles skill wiring (`activate_skill`, `list_capabilities`, `prepareStep`).
+ *
+ * The returned object can be spread directly into `streamText` or `generateText`:
+ *
+ * ```typescript
+ * const params = buildLLMParams({ ... });
+ * return streamText(params).toUIMessageStreamResponse();
+ * ```
+ */
+declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
+//#endregion
+//#region src/server/v1/types.d.ts
+/**
+ * The context object available throughout an agent's lifetime — passed via
+ * `experimental_context` to tool `execute` functions.
+ *
+ * Define your own body shape and compose:
+ * ```typescript
+ * interface MyBody { userTier: "free" | "pro" }
+ * type MyContext = AgentToolContext<MyBody>;
+ * ```
+ */
+type AgentToolContext<TBody = Record<string, unknown>, TUserContext = Record<string, unknown> | undefined> = TBody & {
+  _userContext?: TUserContext;
+};
+interface AgentEnv {
+  AGENT_DB: D1Database;
+  AGENTS_AUDIT_LOGS: R2Bucket;
+  AGENTS_ANALYTICS: AnalyticsEngineDataset;
+}
+interface ChatAgentEnv extends AgentEnv {}
+//#endregion
+//#region src/server/v1/route-agent-request.d.ts
+declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
+//#endregion
+//#region src/server/v1/agent/Agent.d.ts
+/**
+ * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading
+ * and `buildLLMParams` wiring.
+ *
+ * Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state.
+ *
+ * For chat agents with message history, compaction, and conversation recording,
+ * extend {@link ChatAgent} instead.
+ */
+declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env, TUserContext extends Record<string, unknown> = Record<string, unknown>> extends Agent$1<Env & AgentEnv> {
+  protected clientIp?: string;
+  protected forwardedFor?: string;
+  /**
+   * Override to enable JWT authentication on WebSocket connections.
+   * Return the auth config based on the incoming request, or undefined to skip auth.
+   *
+   * @param request - The WebSocket upgrade request
+   * @returns JWT auth config or undefined to skip authentication
+   */
+  protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
+  /**
+   * The user context for the session.
+   * Define getUserContext to set a user context.
+   */
+  protected get userContext(): TUserContext;
+  /**
+   * Returns the identity following verification of the JWT token - getJwtAuthConfig is required.
+   * This method should not have side effects - return a single object from it.
+   * @returns The user context from the request.
+   * @param jwtToken - A valid JWT token following authentication.
+   */
+  protected getUserContext?(jwtToken: string): Promise<TUserContext>;
+  /**
+   * Returns the user ID from the durable object name.
+   */
+  protected getUserId(): string;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  /**
+   * Builds the parameter object for a `streamText` or `generateText` call,
+   * pre-filling `activeSkills` from this agent instance.
+   */
+  protected buildLLMParams<TBody = Record<string, unknown>>(config: Omit<BuildLLMParamsConfig, "messages"> & {
+    options?: OnChatMessageOptions;
+  }): Promise<LLMParams>;
+}
+//#endregion
+//#region src/server/v1/agent-chat/features/conversations/rating.d.ts
+interface MessageRating {
+  rating: number;
+  comment?: string;
+}
+//#endregion
+//#region src/server/v1/agent-chat/ChatAgent.d.ts
+/**
+ * Chat agent for Cloudflare Agents SDK: lazy skill loading, message persistence,
+ * compaction, and conversation metadata in D1.
+ *
+ * Handles CF infrastructure concerns: DO SQLite for loaded skill state,
+ * stripping skill meta-tool messages before persistence, and history replay to
+ * newly connected clients.
+ *
+ * Skill loading, compaction, and LLM calls use `buildLLMParams` from
+ * `@economic/agents` inside `onChatMessage`.
+ */
+declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TUserContext extends Record<string, unknown> = Record<string, unknown>> extends AIChatAgent<Env & ChatAgentEnv> {
+  initialState: {
+    status: string;
+    type: string;
+  };
+  /**
+   * 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.
+   *
+   * Declare this on every subclass:
+   *
+   * ```typescript
+   * protected fastModel = google("gemini-2.0-flash");
+   * ```
+   *
+   * To disable compaction for a specific call, pass `maxMessagesBeforeCompaction: undefined`
+   * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
+   */
+  protected abstract getFastModel(): LanguageModel;
+  /**
+   * Number of days of inactivity before the full conversation is deleted.
+   *
+   * Leave `undefined` to disable automatic retention cleanup.
+   */
+  protected conversationRetentionDays?: number;
+  /**
+   * 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.
+   */
+  protected maxMessagesBeforeCompaction?: number | undefined;
+  protected clientIp?: string;
+  protected forwardedFor?: string;
+  /**
+   * Override to enable JWT authentication on WebSocket connections.
+   * Return the auth config based on the incoming request, or undefined to skip auth.
+   *
+   * @param request - The WebSocket upgrade request
+   * @returns JWT auth config or undefined to skip authentication
+   */
+  protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
+  /**
+   * The user context for the session.
+   * Define getUserContext to set a user context.
+   */
+  protected get userContext(): TUserContext;
+  /**
+   * Returns the identity following verification of the JWT token - getJwtAuthConfig is required.
+   * This method should not have side effects - return a single object from it.
+   * @returns The user context from the request.
+   * @param jwtToken - A valid JWT token following authentication.
+   */
+  protected getUserContext?(jwtToken: string): Promise<TUserContext>;
+  /**
+   * Returns the user ID from the durable object name.
+   */
+  protected getUserId(): string;
+  onStart(): void;
+  onClose(): Promise<void>;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  protected _pendingUserContextRequest?: Promise<void>;
+  /**
+   * Builds the parameter object for a `streamText` or `generateText` call,
+   * pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
+   *
+   * **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>;
+  persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
+    _deleteStaleRows?: boolean;
+  }): Promise<void>;
+  protected onChatResponse(result: ChatResponseResult): Promise<void>;
+  rateMessage(messageId: string, rating: number, comment?: string): Promise<void>;
+  getMessageRatings(): Promise<Record<string, MessageRating>>;
+  getConversations(): Promise<Record<string, unknown>[]>;
+  /**
+   * Exports this conversation's persisted message history for the v1 -> v2
+   * migration. Called over DO RPC by the v2 `Assistant` while migrating a
+   * user's chats into facets. `this.messages` is loaded from the
+   * `cf_ai_chat_agent_messages` table when the DO wakes.
+   *
+   * Read-only: does not mutate or delete any state.
+   */
+  exportForMigration(): Promise<{
+    messages: UIMessage[];
+  }>;
+  deleteConversation(id: string): Promise<boolean>;
+  destroy(): Promise<void>;
+  private deleteConversationCallback;
+  private scheduleConversationForAutoDeletion;
+}
+//#endregion
+//#region src/server/v1/agent-chat/ChatAgentHarness.d.ts
+declare abstract class ChatAgentHarness<Env extends Cloudflare.Env, RequestBody extends Record<string, unknown> = Record<string, unknown>, SessionIdentity extends Record<string, unknown> = Record<string, unknown>> extends ChatAgent<Env, SessionIdentity> {
+  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 { Agent, type AgentToolContext, type BuildLLMParamsConfig, ChatAgent, ChatAgentHarness, type Skill, buildLLMParams, routeAgentRequest };