@economic/agents 2.3.19 → 2.3.20

package/dist/index.d.mts

@@ -114,6 +114,21 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    * cold start, so registration is not allowed to block the connection.
    */
   protected registerInstance(): Promise<void>;
+  /**
+   * The `(agent_name, durable_object_name)` key of the registered row for this
+   * DO. For a parented (facet) agent this resolves to the top-level parent's
+   * row, since facets are not registered themselves.
+   */
+  protected getRegisteredInstanceKey(): {
+    agentName: string;
+    durableObjectName: string;
+  };
+  /**
+   * Records activity against this DO's registered row by advancing its
+   * `updated_at`, so instances can be ordered by recency of activity.
+   * Best-effort and non-blocking — never allowed to interfere with a turn.
+   */
+  protected touchInstance(): Promise<void>;
   /**
    * Resolves the analytics/telemetry agent name to the entry-point agent: the
    * top-level DO registered in the `agent` catalog table.
@@ -249,6 +264,13 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
    * Best-effort and idempotent: no-ops on conflict, retried on the next start.
    */
   private registerInstance;
+  /**
+   * Records activity against this Assistant's registry row by advancing its
+   * `updated_at`, so instances can be ordered by recency of activity. An
+   * Assistant is a top-level DO, so its row is keyed by its own class + name.
+   * Best-effort and non-blocking.
+   */
+  private touchInstance;
   /**
    * 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

package/dist/index.mjs

@@ -28,12 +28,31 @@ const TURN_PROTOCOL_RULES_PROMPT = `These rules are specific for responding to u
 * 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.
+* across cold starts no-op and timestamps reflect the first registration.
+* `updated_at` is seeded to `created_at`; ongoing activity is recorded
+* separately via {@link touchAgentInstance} so cold-start re-registration
+* never inflates the activity timestamp.
 */
 async function registerAgentInstance(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();
+	await db.prepare(`INSERT INTO agent_registry (agent_name, durable_object_name, actor_id, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT (agent_name, durable_object_name) DO NOTHING`).bind(input.agentName, input.durableObjectName, input.actorId, input.createdAt, input.createdAt).run();
+}
+/**
+* Records activity on a registered top-level DO by advancing its `updated_at`.
+*
+* Used to order instances by recency of activity. Keyed on
+* `(agent_name, durable_object_name)` to target the exact registered row —
+* for a parented (facet) agent this is the top-level parent's row, since
+* facets are not registered themselves.
+*
+* Best-effort: a no-op if the row does not yet exist (registration is
+* retried on the next cold start).
+*/
+async function touchAgentInstance(db, input) {
+	await db.prepare(`UPDATE agent_registry
+       SET updated_at = ?
+       WHERE agent_name = ? AND durable_object_name = ?`).bind(input.updatedAt, input.agentName, input.durableObjectName).run();
 }
 //#endregion
 //#region src/server/util/agent.ts
@@ -172,6 +191,7 @@ var Agent = class extends Think {
 	* `returned.tools` into your own `TurnConfig.tools` if you return tools.
 	*/
 	async beforeTurn(ctx) {
+		this.touchInstance();
 		this._toolContextForCurrentTurn = this.getToolContextForCurrentTurn(ctx.body);
 		this._toolsForCurrentTurn = ctx.tools;
 		const activeSkillName = this._getLastActivatedSkillName(ctx.messages);
@@ -313,6 +333,32 @@ var Agent = class extends Think {
 		}
 	}
 	/**
+	* The `(agent_name, durable_object_name)` key of the registered row for this
+	* DO. For a parented (facet) agent this resolves to the top-level parent's
+	* row, since facets are not registered themselves.
+	*/
+	getRegisteredInstanceKey() {
+		return {
+			agentName: this.parentPath[0]?.className ?? this.constructor.name,
+			durableObjectName: this.parentPath[0]?.name ?? this.name
+		};
+	}
+	/**
+	* Records activity against this DO's registered row by advancing its
+	* `updated_at`, so instances can be ordered by recency of activity.
+	* Best-effort and non-blocking — never allowed to interfere with a turn.
+	*/
+	async touchInstance() {
+		try {
+			await touchAgentInstance(this.env.AGENTS_DB, {
+				...this.getRegisteredInstanceKey(),
+				updatedAt: Date.now()
+			});
+		} catch (error) {
+			console.error("[Agent] Failed to update agent_registry activity", error);
+		}
+	}
+	/**
 	* Resolves the analytics/telemetry agent name to the entry-point agent: the
 	* top-level DO registered in the `agent` catalog table.
 	*
@@ -718,6 +764,7 @@ var Assistant = class extends Agent$1 {
 		const now = Date.now();
 		await this.subAgent(this.agent, id);
 		registerChat(this.sql.bind(this), id, now);
+		this.touchInstance(now);
 		return id;
 	}
 	async deleteChat(id) {
@@ -762,6 +809,23 @@ var Assistant = class extends Agent$1 {
 		}
 	}
 	/**
+	* Records activity against this Assistant's registry row by advancing its
+	* `updated_at`, so instances can be ordered by recency of activity. An
+	* Assistant is a top-level DO, so its row is keyed by its own class + name.
+	* Best-effort and non-blocking.
+	*/
+	async touchInstance(updatedAt) {
+		try {
+			await touchAgentInstance(this.env.AGENTS_DB, {
+				agentName: this.constructor.name,
+				durableObjectName: this.name,
+				updatedAt
+			});
+		} catch (error) {
+			console.error("[Assistant] Failed to update agent_registry activity", error);
+		}
+	}
+	/**
 	* 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.3.19",
+  "version": "2.3.20",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [

package/schema/0002_agent_registry_updated_at.sql

@@ -0,0 +1,13 @@
+-- ─── agent_registry.updated_at ────────────────────────────────────────────────────
+-- Adds an activity timestamp to the registry so top-level DOs (one row per
+-- Assistant, i.e. per user) can be ordered by recency of activity. Bumped by
+-- the owning DO whenever a chat is created or has a turn.
+--
+-- Existing rows are backfilled to created_at so ordering remains sensible
+-- before any new activity updates the column.
+
+ALTER TABLE agent_registry ADD COLUMN updated_at INTEGER;
+
+UPDATE agent_registry SET updated_at = created_at WHERE updated_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS agent_registry_updated ON agent_registry(updated_at);