@economic/agents 2.2.1 → 2.2.2

package/README.md

@@ -92,6 +92,14 @@ export default {
   },
   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SupportAgent"] }],
   // see "Bindings"
+  "d1_databases": [
+    {
+      "binding": "AGENTS_DB",
+      "database_name": "agents",
+      "database_id": "agents",
+      "migrations_dir": "node_modules/@economic/agents/schema",
+    },
+  ],
   "r2_buckets": [{ "binding": "AGENTS_AUDIT_LOGS", "bucket_name": "agents-audit-logs" }],
   "analytics_engine_datasets": [{ "binding": "AGENTS_ANALYTICS", "dataset": "agents-analytics" }],
 }

package/dist/index.d.mts

@@ -13,10 +13,11 @@ type ToolContext<RequestContext extends Record<string, unknown> = Record<string,
   _userContext?: UserContext;
 };
 interface AgentEnv {
-  AGENT_DB: D1Database;
+  AGENTS_DB: D1Database;
   AGENTS_AUDIT_LOGS: R2Bucket;
   AGENTS_ANALYTICS: AnalyticsEngineDataset;
   SKILLS_BUCKET: R2Bucket;
+  LOCAL_AGENT_DB?: D1Database;
 }
 type SqlFn = InstanceType<typeof Agent$1>["sql"];
 type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized";
@@ -57,10 +58,10 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
   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>;
+  configureSession(session: Session): Session;
   /**
    * Merges the client request `body` into `experimental_context` for tools
    * returned from {@link getTools} only (Think-internal tools are unchanged).
@@ -116,6 +117,16 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    * @param jwtToken - A valid JWT token following authentication.
    */
   protected getUserContext?(jwtToken: string): Promise<UserContext>;
+  /**
+   * Self-registers this DO in the global `agent_registry`. Only top-level DOs
+   * are registered — facets are enumerable via their parent's own index, so
+   * registering them would explode the row count and duplicate that index.
+   *
+   * Best-effort and idempotent: called once per cold start from `onStart`, the
+   * insert no-ops on conflict. A failed write is simply retried on the next
+   * cold start, so registration is not allowed to block the connection.
+   */
+  protected registerInstance(): Promise<void>;
 }
 //#endregion
 //#region src/server/features/messages.d.ts
@@ -152,9 +163,7 @@ 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. */
+  durableObjectBinding: DurableObjectNamespace; /** Creates (or resolves) a v2 chat facet for the given chat id and returns its stub. */
   createFacet: (chatId: string) => Promise<FacetStub>;
 };
 /**
@@ -221,22 +230,25 @@ type Chat = {
 declare const DELETE_CHAT_CALLBACK: "deleteChatCallback";
 //#endregion
 //#region src/server/agents/Assistant.d.ts
-declare abstract class Assistant extends Agent$1<Cloudflare.Env, AgentConnectionState> {
+declare abstract class Assistant extends Agent$1<Cloudflare.Env & AgentEnv, AgentConnectionState> {
   initialState: AgentConnectionState;
   protected abstract agent: SubAgentClass<ChatAgent>;
   protected abstract fastModel: LanguageModel;
+  onStart(): void;
+  onClose(): Promise<void>;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
-   * Binding name of the legacy v1 chat Durable Object class, used to migrate a
+   * Binding 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;
+  protected migrationBinding?: {
+    binding: DurableObjectNamespace;
+    db: D1Database;
+  };
   /** 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
@@ -251,6 +263,15 @@ declare abstract class Assistant extends Agent$1<Cloudflare.Env, AgentConnection
   recordChatTurn(durableObjectName: string, messages: UIMessage[]): Promise<void>;
   private [DELETE_CHAT_CALLBACK];
   private scheduleChatForAutoDeletion;
+  /**
+   * Self-registers this Assistant in the global `agent_registry`. An Assistant
+   * is a top-level DO keyed directly by user id, so the DO name *is* the actor.
+   *
+   * Runs pre-auth in onStart (the DO has already persisted state by this point,
+   * so it must be tracked regardless of whether auth later succeeds).
+   * Best-effort and idempotent: no-ops on conflict, retried on the next start.
+   */
+  private registerInstance;
 }
 //#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, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -42,6 +42,19 @@ var LocalSkillProvider = class {
 	}
 };
 //#endregion
