@economic/agents 1.4.1 → 1.5.0

package/README.md

@@ -476,6 +476,24 @@ When the retention period expires, the D1 row is deleted, WebSocket connections
 const conversations = await agent.call("getConversations");
 ```
 
+#### Message Ratings (D1)
+
+Users can rate individual messages with thumbs up/down. Ratings are stored in D1 and can be updated if the user changes their mind.
+
+```typescript
+// Rate a message (1 = thumbs up, -1 = thumbs down)
+await agent.call("rateMessage", [messageId, 1]);
+
+// Change rating
+await agent.call("rateMessage", [messageId, -1]);
+
+// Get all ratings for the current conversation
+const ratings = await agent.call("getMessageRatings");
+// Returns: { "message_id_1": 1, "message_id_2": -1, ... }
+```
+
+Ratings are stored per message and upserted on conflict — calling `rateMessage` on an already-rated message updates the rating. Requires [`schema/chat.sql`](schema/chat.sql) which includes the `message_ratings` table.
+
 ---
 
 ## API Reference

package/dist/index.d.mts

@@ -1,29 +1,9 @@
-import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext } from "agents";
-import { AIChatAgent, OnChatMessageOptions } from "@cloudflare/ai-chat";
 import { LanguageModel, StreamTextOnFinishCallback, ToolSet, UIMessage, generateText, streamText } from "ai";
+import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext } from "agents";
+import { AIChatAgent, ChatResponseResult, OnChatMessageOptions } from "@cloudflare/ai-chat";
 import { JWTPayload } from "jose";
 
-//#region src/server/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`.
- *
- * Define your own body shape and compose:
- * ```typescript
- * interface MyBody { userTier: "free" | "pro" }
- * type MyContext = AgentToolContext<MyBody>;
- * ```
- */
-type AgentToolContext<TBody = Record<string, unknown>, TSession = Record<string, unknown> | undefined> = TBody & {
-  logEvent: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
-  session?: TSession;
-};
-interface AgentEnv {
-  AGENT_DB: D1Database;
-}
-//#endregion
-//#region src/server/features/skills/index.d.ts
+//#region src/server/shared/features/skills/index.d.ts
 /**
  * A named group of related tools that can be loaded together on demand.
  *
@@ -45,7 +25,7 @@ interface Skill {
   tools: ToolSet;
 }
 //#endregion
-//#region src/server/llm.d.ts
+//#region src/server/shared/util/llm.d.ts
 type LLMParams = Parameters<typeof streamText>[0] & Parameters<typeof generateText>[0];
 type BuildLLMParamsConfig = Omit<LLMParams, "prompt"> & {
   /** Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`. */activeSkills?: string[]; /** Skills available for on-demand loading this turn. */
