@economic/agents 2.6.1 → 2.7.0

package/README.md

@@ -4,7 +4,7 @@ Our agents SDK for building AI agents on Cloudflare Workers. Each agent is a Dur
 
 React client: [`@economic/agents-react`](../react/README.md).
 
-> The v1 (`@economic/agents/v1`) API (`ChatAgentHarness`, `buildLLMParams`) is deprecated, kept only for migration, and will be removed in v3.
+> The v1 (`@economic/agents/v1`) API (`ChatAgentHarness`, `buildLLMParams`) is deprecated and will be removed in v3.
 
 ## The three classes
 
@@ -252,15 +252,17 @@ const { status, chats, assistant, chat } = useAssistant({
 });
 ```
 
-The `Assistant` keeps the chat list in its own SQLite (a `chats` table, created automatically) and exposes three callable methods:
+The `Assistant` keeps the chat list in its own SQLite (a `chats` table, created automatically) and exposes four callable methods. A newly created chat facet is added to this table when its first turn starts.
 
-| Method           | Returns  | Description                                    |
-| ---------------- | -------- | ---------------------------------------------- |
-| `createChat()`   | `string` | Creates a chat and returns its id.             |
-| `getChats()`     | `Chat[]` | The user's chats, most recently updated first. |
-| `deleteChat(id)` | `void`   | Deletes a chat and its record.                 |
+| Method           | Returns  | Description                                 |
+| ---------------- | -------- | ------------------------------------------- |
+| `createChat()`   | `string` | Creates a chat facet and returns its id.    |
+| `getChats()`     | `Chat[]` | Started chats, most recently updated first. |
+| `deleteChat(id)` | `void`   | Deletes a chat facet and its record.        |
+| `renameChat(id)` | `void`   | Renames a registered chat.                  |
 
 - **Titles and summaries** — generated with `fastModel` after each turn (on the first turn, then refreshed as the chat grows).
+- **Empty chat cleanup** — a newly created facet is scheduled for deletion after one day. Its first completed turn replaces that schedule with the normal sliding retention period.
 - **Retention** — inactive chats are deleted after 90 days, via a Durable Object alarm.
 
 ## Bindings

package/dist/index.d.mts

@@ -22,7 +22,6 @@ interface AgentEnv {
   SKILLS_BUCKET: R2Bucket;
   LOCAL_AGENT_DB?: D1Database;
 }
-type SqlFn = InstanceType<typeof Agent$1>["sql"];
 type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized" | "error";
 type AgentConnectionType = "agent" | "chat" | "assistant";
 //#endregion
@@ -287,59 +286,12 @@ type MessageFeedback = {
   updated_at: number;
 };
 //#endregion
-//#region src/server/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. */
-  durableObjectBinding: DurableObjectNamespace; /** 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/agents/ChatAgent.d.ts
 declare abstract class ChatAgent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>, State = unknown> extends Agent<RequestContext, UserContext, State> {
   protected agentType: AgentConnectionType;
   onStart(): Promise<void>;
   configureSession(session: Session): Session;
+  beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
   onChatResponse(_result: ChatResponseResult): Promise<void>;
   /**
    * Submit feedback for a message by its id.
@@ -353,19 +305,6 @@ declare abstract class ChatAgent<RequestContext extends Record<string, unknown>
    * @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/features/chats.d.ts
@@ -393,6 +332,7 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
   renameChat(id: string, title: string): Promise<void>;
   getChats(): Promise<Chat[]>;
   getChatAgentClassName(): Promise<string>;
+  registerChat(durableObjectName: string): Promise<void>;
   recordChatTurn(durableObjectName: string, messages: UIMessage[]): Promise<void>;
   recordChatFeedback(durableObjectName: string, messageId: string, rating: number): Promise<void>;
   private [DELETE_CHAT_CALLBACK];
@@ -413,26 +353,6 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
    * 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
-   * concrete subclass to enable lazy v1 -> v2 migration; leave undefined to
-   * disable it (e.g. for greenfield deployments with no v1 data).
-   */
-  protected getMigrationBinding(_env: Cloudflare.Env & AgentEnv): {
-    binding: DurableObjectNamespace;
-    db: D1Database;
-  } | undefined;
-  /** In-flight migration, shared across concurrent connections to this DO. */
-  private _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.
-   */
-  private ensureMigrated;
-  private runMigration;
 }
 //#endregion
 //#region src/server/util/skills.d.ts
@@ -452,4 +372,4 @@ declare function skill<Context extends Record<string, unknown> = Record<string,
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type ExchangedToken, type FacetStub, type LegacyChatStub, type LegacyMessageFeedback, type MigrationDeps, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, exchangeToken, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };
+export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type ExchangedToken, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -743,21 +743,7 @@ function ensureChatMessageFeedbackTableExists(sql) {
 }
 function registerChat(sql, durableObjectName, dateTime) {
 	sql`INSERT INTO chats (durable_object_name, created_at, updated_at)
