@economic/agents 2.1.7 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "bin": {
@@ -15,7 +15,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./cli": "./dist/cli.mjs",
-    "./v2": "./dist/v2.mjs",
+    "./v1": "./dist/v1.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {

package/dist/v2.d.mts

@@ -1,256 +0,0 @@
-import { t as JwtAuthConfig } from "./index-DzOC3mNl.mjs";
-import { JSONValue, LanguageModel, Tool as Tool$1, UIMessage } from "ai";
-import { Agent as Agent$1, Connection, ConnectionContext, SubAgentClass } from "agents";
-import { ChatResponseResult, Session, StepConfig, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext } from "@cloudflare/think";
-//#region src/server/v2/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`.ext = AgentToolContext<MyBody>;
- * ```
- */
-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;
-}
-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/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/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;
-  /**
-   * Returns the user ID from the durable object name.
-   */
-  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>;
-  /**
-   * 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.
-   */
-  beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
-  /**
-   * Sets active tools based on skills that might be loaded in the current turn.
-   *
-   * @param ctx - The prepare step context.
-   * @returns The step config.
-   */
-  beforeStep(): Promise<StepConfig | void>;
-  beforeToolCall(ctx: ToolCallContext): Promise<ToolCallDecision | void>;
-  private _buildToolContext;
-  getTools(): ToolSet;
-  /**
-   * Returns the remote skills to be loaded from SKILLS_BUCKET.
-   * @returns The remote skills to be loaded from SKILLS_BUCKET.
-   */
-  protected getRemoteSkills(): string[];
-  /**
-   * Returns the skills to load for the agent.
-   * @returns The skills to load for the agent.
-   */
-  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 env - The worker environment variables
-   * @returns JWT auth config or undefined to skip authentication
-   */
-  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.
-   */
-  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<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[];
-  }>;
-}
-/** 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/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>;
-  /**
-   * 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.
-   */
-  submitMessageFeedback(messageId: string, rating: number, comment?: string): Promise<void>;
-  /**
-   * Returns all message feedback for the current chat.
-   * @returns All message feedback for the current chat.
-   */
-  getMessageFeedback(): Promise<Record<string, MessageFeedback>>;
-  /**
-   * 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.
-   */
-  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>;
-  /**
-   * 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.
-   */
-  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 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 };