+//#region src/server/features/registry.ts
+/**
+* Registers a top-level DO in the global registry.
+*
+* Idempotent: keyed on `(agent_name, durable_object_name)`, so repeated calls
+* across cold starts no-op and `created_at` reflects the first registration.
+*/
+async function registerAgent(db, input) {
+	await db.prepare(`INSERT INTO agent_registry (agent_name, durable_object_name, actor_id, created_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (agent_name, durable_object_name) DO NOTHING`).bind(input.agentName, input.durableObjectName, input.actorId, input.createdAt).run();
+}
+//#endregion
 //#region src/server/agents/Agent.ts
 function getCurrentToolContext() {
 	return getCurrentAgent().agent._lastBody;
@@ -66,26 +79,16 @@ var Agent = class extends Think {
 			if (parent) return this.env[parent.className]?.getByName(parent.name);
 		}
 	}
-	configureSession(session) {
-		let configuredSession = session.withContext("soul", { provider: { get: async () => {
-			return this.getSystemPrompt(this._requestContext !== void 0 ? this._buildToolContext() : void 0);
-		} } }).withContext("critical-rules", { provider: { get: async () => SECURITY_RULES_PROMPT } }).withContext("turn-protocol-rules", { provider: { get: async () => TURN_PROTOCOL_RULES_PROMPT } });
-		const remoteSkills = this.getRemoteSkills();
-		if (remoteSkills.length) if (this.env.SKILLS_BUCKET) configuredSession = configuredSession.withContext("skills", { provider: new R2SkillProvider(this.env.SKILLS_BUCKET, {
-			prefix: "skills/",
-			keys: remoteSkills
-		}) });
-		else console.error("[Agent] Connection rejected: Remote skills defined, but no SKILLS_BUCKET R2 binding found");
-		const localSkills = this.getSkills();
-		if (localSkills.length) configuredSession = configuredSession.withContext("local-skills", { provider: new LocalSkillProvider(localSkills) });
-		return configuredSession.withCachedPrompt();
-	}
 	async onStart() {
 		this.setState({
 			...this.initialState,
 			status: "connecting"
 		});
 		let hasCorrectBindings = true;
+		if (!this.env.AGENTS_DB) {
+			hasCorrectBindings = false;
+			console.warn("[Agent] Connection rejected: no AGENTS_DB bound. Agents database is required for registration.");
+		}
 		if (!this.env.AGENTS_AUDIT_LOGS) {
 			hasCorrectBindings = false;
 			console.error("[Agent] Connection rejected: no AGENTS_AUDIT_LOGS bound. Audit logs are required.");
@@ -98,6 +101,7 @@ var Agent = class extends Think {
 			});
 			throw new Error("Could not connect to agent, bindings not found");
 		}