-    VALUES (${durableObjectName}, ${dateTime}, ${dateTime})`;
-}
-/**
-* Registers a chat while preserving metadata carried over from a v1
-* conversation during migration: its title, summary, and original
-* timestamps. Used so migrated chats keep their titles instead of waiting
-* for the AI summariser to regenerate them.
-*
-* Idempotent: an existing row for the same chat id is left untouched.
-*/
-function registerChatWithMetadata(sql, durableObjectName, metadata) {
-	const { title, summary, createdAt } = metadata;
-	const updatedAt = metadata.updatedAt ?? createdAt;
-	sql`INSERT INTO chats (durable_object_name, title, summary, created_at, updated_at)
-    VALUES (${durableObjectName}, ${title ?? null}, ${summary ?? null}, ${createdAt}, ${updatedAt})
+    VALUES (${durableObjectName}, ${dateTime}, ${dateTime})
     ON CONFLICT (durable_object_name) DO NOTHING`;
 }
 /**
@@ -800,8 +786,8 @@ function recordChatFeedback(sql, durableObjectName, messageId, rating, dateTime
         negative_feedback_count = ${Number(negativeRows[0]?.count ?? 0)}
     WHERE durable_object_name = ${durableObjectName}`;
 }
-function getDeleteChatScheduleIds(schedules) {
-	return schedules.filter((schedule) => schedule.callback === DELETE_CHAT_CALLBACK).map((schedule) => schedule.id);
+function getDeleteChatScheduleIds(schedules, durableObjectName) {
+	return schedules.filter((schedule) => schedule.callback === "deleteChatCallback" && schedule.payload === durableObjectName).map((schedule) => schedule.id);
 }
 /**
 * Number of recent messages passed to `generateSummary` for rolling
@@ -862,92 +848,6 @@ function getChatRetentionMs(days) {
 	return Math.floor(days * 24 * 60 * 60 * 1e3);
 }
 //#endregion
-//#region src/server/features/migration.ts
-async function listLegacyConversations(db, userId) {
-	try {
-		const { results } = await db.prepare(`SELECT durable_object_name, title, summary, created_at, updated_at
-       FROM conversations WHERE durable_object_name LIKE ? ORDER BY updated_at ASC`).bind(`${userId}:%`).all();
-		return results ?? [];
-	} catch (error) {
-		if (error instanceof Error && error.message.includes(`no such table: conversations`)) {
-			console.warn("[Migration] Legacy conversations table missing; skipping v1 migration", { userId });
-			return [];
-		}
-		throw error;
-	}
-}
-async function listLegacyFeedback(db, durableObjectName) {
-	const { results } = await db.prepare(`SELECT message_id, rating, comment FROM message_ratings WHERE durable_object_name = ?`).bind(durableObjectName).all();
-	return (results ?? []).map((row) => ({
-		messageId: row.message_id,
-		rating: row.rating,
-		...row.comment != null ? { comment: row.comment } : {}
-	}));
-}
-/**
-* Removes a migrated v1 chat's D1 rows. Deleting the `conversations` row is what
-* makes the migration idempotent: it drops out of the enumeration so it is never
-* migrated again. The v1 DO itself is left to self-expire via v1 retention.
-*/
-async function deleteLegacyConversation(db, durableObjectName) {
-	await db.prepare(`DELETE FROM conversations WHERE durable_object_name = ?`).bind(durableObjectName).run();
-	await db.prepare(`DELETE FROM message_ratings WHERE durable_object_name = ?`).bind(durableObjectName).run();
-}
-function toEpochMs(value) {
-	if (!value) return Date.now();
-	const parsed = Date.parse(value);
-	return Number.isNaN(parsed) ? Date.now() : parsed;
-}
-/**
-* 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.
-*/
-async function migrateUserFromV1(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 durableObjectBinding.getByName(legacyName).exportForMigration();
-			const feedback = await listLegacyFeedback(db, legacyName);
-			const newChatId = nanoid();
-			const facet = await createFacet(newChatId);
-			if (messages.length > 0) await facet.importLegacyMessages(messages, feedback);
-			registerChatWithMetadata(sql, newChatId, {
-				title: conversation.title ?? void 0,
-				summary: conversation.summary ?? void 0,
-				createdAt: toEpochMs(conversation.created_at),
-				updatedAt: toEpochMs(conversation.updated_at)
-			});
-			await deleteLegacyConversation(db, legacyName);
-			migrated++;
-		} catch (error) {
-			failed++;
-			console.error("[Migration] Failed to migrate v1 chat", {
-				legacyName,
-				error
-			});
-		}
-	}
-	return {
-		migrated,
-		failed
-	};
-}
-//#endregion
 //#region src/server/agents/Assistant.ts
 let _initProto$1;
 function _applyDecs$1(e, t, n, r, o, i) {
@@ -1144,14 +1044,25 @@ var Assistant = class extends Agent$1 {
 				}
 			}
 		}
