@economic/agents 2.1.6 → 2.2.0

package/dist/index.d.mts

@@ -1,278 +1,256 @@
 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
+import { ChatResponseResult, Session, StepConfig, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext } from "@cloudflare/think";
+import { JSONValue, LanguageModel, Tool as Tool$1, UIMessage } from "ai";
+import { Agent as Agent$1, Connection, ConnectionContext, SubAgentClass } from "agents";
+//#region src/server/v2/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>;
+ * `experimental_context` to tool `execute` functions. Contains the typed
+ * request body merged with platform capabilities like `logEvent`.ext = AgentToolContext<MyBody>;
  * ```
  */
-type AgentToolContext<TBody = Record<string, unknown>, TUserContext = Record<string, unknown> | undefined> = TBody & {
-  _userContext?: TUserContext;
+type ToolContext<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext = Record<string, unknown> | undefined> = RequestContext & {
+  _userContext?: UserContext;
 };
 interface AgentEnv {
   AGENT_DB: D1Database;
   AGENTS_AUDIT_LOGS: R2Bucket;
   AGENTS_ANALYTICS: AnalyticsEngineDataset;
+  SKILLS_BUCKET: R2Bucket;
 }
-interface ChatAgentEnv extends AgentEnv {}
+type SqlFn = InstanceType<typeof Agent$1>["sql"];
+type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized";
+type AgentConnectionType = "agent" | "chat" | "assistant";
+type AgentConnectionState = {
+  status: AgentConnectionStatus;
+  type: AgentConnectionType; /** Set by `Assistant` so clients can derive the sub-agent routing name from state. */
+  subAgentName?: string;
+};
 //#endregion
-//#region src/server/v1/route-agent-request.d.ts
-declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
+//#region src/server/v2/util/tools.d.ts
+type ToolSet = Record<string, Tool>;
+type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = Tool$1<INPUT, OUTPUT> & {
+  authorize?: (ctx: Context) => boolean;
+};
+declare function tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any>(tool: Tool<Context, INPUT, OUTPUT>): Tool$1<INPUT, OUTPUT>;
 //#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> {
+//#region src/server/v2/util/skills.d.ts
+interface Skill<Context extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  description: string;
+  instructions: string;
+  tools?: Record<string, Tool<Context>>;
+  authorize?: (ctx: Context) => boolean;
+}
+declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): Skill<Context>;
+//#endregion
+//#region src/server/v2/agents/Agent.d.ts
+declare function getCurrentToolContext(): any;
+declare abstract class Agent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>> extends Think<Cloudflare.Env & AgentEnv, AgentConnectionState> {
+  initialState: AgentConnectionState;
   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;
+  protected getActorIdFromDurableObjectName(): string;
+  protected getParentAgent<T extends Agent$1>(): T | undefined;
+  abstract getModel(ctx?: ToolContext<RequestContext, UserContext>): LanguageModel;
+  abstract getSystemPrompt(ctx?: ToolContext<RequestContext, UserContext>): string;
+  configureSession(session: Session): Session;
+  onStart(): Promise<void>;
+  onClose(): Promise<void>;
   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.
+   * Merges the client request `body` into `experimental_context` for tools
+   * returned from {@link getTools} only (Think-internal tools are unchanged).
+   *
+   * If you override `beforeTurn`, call `super.beforeTurn(ctx)` and merge
+   * `returned.tools` into your own `TurnConfig.tools` if you return tools.
    */
-  protected abstract get binding(): {
-    getByName(name: string): {
-      destroy(): Promise<void>;
-    };
-  };
+  beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
   /**
-   * Fast/cheap language model used for background tasks: compaction and conversation summarization.
-   *
-   * Declare this on every subclass:
+   * Sets active tools based on skills that might be loaded in the current turn.
    *
-   * ```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`.
+   * @param ctx - The prepare step context.
+   * @returns The step config.
    */
-  protected abstract getFastModel(): LanguageModel;
+  beforeStep(): Promise<StepConfig | void>;
+  beforeToolCall(ctx: ToolCallContext): Promise<ToolCallDecision | void>;
+  private _buildToolContext;
+  getTools(): ToolSet;
   /**
-   * Number of days of inactivity before the full conversation is deleted.
-   *
-   * Leave `undefined` to disable automatic retention cleanup.
+   * Returns the remote skills to be loaded from SKILLS_BUCKET.
+   * @returns The remote skills to be loaded from SKILLS_BUCKET.
    */
-  protected conversationRetentionDays?: number;
+  protected getRemoteSkills(): string[];
   /**
-   * 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.
+   * Returns the skills to load for the agent.
+   * @returns The skills to load for the agent.
    */
-  protected maxMessagesBeforeCompaction?: number | undefined;
-  protected clientIp?: string;
-  protected forwardedFor?: string;
+  protected getSkills(): Skill[];
+  private _getAuthorizedTools;
+  private _getAuthorizedSkills;
+  /** Store the pending user context request to defer awaiting it until after the connection is established */
+  private _requestContext?;
   /**
    * Override to enable JWT authentication on WebSocket connections.
    * Return the auth config based on the incoming request, or undefined to skip auth.
+   * Do not add side effects to this method - return a single JwtAuthConfig from it.
    *
-   * @param request - The WebSocket upgrade request
+   * @param env - The worker environment variables
    * @returns JWT auth config or undefined to skip authentication
    */
-  protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
+  static getJwtAuthConfig?(env: Cloudflare.Env): JwtAuthConfig<Record<string, unknown>> | undefined;
+  /** Store the pending user context request to defer awaiting it until after the connection is established */
+  private _pendingUserContextRequest?;
   /**
    * The user context for the session.
    * Define getUserContext to set a user context.
    */
-  protected get userContext(): TUserContext;
+  private _userContext?;
   /**
    * 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.
-   */
+  protected getUserContext?(jwtToken: string): Promise<UserContext>;
+}
+//#endregion
+//#region src/server/v2/features/messages.d.ts
+type MessageFeedback = {
+  message_id: string;
+  rating: number;
+  comment?: string;
+  created_at: number;
+  updated_at: number;
+};
+//#endregion
+//#region src/server/v2/features/migration.d.ts
+/** Per-message feedback carried over from a v1 conversation during migration. */
+type LegacyMessageFeedback = {
+  messageId: string;
+  rating: number;
+  comment?: string;
+};
+/** Minimal RPC surface of a v1 chat DO needed to read its history. */
+interface LegacyChatStub {
   exportForMigration(): Promise<{
     messages: UIMessage[];
   }>;
-  deleteConversation(id: string): Promise<boolean>;
-  destroy(): Promise<void>;
-  private deleteConversationCallback;
-  private scheduleConversationForAutoDeletion;
 }
+/** Minimal RPC surface of a freshly created v2 chat facet needed to seed history. */
+interface FacetStub {
+  importLegacyMessages(messages: UIMessage[], feedback: LegacyMessageFeedback[]): Promise<void>;
+}
+/**
+ * Dependencies for {@link migrateUserFromV1}, injected by the `Assistant` so
+ * this module never needs to touch the DO's protected members directly.
+ */
+type MigrationDeps = {
+  /** The `Assistant` DO's bound `sql` tag (used to register migrated chats). */sql: SqlFn; /** Shared D1 database holding v1 `conversations` and `message_ratings`. */
+  db: D1Database; /** The user being migrated (the `Assistant` DO name). */
+  userId: string; /** Resolves a v1 chat DO stub by its `userId:chatId` name. */
+  legacyNamespace: {
+    getByName(name: string): LegacyChatStub;
+  }; /** Creates (or resolves) a v2 chat facet for the given chat id and returns its stub. */
+  createFacet: (chatId: string) => Promise<FacetStub>;
+};
+/**
+ * Migrates all of a user's v1 chats into v2 facets, lazily and idempotently.
+ *
+ * v1 chats are enumerated from the shared D1 `conversations` table (DOs cannot
+ * be listed directly). For each chat we read its persisted messages from the v1
+ * DO over RPC, create a fresh facet, seed its history and feedback, register it
+ * on the parent `Assistant` with its original title/summary/timestamps, and
+ * finally delete the v1 `conversations` (+ `message_ratings`) rows.
+ *
+ * The conversations row IS the to-do marker: deleting it last means a migrated
+ * chat never reappears, while a chat that errored keeps its row and is simply
+ * retried on the next connection. No extra bookkeeping tables are needed. The
+ * v1 DO is left untouched and self-expires via v1 retention, so its messages
+ * remain as a backstop until then.
+ */
+declare function migrateUserFromV1(deps: MigrationDeps): Promise<{
+  migrated: number;
+  failed: number;
+}>;
 //#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;
+//#region src/server/v2/agents/ChatAgent.d.ts
+declare abstract class ChatAgent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>> extends Agent<RequestContext, UserContext> {
+  initialState: AgentConnectionState;
+  onStart(): Promise<void>;
+  configureSession(session: Session): Session;
+  onChatResponse(_result: ChatResponseResult): Promise<void>;
   /**
-   * 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.
+   * Submit feedback for a message by its id.
+   * @param messageId - The id of the message to give feedback on.
+   * @param rating - The rating to give the message. 1 = thumbs up, -1 = thumbs down.
+   * @returns The message id and the rating.
    */
-  abstract getModel(ctx: AgentToolContext<RequestBody>): LanguageModel;
+  submitMessageFeedback(messageId: string, rating: number, comment?: string): Promise<void>;
   /**
-   * 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.
+   * Returns all message feedback for the current chat.
+   * @returns All message feedback for the current chat.
    */
-  abstract getSystemPrompt(ctx: AgentToolContext<RequestBody>): string;
+  getMessageFeedback(): Promise<Record<string, MessageFeedback>>;
   /**
-   * 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.
+   * Imports a v1 conversation's history into this facet's session storage.
+   *
+   * Called over DO RPC by the v2 `Assistant` during the lazy v1 -> v2
+   * migration. Messages are appended in order as a single linear thread
+   * (each message parented to the previous one) using
+   * `appendMessageToHistory`, which writes durably to the session WITHOUT
+   * triggering a model turn. Any carried-over feedback is then written to
+   * `assistant_messages_feedback`.
+   *
+   * Safe to skip persisting if there is nothing to import.
    */
-  getTools(_ctx: AgentToolContext<RequestBody>): ToolSet;
+  importLegacyMessages(messages: UIMessage[], feedback?: LegacyMessageFeedback[]): Promise<void>;
+}
+//#endregion
+//#region src/server/v2/features/chats.d.ts
+type Chat = {
+  durable_object_name: string;
+  title?: string;
+  summary?: string;
+  created_at: number;
+  updated_at: number;
+};
+declare const DELETE_CHAT_CALLBACK: "deleteChatCallback";
+//#endregion
+//#region src/server/v2/agents/Assistant.d.ts
+declare abstract class Assistant extends Agent$1<Cloudflare.Env, AgentConnectionState> {
+  initialState: AgentConnectionState;
+  protected abstract agent: SubAgentClass<ChatAgent>;
+  protected abstract fastModel: LanguageModel;
+  /**
+   * Binding name of the legacy v1 chat Durable Object class, used to migrate a
+   * user's v1 chats into facets the first time they connect. Set this on the
+   * concrete subclass to enable lazy v1 -> v2 migration; leave undefined to
+   * disable it (e.g. for greenfield deployments with no v1 data).
+   */
+  protected legacyBinding?: keyof Cloudflare.Env;
+  /** In-flight migration, shared across concurrent connections to this DO. */
+  private _migrationPromise?;
+  onStart(): void;
+  onClose(): Promise<void>;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
-   * 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.
+   * Runs the lazy v1 -> v2 migration for this user. Concurrent connections to
+   * this DO share a single in-flight run. Idempotency across runs/restarts is
+   * handled by `migrateUserFromV1` deleting each chat's v1 `conversations` row,
+   * so an already-migrated chat is never re-enumerated.
    */
-  getSkills(_ctx: AgentToolContext<RequestBody>): Skill[];
-  onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response>;
+  private ensureMigrated;
+  private runMigration;
+  createChat(): Promise<string>;
+  deleteChat(id: string): Promise<void>;
+  getChats(): Promise<Chat[]>;
+  recordChatTurn(durableObjectName: string, messages: UIMessage[]): Promise<void>;
+  private [DELETE_CHAT_CALLBACK];
+  private scheduleChatForAutoDeletion;
 }
 //#endregion
-export { Agent, type AgentToolContext, type BuildLLMParamsConfig, ChatAgent, ChatAgentHarness, type Skill, buildLLMParams, routeAgentRequest };
+export { Agent, type AgentConnectionState, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type FacetStub, type LegacyChatStub, type LegacyMessageFeedback, type MigrationDeps, type Skill, type Tool, type ToolContext, type ToolSet, getCurrentToolContext, migrateUserFromV1, skill, tool };