@@ -65,7 +45,31 @@ type BuildLLMParamsConfig = Omit<LLMParams, "prompt"> & {
  */
 declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
 //#endregion
-//#region src/server/features/auth/index.d.ts
+//#region src/server/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`.
+ *
+ * Define your own body shape and compose:
+ * ```typescript
+ * interface MyBody { userTier: "free" | "pro" }
+ * type MyContext = AgentToolContext<MyBody>;
+ * ```
+ */
+type AgentToolContext<TBody = Record<string, unknown>, TSession = Record<string, unknown> | undefined> = TBody & {
+  logEvent: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
+  session?: TSession;
+};
+interface AgentEnv {
+  AGENT_DB: D1Database;
+}
+interface ChatAgentEnv extends AgentEnv {}
+//#endregion
+//#region src/server/route-agent-request.d.ts
+declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
+//#endregion
+//#region src/server/shared/features/auth/index.d.ts
 interface JwtAuthConfig<TClaims extends Record<string, unknown> = Record<string, unknown>> {
   /** Issuers whose tokens are accepted (exact string or RegExp). */
   allowedIssuers: readonly (string | RegExp)[];
@@ -80,7 +84,7 @@ interface JwtAuthConfig<TClaims extends Record<string, unknown> = Record<string,
   getClaims: (payload: JWTPayload) => TClaims;
 }
 //#endregion
-//#region src/server/agents/Agent.d.ts
+//#region src/server/agent/Agent.d.ts
 /**
  * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
  * audit logging, and `buildLLMParams` wiring.
@@ -130,7 +134,7 @@ declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env> extend
   }): Promise<LLMParams>;
 }
 //#endregion
-//#region src/server/agents/ChatAgent.d.ts
+//#region src/server/agent-chat/ChatAgent.d.ts
 /**
  * Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,
  * message persistence, compaction, and conversation metadata in D1.
@@ -142,7 +146,7 @@ declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env> extend
  * Skill loading, compaction, and LLM calls use `buildLLMParams` from
  * `@economic/agents` inside `onChatMessage`.
  */
-declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent<Env & AgentEnv> {
+declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent<Env & ChatAgentEnv> {
   /**
    * The binding of the Durable Object instance for this agent.
    */
@@ -222,26 +226,17 @@ declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> ex
   persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
     _deleteStaleRows?: boolean;
   }): Promise<void>;
+  protected onChatResponse(result: ChatResponseResult): Promise<void>;
+  rateMessage(messageId: string, rating: number): Promise<void>;
+  getMessageRatings(): Promise<Record<string, number>>;
   getConversations(): Promise<Record<string, unknown>[]>;
   deleteConversation(id: string): Promise<boolean>;
   destroy(): Promise<void>;
-  /**
-   * Records this conversation in the `conversations` D1 table and triggers
-   * LLM-based title/summary generation when appropriate. Called automatically
-   * from `onFinish` in `buildLLMParams` after each completed LLM turn.
-   *
-   * On the first turn (no existing row), awaits `generateTitleAndSummary` and
-   * inserts the row with title and summary already populated. On subsequent
-   * turns, upserts the timestamp and fire-and-forgets a summary refresh every
-   * `SUMMARY_CONTEXT_MESSAGES` messages (when the context window fully turns
-   * over). Neither path blocks the response to the client.
-   */
-  private recordConversation;
   private deleteConversationCallback;
-  private scheduleConversationForDeletion;
+  private scheduleConversationForAutoDeletion;
 }
 //#endregion
-//#region src/server/harnesses/ChatAgentHarness.d.ts
+//#region src/server/agent-chat/ChatAgentHarness.d.ts
 declare abstract class ChatAgentHarness<Env extends Cloudflare.Env, RequestBody extends Record<string, unknown> = Record<string, unknown>> extends ChatAgent<Env> {
   get binding(): {
     getByName(name: string): {
@@ -276,7 +271,4 @@ declare abstract class ChatAgentHarness<Env extends Cloudflare.Env, RequestBody
   onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response>;
 }
 //#endregion
-//#region src/server/route-agent-request.d.ts
-declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
-//#endregion
 export { Agent, type AgentToolContext, type BuildLLMParamsConfig, ChatAgent, ChatAgentHarness, type Skill, buildLLMParams, routeAgentRequest };

package/dist/index.mjs

@@ -1,8 +1,8 @@
+import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, streamText, tool } from "ai";
 import { Agent as Agent$1, callable, routeAgentRequest as routeAgentRequest$1 } from "agents";
 import { AIChatAgent } from "@cloudflare/ai-chat";
-import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, streamText, tool } from "ai";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
-//#region src/server/features/skills/index.ts
+//#region src/server/shared/features/skills/index.ts
 const TOOL_NAME_ACTIVATE_SKILL = "activate_skill";
 const TOOL_NAME_LIST_CAPABILITIES = "list_capabilities";
 const SKILL_STATE_SENTINEL = "\n__SKILLS_STATE__:";
@@ -115,31 +115,10 @@ function createSkills(config) {
 		}
 	};
 }