+		this.registerInstance();
 	}
 	async onClose() {
 		this.setState({
@@ -148,6 +152,20 @@ var Agent = class extends Think {
 			status: "connected"
 		});
 	}
+	configureSession(session) {
+		let configuredSession = session.withContext("soul", { provider: { get: async () => {
+			return this.getSystemPrompt(this._requestContext !== void 0 ? this._buildToolContext() : void 0);
+		} } }).withContext("critical-rules", { provider: { get: async () => SECURITY_RULES_PROMPT } }).withContext("turn-protocol-rules", { provider: { get: async () => TURN_PROTOCOL_RULES_PROMPT } });
+		const remoteSkills = this.getRemoteSkills();
+		if (remoteSkills.length) if (this.env.SKILLS_BUCKET) configuredSession = configuredSession.withContext("skills", { provider: new R2SkillProvider(this.env.SKILLS_BUCKET, {
+			prefix: "skills/",
+			keys: remoteSkills
+		}) });
+		else console.error("[Agent] Connection rejected: Remote skills defined, but no SKILLS_BUCKET R2 binding found");
+		const localSkills = this.getSkills();
+		if (localSkills.length) configuredSession = configuredSession.withContext("local-skills", { provider: new LocalSkillProvider(localSkills) });
+		return configuredSession.withCachedPrompt();
+	}
 	/**
 	* Merges the client request `body` into `experimental_context` for tools
 	* returned from {@link getTools} only (Think-internal tools are unchanged).
@@ -268,6 +286,28 @@ var Agent = class extends Think {
 	* Define getUserContext to set a user context.
 	*/
 	_userContext;
+	/**
+	* Self-registers this DO in the global `agent_registry`. Only top-level DOs
+	* are registered — facets are enumerable via their parent's own index, so
+	* registering them would explode the row count and duplicate that index.
+	*
+	* Best-effort and idempotent: called once per cold start from `onStart`, the
+	* insert no-ops on conflict. A failed write is simply retried on the next
+	* cold start, so registration is not allowed to block the connection.
+	*/
+	async registerInstance() {
+		if (this.parentPath.length > 0) return;
+		try {
+			await registerAgent(this.env.AGENTS_DB, {
+				agentName: this.constructor.name,
+				durableObjectName: this.name,
+				actorId: this.getActorIdFromDurableObjectName(),
+				createdAt: Date.now()
+			});
+		} catch (error) {
+			console.error("[Agent] Failed to register in agent_registry", error);
+		}
+	}
 };
 //#endregion
 //#region src/server/features/chats.ts
