@economic/agents 2.1.4 → 2.1.5

package/dist/index.d.mts

@@ -135,6 +135,10 @@ interface MessageRating {
  * `@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.
    */
@@ -196,6 +200,8 @@ declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TU
    * 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>;
   /**
@@ -217,6 +223,17 @@ 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/index.mjs

@@ -667,6 +667,10 @@ async function getMessageRatings(db, durableObjectName) {
 * `@economic/agents` inside `onChatMessage`.
 */
 var ChatAgent = class extends AIChatAgent {
+	initialState = {
+		status: "connecting",
+		type: "chat"
+	};
 	/**
 	* Number of days of inactivity before the full conversation is deleted.
 	*
@@ -697,6 +701,18 @@ var ChatAgent = class extends AIChatAgent {
 	getUserId() {
 		return this.name.split(":")[0];
 	}
+	onStart() {
+		this.setState({
+			...this.initialState,
+			status: "connecting"
+		});
+	}
+	async onClose() {
+		this.setState({
+			type: "chat",
+			status: "disconnected"
+		});
+	}
 	async onConnect(connection, ctx) {
 		this.clientIp = ctx.request.headers.get("CF-Connecting-IP") ?? ctx.request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim();
 		this.forwardedFor = ctx.request.headers.get("X-Forwarded-For") ?? void 0;
@@ -725,10 +741,18 @@ var ChatAgent = class extends AIChatAgent {
 				} catch (error) {
 					console.error("[Agent] JWT verification error", error);
 					connection.close(4001, "Unauthorized");
+					this.setState({
+						type: "chat",
+						status: "unauthorized"
+					});
 					return;
 				}
 				if (!result.success) {
 					connection.close(result.status === 401 ? 4001 : 4003, result.message);
+					this.setState({
+						type: "chat",
+						status: "unauthorized"
+					});
 					return;
 				}
 			}
@@ -737,6 +761,10 @@ var ChatAgent = class extends AIChatAgent {
 				if (userContext) connection.setState({ userContext });
 			});
 		}
+		this.setState({
+			type: "chat",
+			status: "connected"
+		});
 		return super.onConnect(connection, ctx);
 	}
 	_pendingUserContextRequest;
@@ -809,6 +837,17 @@ var ChatAgent = class extends AIChatAgent {
 	@callable({ description: "Returns all conversations for the current user" }) 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 };
+	}
 	@callable({ description: "Delete a conversation by its id" }) async deleteConversation(id) {
 		if (!id.startsWith(`${this.getUserId()}:`)) {
 			console.error("[Agent] Failed to delete conversation: Not owned by current user", {

package/dist/v2.d.mts

@@ -18,6 +18,7 @@ interface AgentEnv {
   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 = {
@@ -126,6 +127,56 @@ type MessageFeedback = {
   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;
@@ -144,6 +195,19 @@ 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/v2/features/chats.d.ts
@@ -161,9 +225,26 @@ declare abstract class Assistant extends Agent$1<Cloudflare.Env, AgentConnection
   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[]>;
@@ -172,4 +253,4 @@ declare abstract class Assistant extends Agent$1<Cloudflare.Env, AgentConnection
   private scheduleChatForAutoDeletion;
 }
 //#endregion
-export { Agent, type AgentConnectionState, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type Skill, type Tool, type ToolContext, type ToolSet, getCurrentToolContext, skill, tool };
+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 };

package/dist/v2.mjs

@@ -297,6 +297,21 @@ 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})
+    ON CONFLICT (durable_object_name) DO NOTHING`;
+}
 function deleteChat(sql, durableObjectName) {
 	sql`DELETE FROM chats WHERE durable_object_name = ${durableObjectName}`;
 }
@@ -368,12 +383,99 @@ function getChatRetentionMs(days) {
 	return Math.floor(days * 24 * 60 * 60 * 1e3);
 }
 //#endregion
+//#region src/server/v2/features/migration.ts
+async function listLegacyConversations(db, userId) {
+	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 ?? [];
+}
+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, legacyNamespace, 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 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/v2/agents/Assistant.ts
 var Assistant = class extends Agent$1 {
 	initialState = {
 		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,
@@ -423,12 +525,53 @@ var Assistant = class extends Agent$1 {
 				});
 			}
 		}
+		await this.ensureMigrated();
 		this.setState({
 			...this.initialState,
 			status: "connected",
 			subAgentName: this.agent.name
 		});
 	}
+	/**
+	* 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;
+		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;
+		}
+		try {
+			const result = await migrateUserFromV1({
+				sql: this.sql.bind(this),
+				db: this.env.AGENT_DB,
+				userId: this.name,
+				legacyNamespace,
+				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
+			});
+		}
+	}
 	@callable() async createChat() {
 		const id = nanoid();
 		const now = Date.now();
@@ -549,6 +692,26 @@ var ChatAgent = class extends Agent {
 	@callable({ description: "Returns all message feedback for the current chat" }) 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;
+		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);
+	}
 };
 //#endregion
 //#region src/server/v2/util/skills.ts
@@ -559,4 +722,4 @@ function skill(definition) {
 	return definition;
 }
 //#endregion
-export { Agent, Assistant, ChatAgent, getCurrentToolContext, skill, tool };
+export { Agent, Assistant, ChatAgent, getCurrentToolContext, migrateUserFromV1, skill, tool };

package/package.json

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