-/**
-* Removes ephemeral skill-related messages from a conversation.
-*
-* Strips both `activate_skill` and `list_capabilities` tool calls entirely —
-* skill state is persisted to DO SQLite by the CF layer, so these messages
-* are not needed for future turns.
-*
-* If stripping leaves an assistant message with no parts, the entire message
-* is dropped.
-*/
-function filterEphemeralMessages(messages) {
-	return messages.flatMap((msg) => {
-		if (msg.role !== "assistant" || !msg.parts?.length) return [msg];
-		const filtered = msg.parts.filter((part) => {
-			if (!("toolCallId" in part)) return true;
-			const { type } = part;
-			return type !== `tool-list_capabilities` && type !== `tool-activate_skill`;
-		});
-		if (filtered.length === 0) return [];
-		if (filtered.length === msg.parts.length) return [msg];
-		return [{
-			...msg,
-			parts: filtered
-		}];
-	});
+function isEphemeralSkillToolPart(part) {
+	if (!part || typeof part !== "object" || !("toolCallId" in part) || !("type" in part)) return false;
+	const { type } = part;
+	return type === `tool-list_capabilities` || type === `tool-activate_skill`;
 }
 /** Creates the `skill_state` table in DO SQLite if it does not exist yet. */
 function ensureSkillTable(sql) {
@@ -182,7 +161,7 @@ function saveSkillStateFromMessages(sql, messages) {
 	sql`INSERT OR REPLACE INTO skill_state(id, active_skills) VALUES(1, ${JSON.stringify(latestSkillState)})`;
 }
 //#endregion
-//#region src/server/llm.ts
+//#region src/server/shared/util/llm.ts
 function buildSystemPromptWithSkills(basePrompt, availableSkillList, loadedGuidance) {
 	let prompt = `${basePrompt}
 
@@ -277,7 +256,20 @@ function buildLLMParams(config) {
 	};
 }
 //#endregion
-//#region src/server/features/audit/audit.ts
+//#region src/server/route-agent-request.ts
+async function routeAgentRequest(request, env, options) {
+	const response = await routeAgentRequest$1(request, env, options);
+	if (!response) return null;
+	const protocol = request.headers.get("Sec-WebSocket-Protocol");
+	if (response.status === 101 && protocol) {
+		const newResponse = new Response(null, response);
+		newResponse.headers.set("Sec-WebSocket-Protocol", protocol.split(",")[0].trim());
+		return newResponse;
+	}
+	return response;
+}
+//#endregion
+//#region src/server/shared/features/audit/audit.ts
 /**
 * Inserts a single audit event row into the shared `audit_events` D1 table.
 *
@@ -369,7 +361,7 @@ function buildTurnLogPayload(event) {
 	};
 }
 //#endregion
-//#region src/server/features/auth/index.ts
+//#region src/server/shared/features/auth/index.ts
 const jwksByIssuer = /* @__PURE__ */ new Map();
 function getJwksForIssuer(issuer) {
 	const normalized = issuer.replace(/\/$/, "");
@@ -469,7 +461,7 @@ async function verifyJwt(request, config) {
 	};
 }
 //#endregion
-//#region src/server/agents/Agent.ts
+//#region src/server/agent/Agent.ts
 /**
 * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
 * audit logging, and `buildLLMParams` wiring.
@@ -668,7 +660,16 @@ async function compactIfNeeded(messages, model, tailSize) {
 	return compactMessages(messages, model, tailSize);
 }
 //#endregion
-//#region src/server/features/conversations/conversations.ts
+//#region src/server/agent-chat/features/conversations/conversations.ts
+async function recordConversationSummary(db, durableObjectName, messages, model) {
+	if (!await getConversationSummary(db, durableObjectName)) {
+		const { title, summary } = await generateTitleAndSummary(messages, model);
+		await upsertConversationSummary(db, durableObjectName, title, summary);
+	} else {
+		await upsertConversationSummary(db, durableObjectName);
+		if (messages.length % SUMMARY_CONTEXT_MESSAGES === 0) await generateConversationSummary(db, durableObjectName, messages, model);
+	}
+}
 /**
 * Records a conversation row in the `conversations` D1 table.
 *
@@ -679,7 +680,7 @@ async function compactIfNeeded(messages, model, tailSize) {
 * `created_at`, `title`, and `summary` are never overwritten, preserving
 * any user edits.
 */
-async function recordConversation(db, durableObjectName, title, summary) {
+async function upsertConversationSummary(db, durableObjectName, title, summary) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	await db.prepare(`INSERT INTO conversations (durable_object_name, title, summary, created_at, updated_at)
        VALUES (?, ?, ?, ?, ?)
@@ -687,6 +688,12 @@ async function recordConversation(db, durableObjectName, title, summary) {
          updated_at = excluded.updated_at`).bind(durableObjectName, title ?? null, summary ?? null, now, now).run();
 }
 /**
+* Number of recent messages passed to `generateSummary` for rolling
+* summarization. Keeping this bounded prevents the prompt growing
+* unboundedly regardless of conversation length.
+*/
+const SUMMARY_CONTEXT_MESSAGES = 30;
+/**
 * Returns the current `title` and `summary` for a conversation row,
 * or `null` if the row does not exist yet.
 */
@@ -724,7 +731,7 @@ async function updateConversationSummary(db, durableObjectName, title, summary)
 * prompt bounded regardless of total conversation length.
 */
 async function generateTitleAndSummary(messages, model, existingSummary) {
-	const recentMessages = await convertToModelMessages(messages.slice(-30));
+	const recentMessages = await convertToModelMessages(messages.slice(-SUMMARY_CONTEXT_MESSAGES));
 	const previousContext = existingSummary ? `Previous summary: ${existingSummary}\n\nMost recent messages:` : "Conversation:";
 	const { output } = await generateText({
 		model,
@@ -766,7 +773,7 @@ async function generateConversationSummary(db, durableObjectName, messages, mode
 	};
 }
 //#endregion
-//#region src/server/features/conversations/retention.ts
+//#region src/server/agent-chat/features/conversations/retention.ts
 const DELETE_CONVERSATION_CALLBACK = "deleteConversationCallback";
 const CONVERSATION_EXPIRED_CLOSE_CODE = 3001;
 const CONVERSATION_EXPIRED_CLOSE_REASON = "Conversation expired due to inactivity.";
@@ -778,7 +785,34 @@ function getDeleteConversationScheduleIds(schedules) {
 	return schedules.filter((schedule) => schedule.callback === DELETE_CONVERSATION_CALLBACK).map((schedule) => schedule.id);
 }
 //#endregion
-//#region src/server/agents/ChatAgent.ts
+//#region src/server/shared/util/messages.ts
+function filterEphemeralMessages(messages) {
+	return messages.flatMap((message) => {
+		if (message.role !== "assistant" || !message.parts?.length) return [message];
+		const filteredParts = message.parts.filter((part) => !isEphemeralSkillToolPart(part));
+		if (filteredParts.length === 0) return [];
+		return [{
+			...message,
+			parts: filteredParts
+		}];
+	});
+}
+//#endregion
+//#region src/server/agent-chat/features/conversations/rating.ts
+async function rateMessage(db, durableObjectName, messageId, rating) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	await db.prepare(`INSERT INTO message_ratings (message_id, durable_object_name, rating, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT (message_id, durable_object_name) DO UPDATE SET
+        rating = excluded.rating,
+        updated_at = excluded.updated_at`).bind(messageId, durableObjectName, rating, now, now).run();
+}
+async function getMessageRatings(db, durableObjectName) {
+	const result = await db.prepare(`SELECT message_id, rating FROM message_ratings WHERE durable_object_name = ?`).bind(durableObjectName).all();
+	return Object.fromEntries(result.results.map((row) => [row.message_id, row.rating]));
+}
+//#endregion
+//#region src/server/agent-chat/ChatAgent.ts
 /**
 * Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,
 * message persistence, compaction, and conversation metadata in D1.
@@ -886,7 +920,6 @@ var ChatAgent = class extends AIChatAgent {
 		const processedMessages = fastModel && this.maxMessagesBeforeCompaction !== void 0 ? await compactIfNeeded(messages, fastModel, this.maxMessagesBeforeCompaction) : messages;
 		const onFinish = async (event) => {
 			this.logEvent("Turn completed", buildTurnLogPayload(event));
-			this.recordConversation(filterEphemeralMessages([...this.messages]));
 			await config.onFinish?.(event);
 		};
 		return buildLLMParams({
@@ -901,7 +934,21 @@ var ChatAgent = class extends AIChatAgent {
 		const filtered = filterEphemeralMessages(messages);
 		await super.persistMessages(filtered, excludeBroadcastIds, options);
 		saveSkillStateFromMessages(this.sql.bind(this), messages);
-		this.scheduleConversationForDeletion();
+		await super.persistMessages(filterEphemeralMessages(messages), excludeBroadcastIds, options);
+	}
+	async onChatResponse(result) {
+		if (result.error) {
+			console.error("[ChatAgent] Chat response error", result.error);
+			return;
+		}
+		recordConversationSummary(this.env.AGENT_DB, this.name, this.messages, this.getFastModel());
+		this.scheduleConversationForAutoDeletion();
+	}
+	@callable({ description: "Rate a message by its id" }) async rateMessage(messageId, rating) {
+		await rateMessage(this.env.AGENT_DB, this.name, messageId, rating);
+	}
+	@callable({ description: "Returns all message ratings for the current conversation" }) async getMessageRatings() {
+		return getMessageRatings(this.env.AGENT_DB, this.name);
 	}
 	@callable({ description: "Returns all conversations for the current user" }) async getConversations() {
 		return getConversations(this.env.AGENT_DB, this.getUserId());
@@ -938,43 +985,13 @@ var ChatAgent = class extends AIChatAgent {
 		}
 		return super.destroy();
 	}
-	/**
-	* Records this conversation in the `conversations` D1 table and triggers
-	* LLM-based title/summary generation when appropriate. Called automatically
-	* from `onFinish` in `buildLLMParams` after each completed LLM turn.
-	*
-	* On the first turn (no existing row), awaits `generateTitleAndSummary` and
-	* inserts the row with title and summary already populated. On subsequent
-	* turns, upserts the timestamp and fire-and-forgets a summary refresh every
-	* `SUMMARY_CONTEXT_MESSAGES` messages (when the context window fully turns
-	* over). Neither path blocks the response to the client.
-	*/
-	async recordConversation(messages) {
-		if (!await getConversationSummary(this.env.AGENT_DB, this.name)) {
-			const { title, summary } = await generateTitleAndSummary(messages, this.getFastModel());
-			await recordConversation(this.env.AGENT_DB, this.name, title, summary);
-			this.logEvent("Conversation summary generated", {
-				title,
-				summary
-			});
-		} else {
-			await recordConversation(this.env.AGENT_DB, this.name);
-			if (messages.length % 30 === 0) {
-				const { title, summary } = await generateConversationSummary(this.env.AGENT_DB, this.name, messages, this.getFastModel());
-				this.logEvent("Conversation summary updated", {
-					title,
-					summary
-				});
-			}
-		}
-	}
 	async deleteConversationCallback() {
 		if (await this.deleteConversation(this.name)) this.logEvent("Conversation deleted due to inactivity", {
 			conversationName: this.name,
 			retentionDays: this.conversationRetentionDays ?? null
 		});
 	}
-	async scheduleConversationForDeletion() {
+	async scheduleConversationForAutoDeletion() {
 		const retentionMs = getConversationRetentionMs(this.conversationRetentionDays);
 		if (retentionMs === null) return;
 		const scheduleIds = getDeleteConversationScheduleIds(this.getSchedules());
@@ -983,7 +1000,7 @@ var ChatAgent = class extends AIChatAgent {
 	}
 };
 //#endregion
-//#region src/server/harnesses/ChatAgentHarness.ts
+//#region src/server/agent-chat/ChatAgentHarness.ts
 var ChatAgentHarness = class extends ChatAgent {
 	get binding() {
 		const className = this.constructor.name;
@@ -1019,17 +1036,4 @@ var ChatAgentHarness = class extends ChatAgent {
 	}
 };
 //#endregion
-//#region src/server/route-agent-request.ts
-async function routeAgentRequest(request, env, options) {
-	const response = await routeAgentRequest$1(request, env, options);
-	if (!response) return null;
-	const protocol = request.headers.get("Sec-WebSocket-Protocol");
-	if (response.status === 101 && protocol) {
-		const newResponse = new Response(null, response);
-		newResponse.headers.set("Sec-WebSocket-Protocol", protocol.split(",")[0].trim());
-		return newResponse;
-	}
-	return response;
-}
-//#endregion
 export { Agent, ChatAgent, ChatAgentHarness, buildLLMParams, routeAgentRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "bin": {
@@ -33,6 +33,7 @@
     "@cloudflare/workers-types": "^4.20260412.1",
     "@types/node": "^25.6.0",
     "@typescript/native-preview": "7.0.0-dev.20260412.1",
+    "agents": "^0.11.0",
     "ai": "^6.0.158",
     "jose": "^6.2.2",
     "tsdown": "^0.21.7",
@@ -41,7 +42,7 @@
   },
   "peerDependencies": {
     "@cloudflare/ai-chat": ">=0.1.0 <1.0.0",
-    "agents": ">=0.10.2 <1.0.0",
+    "agents": ">=0.11.0 <1.0.0",
     "ai": "^6.0.0",
     "jose": "^6.0.0"
   },

package/schema/chat.sql

@@ -21,5 +21,15 @@ CREATE TABLE IF NOT EXISTS conversations (
   updated_at        TEXT NOT NULL
 );
 
-CREATE INDEX IF NOT EXISTS conversations_do   ON conversations(durable_object_name);
-CREATE INDEX IF NOT EXISTS conversations_ts   ON conversations(updated_at);
+CREATE INDEX IF NOT EXISTS conversations_ts ON conversations(updated_at);
+
+-- ─── Message ratings ──────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS message_ratings (
+  message_id          TEXT NOT NULL,
+  durable_object_name TEXT NOT NULL,
+  rating              INTEGER,
+  created_at          TEXT NOT NULL,
+  updated_at          TEXT NOT NULL,
+  PRIMARY KEY (message_id, durable_object_name)
+);