@@ -423,14 +463,14 @@ function toEpochMs(value) {
 * remain as a backstop until then.
 */
 async function migrateUserFromV1(deps) {
-	const { sql, db, userId, legacyNamespace, createFacet } = deps;
+	const { sql, db, userId, durableObjectBinding, createFacet } = deps;
 	const conversations = await listLegacyConversations(db, userId);
 	let migrated = 0;
 	let failed = 0;
 	for (const conversation of conversations) {
 		const legacyName = conversation.durable_object_name;
 		try {
-			const { messages } = await legacyNamespace.getByName(legacyName).exportForMigration();
+			const { messages } = await durableObjectBinding.getByName(legacyName).exportForMigration();
 			const feedback = await listLegacyFeedback(db, legacyName);
 			const newChatId = nanoid();
 			const facet = await createFacet(newChatId);
@@ -463,15 +503,6 @@ var Assistant = class extends Agent$1 {
 		status: "connecting",
 		type: "assistant"
 	};
-	/**
-	* 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).
-	*/
-	legacyBinding;
-	/** In-flight migration, shared across concurrent connections to this DO. */
-	_migrationPromise;
 	onStart() {
 		this.setState({
 			...this.initialState,
@@ -479,6 +510,19 @@ var Assistant = class extends Agent$1 {
 			subAgentName: this.agent.name
 		});
 		ensureChatsTableExists(this.sql.bind(this));
+		let hasCorrectBindings = true;
+		if (!this.env.AGENTS_DB) {
+			hasCorrectBindings = false;
+			console.warn("[Agent] Connection rejected: no AGENTS_DB bound. Agents database is required for registration.");
+		}
+		if (!hasCorrectBindings) {
+			this.setState({
+				...this.initialState,
+				status: "disconnected"
+			});
+			throw new Error("Could not connect to agent, bindings not found");
+		}
+		this.registerInstance();
 	}
 	async onClose() {
 		this.setState({
@@ -529,30 +573,35 @@ var Assistant = class extends Agent$1 {
 		});
 	}
 	/**
+	* Binding 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).
+	*/
+	migrationBinding;
+	/** In-flight migration, shared across concurrent connections to this DO. */
+	_migrationPromise;
+	/**
 	* 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.
 	*/
 	async ensureMigrated() {
-		if (!this.legacyBinding) return;
+		if (!this.migrationBinding) return;
 		this._migrationPromise ??= this.runMigration().finally(() => {
 			this._migrationPromise = void 0;
 		});
 		await this._migrationPromise;
 	}
 	async runMigration() {
-		const legacyNamespace = this.env[this.legacyBinding];
-		if (!legacyNamespace?.getByName) {
-			console.error("[Assistant] Migration skipped: legacy binding not found", { legacyBinding: this.legacyBinding });
-			return;
-		}
+		if (!this.migrationBinding) return;
 		try {
 			const result = await migrateUserFromV1({
 				sql: this.sql.bind(this),
-				db: this.env.AGENT_DB,
+				db: this.migrationBinding.db,
 				userId: this.name,
-				legacyNamespace,
+				durableObjectBinding: this.migrationBinding.binding,
 				createFacet: async (chatId) => {
 					return await this.subAgent(this.agent, chatId);
 				}
@@ -596,6 +645,26 @@ var Assistant = class extends Agent$1 {
 		await Promise.all(scheduleIds.map((scheduleId) => this.cancelSchedule(scheduleId)));
 		await this.schedule(new Date(Date.now() + retentionMs), DELETE_CHAT_CALLBACK, durableObjectName, { idempotent: true });
 	}
+	/**
+	* Self-registers this Assistant in the global `agent_registry`. An Assistant
+	* is a top-level DO keyed directly by user id, so the DO name *is* the actor.
+	*
+	* Runs pre-auth in onStart (the DO has already persisted state by this point,
+	* so it must be tracked regardless of whether auth later succeeds).
+	* Best-effort and idempotent: no-ops on conflict, retried on the next start.
+	*/
+	async registerInstance() {
+		try {
+			await registerAgent(this.env.AGENTS_DB, {
+				agentName: this.constructor.name,
+				durableObjectName: this.name,
+				actorId: this.name,
+				createdAt: Date.now()
+			});
+		} catch (error) {
+			console.error("[Assistant] Failed to register in agent_registry", error);
+		}
+	}
 };
 //#endregion
 //#region src/server/features/messages.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "bin": {

package/schema/0001_v2_release.sql

@@ -0,0 +1,18 @@
+-- ─── Agents registry ────────────────────────────────────────────────────────────
+-- A directory of every top-level Durable Object in the system. DOs cannot be
+-- enumerated via the runtime, so each top-level DO self-registers here on
+-- creation (facets are omitted — they are enumerable via their parent's own
+-- index). Source of truth for "what exists" and "all DOs for a given user".
+-- Distinct from the audit/analytics event stream, which records "what happened".
+
+CREATE TABLE IF NOT EXISTS agent_registry (
+  agent_name            TEXT NOT NULL,
+  durable_object_name   TEXT NOT NULL,
+  actor_id              TEXT NOT NULL,
+  created_at            INTEGER NOT NULL,
+
+  PRIMARY KEY (agent_name, durable_object_name)
+);
+
+CREATE INDEX IF NOT EXISTS agent_registry_actor ON agent_registry(actor_id);
+CREATE INDEX IF NOT EXISTS agent_registry_class ON agent_registry(agent_name);

package/schema/agent/0001_initial.sql

@@ -1,12 +0,0 @@
--- ─── Audit logging ────────────────────────────────────────────────────────────
-
-CREATE TABLE IF NOT EXISTS audit_events (
-  id                  TEXT PRIMARY KEY,
-  durable_object_name TEXT NOT NULL,
-  message             TEXT NOT NULL,
-  payload             TEXT,
-  created_at          TEXT NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS audit_events_do   ON audit_events(durable_object_name);
-CREATE INDEX IF NOT EXISTS audit_events_ts   ON audit_events(created_at);