-		await this.ensureMigrated();
 		sendConnectionStatus(connection, "connected");
 	}
 	async createChat() {
 		const id = nanoid();
 		const now = Date.now();
 		await this.subAgent(this.agent, id);
-		registerChat(this.sql.bind(this), id, now);
+		try {
+			await this.scheduleChatForAutoDeletion(id, 1);
+		} catch (error) {
+			try {
+				await this.deleteSubAgent(this.agent, id);
+			} catch (cleanupError) {
+				console.error("[Assistant] Failed to clean up an unscheduled chat facet", {
+					durableObjectName: id,
+					error: cleanupError
+				});
+			}
+			throw error;
+		}
 		this.touchInstance(now);
 		return id;
 	}
@@ -1168,9 +1079,17 @@ var Assistant = class extends Agent$1 {
 	async getChatAgentClassName() {
 		return this.agent.name;
 	}
+	async registerChat(durableObjectName) {
+		registerChat(this.sql.bind(this), durableObjectName, Date.now());
+	}
 	async recordChatTurn(durableObjectName, messages) {
 		summariseChatWithAI(this.sql.bind(this), durableObjectName, messages, this.fastModel);
-		this.scheduleChatForAutoDeletion(durableObjectName);
+		this.scheduleChatForAutoDeletion(durableObjectName).catch((error) => {
+			console.error("[Assistant] Failed to reschedule chat deletion", {
+				durableObjectName,
+				error
+			});
+		});
 	}
 	async recordChatFeedback(durableObjectName, messageId, rating) {
 		recordChatFeedback(this.sql.bind(this), durableObjectName, messageId, rating);
@@ -1178,12 +1097,19 @@ var Assistant = class extends Agent$1 {
 	async [DELETE_CHAT_CALLBACK](durableObjectName) {
 		await this.deleteChat(durableObjectName);
 	}
-	async scheduleChatForAutoDeletion(durableObjectName) {
-		const retentionMs = getChatRetentionMs(90);
+	async scheduleChatForAutoDeletion(durableObjectName, retentionDays = 90) {
+		const retentionMs = getChatRetentionMs(retentionDays);
 		if (retentionMs === null) return;
-		const scheduleIds = getDeleteChatScheduleIds(await this.listSchedules());
-		await Promise.all(scheduleIds.map((scheduleId) => this.cancelSchedule(scheduleId)));
-		await this.schedule(new Date(Date.now() + retentionMs), DELETE_CHAT_CALLBACK, durableObjectName, { idempotent: true });
+		let lastError;
+		for (let attempt = 0; attempt < 3; attempt++) try {
+			const scheduleIds = getDeleteChatScheduleIds(await this.listSchedules(), durableObjectName);
+			await Promise.all(scheduleIds.map((scheduleId) => this.cancelSchedule(scheduleId)));
+			await this.schedule(new Date(Date.now() + retentionMs), DELETE_CHAT_CALLBACK, durableObjectName, { idempotent: true });
+			return;
+		} catch (error) {
+			lastError = error;
+		}
+		throw lastError;
 	}
 	/**
 	* Self-registers this Assistant in the global `agent_registry`. An Assistant
@@ -1222,52 +1148,6 @@ var Assistant = class extends Agent$1 {
 			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
-	* disable it (e.g. for greenfield deployments with no v1 data).
-	*/
-	getMigrationBinding(_env) {}
-	/** 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.getMigrationBinding(this.env)) return;
-		this._migrationPromise ??= this.runMigration().finally(() => {
-			this._migrationPromise = void 0;
-		});
-		await this._migrationPromise;
-	}
-	async runMigration() {
-		const migrationBinding = this.getMigrationBinding(this.env);
-		if (!migrationBinding) return;
-		try {
-			const result = await migrateUserFromV1({
-				sql: this.sql.bind(this),
-				db: migrationBinding.db,
-				userId: this.name,
-				durableObjectBinding: migrationBinding.binding,
-				createFacet: async (chatId) => {
-					return await this.subAgent(this.agent, chatId);
-				}
-			});
-			if (result.migrated > 0 || result.failed > 0) console.info("[Assistant] v1 -> v2 migration complete", {
-				userId: this.name,
-				...result
-			});
-		} catch (error) {
-			console.error("[Assistant] v1 -> v2 migration failed", {
-				userId: this.name,
-				error
-			});
-		}
-	}
 };
 //#endregion
 //#region src/server/features/messages.ts
@@ -1477,6 +1357,11 @@ var ChatAgent = class extends Agent {
 	configureSession(session) {
 		return super.configureSession(session).onCompaction(createCompactFn(this.getModel())).compactAfter(COMPACTION_TOKEN_THRESHOLD);
 	}
+	async beforeTurn(ctx) {
+		const parent = await this.getParentAgent();
+		if (parent?.registerChat) await parent.registerChat(this.name);
+		return super.beforeTurn(ctx);
+	}
 	async onChatResponse(_result) {
 		const parent = await this.getParentAgent();
 		if (parent?.recordChatTurn) await parent.recordChatTurn(this.name, this.messages);
@@ -1513,38 +1398,6 @@ var ChatAgent = class extends Agent {
 	async getMessageFeedback() {
 		return getMessageFeedback(this.sql.bind(this));
 	}
-	/**
-	* 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.
-	*/
-	async importLegacyMessages(messages, feedback = []) {
-		let parentId = null;
-		const parent = await this.getParentAgent();
-		for (const message of messages) {
-			await this.appendMessageToHistory(message, parentId);
-			parentId = message.id;
-		}
-		for (const item of feedback) {
-			submitMessageFeedback(this.sql.bind(this), item.messageId, item.rating, item.comment);
-			try {
-				await parent?.recordChatFeedback?.(this.name, item.messageId, item.rating);
-			} catch (error) {
-				console.error("[ChatAgent] Failed to import parent chat feedback summary", {
-					durableObjectName: this.name,
-					messageId: item.messageId,
-					error
-				});
-			}
-		}
-	}
 };
 //#endregion
 //#region src/server/util/skills.ts
@@ -1579,4 +1432,4 @@ function getCurrentToolContext() {
 	return getCurrentAgent().agent._lastBody;
 }
 //#endregion
-export { Agent, Assistant, ChatAgent, exchangeToken, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };
+export { Agent, Assistant, ChatAgent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/dist/v1.d.mts

@@ -220,17 +220,6 @@ declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TU
   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;

package/dist/v1.mjs

@@ -977,17 +977,6 @@ var ChatAgent = class extends AIChatAgent {
 	async getConversations() {
 		return getConversations(this.env.AGENT_DB, this.getUserId());
 	}
-	/**
-	* 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.
-	*/
-	async exportForMigration() {
-		return { messages: this.messages };
-	}
 	async deleteConversation(id) {
 		if (!id.startsWith(`${this.getUserId()}:`)) {
 			console.error("[Agent] Failed to delete conversation: Not owned by current user", {

package/package.json

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