@economic/agents 0.0.1-beta.6 → 1.0.0

package/dist/index.mjs

@@ -1,35 +1,10 @@
-import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
-import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, tool } from "ai";
-import { callable } from "agents";
+import { Agent as Agent$1, callable } from "agents";
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, streamText, tool } from "ai";
 //#region src/server/features/skills/index.ts
-/** Creates the `skill_state` table in DO SQLite if it does not exist yet. */
-function ensureSkillTable(sql) {
-	sql`CREATE TABLE IF NOT EXISTS skill_state (id INTEGER PRIMARY KEY, active_skills TEXT NOT NULL DEFAULT '[]')`;
-}
-/**
-* Reads the persisted list of loaded skill names from DO SQLite.
-* Returns an empty array if the table is missing or the row does not exist.
-*/
-function getStoredSkills(sql) {
-	try {
-		ensureSkillTable(sql);
-		const rows = sql`SELECT active_skills FROM skill_state WHERE id = 1`;
-		if (rows.length === 0) return [];
-		return JSON.parse(rows[0].active_skills);
-	} catch {
-		return [];
-	}
-}
-/**
-* Persists the current list of loaded skill names to DO SQLite.
-* Upserts the single `skill_state` row (id = 1).
-*/
-function saveStoredSkills(sql, skills) {
-	ensureSkillTable(sql);
-	sql`INSERT OR REPLACE INTO skill_state(id, active_skills) VALUES(1, ${JSON.stringify(skills)})`;
-}
-const ACTIVATE_SKILL = "activate_skill";
-const LIST_CAPABILITIES = "list_capabilities";
+const TOOL_NAME_ACTIVATE_SKILL = "activate_skill";
+const TOOL_NAME_LIST_CAPABILITIES = "list_capabilities";
+const SKILL_STATE_SENTINEL = "\n__SKILLS_STATE__:";
 function buildActivateSkillDescription(skills) {
 	return [
 		"Load additional skills to help with the user's request.",
@@ -44,17 +19,6 @@ function buildAvailableSkillList(skills) {
 }
 const LIST_CAPABILITIES_DESCRIPTION = "List all tools currently available to you, which skills are loaded, and which can still be loaded. Call this when the user asks about your capabilities or what you can do.";
 /**
-* Sentinel appended to a successful activate_skill result.
-*
-* Format: `Loaded: search, code.\n__SKILLS_STATE__:["search","code"]`
-*
-* The CF layer's `persistMessages` detects this sentinel, extracts the JSON
-* array of all currently-loaded skill names, writes it to DO SQLite, and
-* strips the entire activate_skill message from the persisted conversation.
-* No `onSkillsChanged` callback or D1 dependency needed.
-*/
-const SKILL_STATE_SENTINEL = "\n__SKILLS_STATE__:";
-/**
 * Creates a skill loading system for use with the Vercel AI SDK.
 *
 * The agent starts with only its always-on tools active. The LLM can call
@@ -72,8 +36,8 @@ function createSkills(config) {
 	for (const skill of skills) Object.assign(allTools, skill.tools);
 	function getActiveToolNames() {
 		const names = [
-			ACTIVATE_SKILL,
-			LIST_CAPABILITIES,
+			TOOL_NAME_ACTIVATE_SKILL,
+			TOOL_NAME_LIST_CAPABILITIES,
 			...Object.keys(alwaysOnTools)
 		];
 		for (const skillName of loadedSkills) {
@@ -92,7 +56,7 @@ function createSkills(config) {
 		if (sections.length === 0) return "";
 		return sections.join("\n\n");
 	}
-	allTools[ACTIVATE_SKILL] = tool({
+	allTools[TOOL_NAME_ACTIVATE_SKILL] = tool({
 		description: buildActivateSkillDescription(skills),
 		inputSchema: jsonSchema({
 			type: "object",
@@ -115,10 +79,10 @@ function createSkills(config) {
 				newlyLoaded.push(skillName);
 			}
 			if (newlyLoaded.length > 0) return `Loaded: ${newlyLoaded.join(", ")}.${SKILL_STATE_SENTINEL}${JSON.stringify([...loadedSkills])}`;
-			return ALREADY_LOADED_OUTPUT;
+			return "All requested skills were already loaded.";
 		}
 	});
-	allTools[LIST_CAPABILITIES] = tool({
+	allTools[TOOL_NAME_LIST_CAPABILITIES] = tool({
 		description: LIST_CAPABILITIES_DESCRIPTION,
 		inputSchema: jsonSchema({
 			type: "object",
@@ -150,7 +114,6 @@ function createSkills(config) {
 		}
 	};
 }
-const ALREADY_LOADED_OUTPUT = "All requested skills were already loaded.";
 /**
 * Removes ephemeral skill-related messages from a conversation.
 *
@@ -177,136 +140,35 @@ function filterEphemeralMessages(messages) {
 		}];
 	});
 }
-const TOOL_RESULT_PREVIEW_CHARS = 200;
-const SUMMARY_MAX_TOKENS = 4e3;
-/**
-* Estimates token count for a message array using a 3.5 chars/token
-* approximation. Counts text from text/reasoning parts, tool inputs/outputs.
-*/
-function estimateMessagesTokens(messages) {
-	let totalChars = 0;
-	for (const msg of messages) {
-		if (typeof msg.content === "string") {
-			totalChars += msg.content.length;
-			continue;
-		}
-		for (const part of msg.content) if (part.type === "text" || part.type === "reasoning") totalChars += part.text.length;
-		else if (part.type === "tool-call") totalChars += JSON.stringify(part.input).length;
-		else if (part.type === "tool-result") {
-			const output = part.output;
-			totalChars += typeof output === "string" ? output.length : JSON.stringify(output).length;
-		}
-	}
-	return Math.ceil(totalChars / 3.5);
-}
-/**
-* Renders messages as human-readable text for the compaction summary prompt.
-*/
-function formatMessagesForSummary(messages) {
-	const lines = [];
-	for (const msg of messages) {
-		const roleLabel = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
-		const parts = [];
-		if (typeof msg.content === "string") {
-			if (msg.content.trim()) parts.push(msg.content.trim());
-		} else for (const part of msg.content) if (part.type === "text" || part.type === "reasoning") {
-			const text = part.text.trim();
-			if (text) parts.push(text);
-		} else if (part.type === "tool-call") {
-			const p = part;
-			parts.push(`[Tool call: ${p.toolName}]`);
-		} else if (part.type === "tool-result") {
-			const p = part;
-			const rawOutput = typeof p.output === "string" ? p.output : JSON.stringify(p.output);
-			const preview = rawOutput.slice(0, TOOL_RESULT_PREVIEW_CHARS);
-			const ellipsis = rawOutput.length > TOOL_RESULT_PREVIEW_CHARS ? "..." : "";
-			parts.push(`[Tool: ${p.toolName}, result: ${preview}${ellipsis}]`);
-		}
-		if (parts.length > 0) lines.push(`${roleLabel}: ${parts.join(" ")}`);
-	}
-	return lines.join("\n\n");
+/** Creates the `skill_state` table in DO SQLite if it does not exist yet. */
+function ensureSkillTable(sql) {
+	sql`CREATE TABLE IF NOT EXISTS skill_state (id INTEGER PRIMARY KEY, active_skills TEXT NOT NULL DEFAULT '[]')`;
 }
 /**
-* Calls the model to produce a concise summary of old + recent message windows.
+* Reads the persisted list of loaded skill names from DO SQLite.
+* Returns an empty array if the table is missing or the row does not exist.
 */
-async function generateCompactionSummary(oldMessages, recentMessages, model) {
-	const prompt = `Summarize this conversation history concisely for an AI assistant to continue the conversation.
-Focus MORE on recent exchanges (what the user was working on, what tools were used, what was found).
-Include key facts, decisions, and context needed to continue the conversation.
-Keep entity names, numbers, file paths, and specific details that might be referenced later.
-Do NOT include pleasantries or meta-commentary - just the essential context.
-
-OLDER MESSAGES (summarize briefly):
-${formatMessagesForSummary(oldMessages)}
-
-RECENT MESSAGES (summarize with more detail - this is where the user currently is):
-${formatMessagesForSummary(recentMessages)}
-
-Write a concise summary:`;
+function getStoredSkills(sql) {
 	try {
-		const { text } = await generateText({
-			model,
-			messages: [{
-				role: "user",
-				content: prompt
-			}],
-			maxOutputTokens: SUMMARY_MAX_TOKENS
-		});
-		return text || "Unable to summarize conversation history.";
-	} catch (error) {
-		console.error("Compaction summarization error:", error);
-		return "Unable to summarize conversation history.";
+		ensureSkillTable(sql);
+		const rows = sql`SELECT active_skills FROM skill_state WHERE id = 1`;
+		if (rows.length === 0) return [];
+		return JSON.parse(rows[0].active_skills);
+	} catch {
+		return [];
 	}
 }
 /**
-* Summarizes older messages into a single system message and appends the
-* recent verbatim tail. Returns messages unchanged if already short enough.
-*/
-async function compactMessages(messages, model, tailSize) {
-	if (messages.length <= tailSize) return messages;
-	const splitIndex = messages.length - tailSize;
-	const oldMessages = messages.slice(0, splitIndex);
-	const recentTail = messages.slice(splitIndex);
-	return [{
-		role: "system",
-		content: `[Conversation summary - older context was compacted]\n${await generateCompactionSummary(oldMessages, recentTail, model)}`
-	}, ...recentTail];
-}
-/**
-* Entry point for compaction. Returns messages unchanged when model is
-* undefined or estimated token count is under COMPACT_TOKEN_THRESHOLD.
+* Persists the current list of loaded skill names to DO SQLite.
+* Upserts the single `skill_state` row (id = 1).
 */
-async function compactIfNeeded(messages, model, tailSize) {
-	if (!model || estimateMessagesTokens(messages) <= 14e4) return messages;
-	return compactMessages(messages, model, tailSize);
+function saveStoredSkills(sql, skills) {
+	ensureSkillTable(sql);
+	sql`INSERT OR REPLACE INTO skill_state(id, active_skills) VALUES(1, ${JSON.stringify(skills)})`;
 }
 //#endregion
 //#region src/server/llm.ts
-/**
-* Composes the full system prompt from its three parts: the consumer's base
-* string, the static skill roster, and the dynamic loaded-skill guidance.
-*
-* The full shape, at a glance:
-*
-*   {base}
-*
-*   ## Tools
-*
-*   Use `activate_skill` to load these skills (BE PROACTIVE on requesting
-*   tools based on the user's request AND you DON'T need to mention that you
-*   are loading more tools):
-*
-*   **{name}**: {description}
-*   ...
-*
-*   **Loaded skill instructions**
-*   The following skills are currently active. Apply their instructions when
-*   using the corresponding tools.
-*
-*   **{name}**
-*   {guidance body}
-*/
-function buildSystemPrompt(basePrompt, availableSkillList, loadedGuidance) {
+function buildSystemPromptWithSkills(basePrompt, availableSkillList, loadedGuidance) {
 	let prompt = `${basePrompt}
 
 ## Tools
@@ -359,99 +221,318 @@ function buildSourcesTransform(additional) {
 /**
 * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
 *
-* Handles message conversion, optional compaction, skill wiring (`activate_skill`,
-* `list_capabilities`, `prepareStep`), and context/abort signal extraction from
-* the Cloudflare Agents SDK `options` object.
+* Handles skill wiring (`activate_skill`, `list_capabilities`, `prepareStep`).
 *
 * The returned object can be spread directly into `streamText` or `generateText`:
 *
 * ```typescript
-* const params = await buildLLMParams({ ... });
+* const params = buildLLMParams({ ... });
 * return streamText(params).toUIMessageStreamResponse();
 * ```
 */
-async function buildLLMParams(config) {
-	const { options, messages, activeSkills = [], skills, fastModel, maxMessagesBeforeCompaction, experimental_transform, ...rest } = config;
-	const rawMessages = await convertToModelMessages(messages);
-	const processedMessages = fastModel && maxMessagesBeforeCompaction !== void 0 ? await compactIfNeeded(rawMessages, fastModel, maxMessagesBeforeCompaction) : rawMessages;
+function buildLLMParams(config) {
+	const { activeSkills = [], skills, experimental_transform, system, tools = {}, ...rest } = config;
 	const composedTransform = buildSourcesTransform(experimental_transform);
 	const baseParams = {
 		...rest,
-		experimental_transform: composedTransform,
-		messages: processedMessages,
-		experimental_context: options?.body,
-		abortSignal: options?.abortSignal,
-		stopWhen: rest.stopWhen ?? stepCountIs(20)
+		system,
+		tools,
+		stopWhen: rest.stopWhen ?? stepCountIs(20),
+		experimental_transform: composedTransform
 	};
 	if (!skills?.length) return baseParams;
-	const base = typeof rest.system === "string" ? rest.system : void 0;
 	const skillsCtx = createSkills({
-		tools: rest.tools ?? {},
+		tools,
 		skills,
 		initialLoadedSkills: activeSkills
 	});
+	const systemWithSkills = buildSystemPromptWithSkills(typeof system === "string" ? system : void 0, skillsCtx.availableSkillList, skillsCtx.getLoadedGuidance());
 	const prepareStep = async (stepOptions) => {
 		return {
 			activeTools: (await skillsCtx.prepareStep(stepOptions) ?? {}).activeTools ?? [],
-			system: buildSystemPrompt(base, skillsCtx.availableSkillList, skillsCtx.getLoadedGuidance())
+			system: systemWithSkills
 		};
 	};
 	return {
 		...baseParams,
-		system: buildSystemPrompt(base, skillsCtx.availableSkillList, skillsCtx.getLoadedGuidance()),
+		system: systemWithSkills,
 		tools: skillsCtx.tools,
 		activeTools: skillsCtx.activeTools,
 		prepareStep
 	};
 }
 //#endregion
-//#region src/server/features/audit/index.ts
+//#region src/server/features/audit/audit.ts
 /**
 * Inserts a single audit event row into the shared `audit_events` D1 table.
 *
-* Called by `AIChatAgent.log()`. Not intended for direct use.
+* Called by `ChatAgentHarness.logEvent()` (and `AgentHarness.logEvent()`). Not intended for direct use.
 */
+const SENSITIVE_KEYS = /^(password|token|secret|api_key|apikey|authorization|credentials)$/i;
+const REDACTED = "[REDACTED]";
+/** Deep-clone and redact values for keys that look like secrets (for audit logging). */
+function sanitizePayload(value) {
+	if (value === null || value === void 0) return value;
+	if (Array.isArray(value)) return value.map(sanitizePayload);
+	if (typeof value === "object") {
+		const result = {};
+		for (const [key, val] of Object.entries(value)) result[key] = SENSITIVE_KEYS.test(key) ? REDACTED : sanitizePayload(val);
+		return result;
+	}
+	return value;
+}
 async function insertAuditEvent(db, durableObjectName, message, payload) {
 	await db.prepare(`INSERT INTO audit_events (id, durable_object_name, message, payload, created_at)
-       VALUES (?, ?, ?, ?, ?)`).bind(crypto.randomUUID(), durableObjectName, message, payload ? JSON.stringify(payload) : null, (/* @__PURE__ */ new Date()).toISOString()).run();
+       VALUES (?, ?, ?, ?, ?)`).bind(crypto.randomUUID(), durableObjectName, message, payload ? JSON.stringify(sanitizePayload(payload)) : null, (/* @__PURE__ */ new Date()).toISOString()).run();
+}
+function stringifyForSkillScan(output) {
+	if (typeof output === "string") return output;
+	if (output === null || output === void 0) return "";
+	try {
+		return JSON.stringify(output);
+	} catch {
+		return "";
+	}
+}
+function forEachStep(event, fn) {
+	if (event.steps.length > 0) for (const step of event.steps) fn(step);
+	else fn(event);
+}
+/**
+* User text from provider request body (`contents` is e.g. Gemini format).
+*/
+function extractUserInputFromRequestBody(body) {
+	const firstContent = body?.contents?.[0];
+	if (firstContent?.role !== "user" || !firstContent.parts?.length) return "";
+	return firstContent.parts.map((p) => p.text).filter((t) => typeof t === "string").join(" ").trim();
+}
+/**
+* Builds the payload for a "Turn completed" audit event from the AI SDK
+* `OnFinishEvent`.
+*
+* Returns:
+* - `input`: user message text from `request.body.contents[0]` (Gemini-style)
+* - `output`: assistant response text (truncated to 200 chars)
+* - `toolCalls`: array of { toolName, toolInput, toolOutput }
+* - `loadedSkills`: skill names extracted from activate_skill results
+*/
+function buildTurnLogPayload(event) {
+	const toolCalls = [];
+	let latestSkills;
+	const toolOutputs = /* @__PURE__ */ new Map();
+	forEachStep(event, (step) => {
+		for (const tr of step.toolResults) toolOutputs.set(tr.toolCallId, tr.output);
+	});
+	forEachStep(event, (step) => {
+		for (const tc of step.toolCalls) toolCalls.push({
+			name: tc.toolName,
+			input: tc.input,
+			output: toolOutputs.get(tc.toolCallId)
+		});
+		const considerToolResultForSkills = (toolName, output) => {
+			if (toolName !== "activate_skill") return;
+			const s = stringifyForSkillScan(output);
+			const sentinelIdx = s.indexOf(SKILL_STATE_SENTINEL);
+			if (sentinelIdx === -1) return;
+			try {
+				const stateJson = s.slice(sentinelIdx + 18);
+				latestSkills = JSON.parse(stateJson);
+			} catch {}
+		};
+		for (const tr of step.toolResults) considerToolResultForSkills(tr.toolName, tr.output);
+	});
+	const input = extractUserInputFromRequestBody(event.request?.body);
+	return {
+		detail: {
+			model: event.model.modelId,
+			tokens: event.usage?.totalTokens
+		},
+		loadedSkills: latestSkills ?? [],
+		toolCalls,
+		input: input.slice(0, 200),
+		output: (event.text ?? "").slice(0, 200)
+	};
 }
+//#endregion
+//#region src/server/agents/Agent.ts
 /**
-* Builds the payload for a "turn completed" audit event from the final message list.
+* Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
+* audit logging, and `buildLLMParams` wiring.
+*
+* Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state
+* and writing audit events to D1.
 *
-* Extracts the last user and assistant message texts (truncated to 200 chars),
-* all non-meta tool call names used this turn, and the current loaded skill set.
+* For chat agents with message history, compaction, and conversation recording,
+* extend {@link ChatAgent} instead.
+*/
+var Agent = class extends Agent$1 {
+	/**
+	* Returns the user ID from the durable object name.
+	*/
+	getUserId() {
+		return this.name.split(":")[0];
+	}
+	async onConnect(connection, ctx) {
+		if (!this.env.AGENT_DB) {
+			console.error("[Agent] Connection rejected: no AGENT_DB bound");
+			connection.close(3e3, "Could not connect to agent, database not found");
+			return;
+		}
+		if (!this.getUserId()) {
+			console.error("[Agent] Connection rejected: name must be in the format userId:uniqueChatId");
+			connection.close(3e3, "Could not connect to agent, name is not in correct format");
+			return;
+		}
+		return super.onConnect(connection, ctx);
+	}
+	/**
+	* Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
+	* otherwise silently does nothing.
+	*
+	* Called automatically at the end of each LLM turn (from `onFinish` in
+	* `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
+	* `execute` functions.
+	*/
+	async logEvent(message, payload) {
+		try {
+			await insertAuditEvent(this.env.AGENT_DB, this.name, message, payload);
+		} catch (error) {
+			console.error("[Agent] Failed to write audit event", error);
+		}
+	}
+	/**
+	* Builds the parameter object for a `streamText` or `generateText` call,
+	* pre-filling `activeSkills` from this agent instance.
+	* Injects `logEvent` into `experimental_context` and wires `onFinish` for
+	* turn-completed audit events.
+	*/
+	async buildLLMParams(config) {
+		const activeSkills = await getStoredSkills(this.sql.bind(this));
+		const experimental_context = {
+			...config.options?.body,
+			logEvent: this.logEvent.bind(this)
+		};
+		const onFinish = async (event) => {
+			this.logEvent("Turn completed", buildTurnLogPayload(event));
+			await config.onFinish?.(event);
+		};
+		return buildLLMParams({
+			...config,
+			activeSkills,
+			experimental_context,
+			onFinish
+		});
+	}
+};
+const TOOL_RESULT_PREVIEW_CHARS = 200;
+const SUMMARY_MAX_TOKENS = 4e3;
+/**
+* Estimates token count for a message array using a 3.5 chars/token
+* approximation. Counts text from text/reasoning parts, tool inputs/outputs.
 */
-function buildTurnSummary(messages, loadedSkills) {
-	const toolCallNames = [];
+function estimateMessagesTokens(messages) {
+	let totalChars = 0;
 	for (const msg of messages) {
-		if (msg.role !== "assistant" || !msg.parts) continue;
-		for (const part of msg.parts) {
-			if (!("toolCallId" in part)) continue;
-			const { type } = part;
-			if (!type.startsWith("tool-")) continue;
-			const name = type.slice(5);
-			if (name !== "activate_skill" && name !== "list_capabilities" && !toolCallNames.includes(name)) toolCallNames.push(name);
+		if (typeof msg.content === "string") {
+			totalChars += msg.content.length;
+			continue;
+		}
+		for (const part of msg.content) if (part.type === "text" || part.type === "reasoning") totalChars += part.text.length;
+		else if (part.type === "tool-call") totalChars += JSON.stringify(part.input).length;
+		else if (part.type === "tool-result") {
+			const output = part.output;
+			totalChars += typeof output === "string" ? output.length : JSON.stringify(output).length;
 		}
 	}
-	const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
-	const lastAssistantMsg = [...messages].reverse().find((m) => m.role === "assistant");
-	return {
-		userMessage: extractMessageText(lastUserMsg).slice(0, 200),
-		toolCalls: toolCallNames,
-		loadedSkills,
-		assistantMessage: extractMessageText(lastAssistantMsg).slice(0, 200)
-	};
+	return Math.ceil(totalChars / 3.5);
+}
+/**
+* Renders messages as human-readable text for the compaction summary prompt.
+*/
+function formatMessagesForSummary(messages) {
+	const lines = [];
+	for (const msg of messages) {
+		const roleLabel = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
+		const parts = [];
+		if (typeof msg.content === "string") {
+			if (msg.content.trim()) parts.push(msg.content.trim());
+		} else for (const part of msg.content) if (part.type === "text" || part.type === "reasoning") {
+			const text = part.text.trim();
+			if (text) parts.push(text);
+		} else if (part.type === "tool-call") {
+			const p = part;
+			parts.push(`[Tool call: ${p.toolName}]`);
+		} else if (part.type === "tool-result") {
+			const p = part;
+			const rawOutput = typeof p.output === "string" ? p.output : JSON.stringify(p.output);
+			const preview = rawOutput.slice(0, TOOL_RESULT_PREVIEW_CHARS);
+			const ellipsis = rawOutput.length > TOOL_RESULT_PREVIEW_CHARS ? "..." : "";
+			parts.push(`[Tool: ${p.toolName}, result: ${preview}${ellipsis}]`);
+		}
+		if (parts.length > 0) lines.push(`${roleLabel}: ${parts.join(" ")}`);
+	}
+	return lines.join("\n\n");
 }
-function extractMessageText(msg) {
-	if (!msg?.parts) return "";
-	return msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ").trim();
+/**
+* Calls the model to produce a concise summary of old + recent message windows.
+*/
+async function generateCompactionSummary(oldMessages, recentMessages, model) {
+	const prompt = `Summarize this conversation history concisely for an AI assistant to continue the conversation.
+Focus MORE on recent exchanges (what the user was working on, what tools were used, what was found).
+Include key facts, decisions, and context needed to continue the conversation.
+Keep entity names, numbers, file paths, and specific details that might be referenced later.
+Do NOT include pleasantries or meta-commentary - just the essential context.
+
+OLDER MESSAGES (summarize briefly):
+${formatMessagesForSummary(oldMessages)}
+
+RECENT MESSAGES (summarize with more detail - this is where the user currently is):
+${formatMessagesForSummary(recentMessages)}
+
+Write a concise summary:`;
+	try {
+		const { text } = await generateText({
+			model,
+			messages: [{
+				role: "user",
+				content: prompt
+			}],
+			maxOutputTokens: SUMMARY_MAX_TOKENS
+		});
+		return text || "Unable to summarize conversation history.";
+	} catch (error) {
+		console.error("Compaction summarization error:", error);
+		return "Unable to summarize conversation history.";
+	}
+}
+/**
+* Summarizes older messages into a single system message and appends the
+* recent verbatim tail. Returns messages unchanged if already short enough.
+*/
+async function compactMessages(messages, model, tailSize) {
+	if (messages.length <= tailSize) return messages;
+	const splitIndex = messages.length - tailSize;
+	const oldMessages = messages.slice(0, splitIndex);
+	const recentTail = messages.slice(splitIndex);
+	return [{
+		role: "system",
+		content: `[Conversation summary - older context was compacted]\n${await generateCompactionSummary(oldMessages, recentTail, model)}`
+	}, ...recentTail];
+}
+/**
+* Entry point for compaction. Returns messages unchanged when model is
+* undefined or estimated token count is under COMPACT_TOKEN_THRESHOLD.
+*/
+async function compactIfNeeded(messages, model, tailSize) {
+	if (!model || estimateMessagesTokens(messages) <= 14e4) return messages;
+	return compactMessages(messages, model, tailSize);
 }
 //#endregion
-//#region src/server/features/conversations/index.ts
+//#region src/server/features/conversations/conversations.ts
 /**
 * Records a conversation row in the `conversations` D1 table.
 *
-* Called by `AIChatAgent` after every turn. On first call for a given
+* Called by `ChatAgentHarness` after every turn. On first call for a given
 * `durableObjectName` the row is inserted with `created_at` set to now,
 * and with the provided `title` and `summary` if supplied.
 * On subsequent calls only `updated_at` is refreshed —
@@ -480,6 +561,12 @@ async function getConversations(db, userId) {
 	return results;
 }
 /**
+* Deletes a conversation row from the `conversations` D1 table.
+*/
+async function deleteConversationRow(db, durableObjectName) {
+	await db.prepare(`DELETE FROM conversations WHERE durable_object_name = ?`).bind(durableObjectName).run();
+}
+/**
 * Writes a generated `title` and `summary` back to the `conversations` row.
 */
 async function updateConversationSummary(db, durableObjectName, title, summary) {
@@ -527,161 +614,134 @@ async function generateTitleAndSummary(messages, model, existingSummary) {
 * Only the last `SUMMARY_CONTEXT_MESSAGES` messages are passed to keep the
 * prompt bounded regardless of total conversation length.
 *
-* Called by `AIChatAgent` every `SUMMARY_CONTEXT_MESSAGES` messages after
+* Called by `ChatAgentHarness` every `SUMMARY_CONTEXT_MESSAGES` messages after
 * the first turn.
 */
 async function generateConversationSummary(db, durableObjectName, messages, model) {
 	const { title, summary } = await generateTitleAndSummary(messages, model, (await getConversationSummary(db, durableObjectName))?.summary ?? void 0);
 	await updateConversationSummary(db, durableObjectName, title, summary);
+	return {
+		title,
+		summary
+	};
+}
+//#endregion
+//#region src/server/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.";
+function getConversationRetentionMs(days) {
+	if (typeof days !== "number" || !Number.isFinite(days) || days <= 0) return null;
+	return Math.floor(days * 24 * 60 * 60 * 1e3);
+}
+function getDeleteConversationScheduleIds(schedules) {
+	return schedules.filter((schedule) => schedule.callback === DELETE_CONVERSATION_CALLBACK).map((schedule) => schedule.id);
 }
 //#endregion
-//#region src/server/agents/AIChatAgent.ts
+//#region src/server/agents/ChatAgent.ts
 /**
-* Base class for Cloudflare Agents SDK chat agents with lazy skill loading
-* and built-in audit logging.
+* Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,
+* message persistence, compaction, and conversation metadata in D1.
 *
-* Handles CF infrastructure concerns only: DO SQLite persistence for loaded
-* skill state, stripping skill meta-tool messages before persistence, history
-* replay to newly connected clients, and writing audit events to D1.
+* Handles CF infrastructure concerns: DO SQLite for loaded skill state,
+* stripping skill meta-tool messages before persistence, history replay to
+* newly connected clients, and audit events to D1.
 *
-* Skill loading, compaction, and LLM communication are delegated to
-* `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
+* Skill loading, compaction, and LLM calls use `buildLLMParams` from
+* `@economic/agents` inside `onChatMessage`.
 */
-var AIChatAgent = class extends AIChatAgent$1 {
+var ChatAgent = class extends AIChatAgent {
+	/**
+	* Number of days of inactivity before the full conversation is deleted.
+	*
+	* Leave `undefined` to disable automatic retention cleanup.
+	*/
+	conversationRetentionDays;
+	/**
+	* Number of recent messages to keep verbatim when compaction runs.
+	* Older messages beyond this count are summarised into a single system message.
+	* Used as the default when `maxMessagesBeforeCompaction` is not provided to `buildLLMParams`.
+	*
+	* Default is 15.
+	*/
+	maxMessagesBeforeCompaction = 15;
+	/**
+	* Returns the user ID from the durable object name.
+	*/
 	getUserId() {
 		return this.name.split(":")[0];
 	}
 	async onConnect(connection, ctx) {
-		await super.onConnect(connection, ctx);
-		if (!this.getUserId()) {
-			console.error("[AIChatAgent] Connection rejected: name must be in the format userId:uniqueChatId");
-			connection.close(3e3, "Name does not match format userId:uniqueChatId");
+		if (!this.env.AGENT_DB) {
+			console.error("[ChatAgent] Connection rejected: no AGENT_DB bound");
+			connection.close(3e3, "Could not connect to agent, database not found");
 			return;
 		}
-	}
-	/**
-	* Resolves the D1 database binding required for all D1 writes.
-	* Returns null and silently no-ops if AGENT_DB is not bound.
-	*/
-	resolveD1Context() {
-		const db = this.env.AGENT_DB;
-		if (!db) {
-			console.error("[AIChatAgent] Skipping logging: D1 database not found");
-			return null;
+		if (!this.getUserId()) {
+			console.error("[ChatAgent] Connection rejected: name must be in the format userId:uniqueChatId");
+			connection.close(3e3, "Could not connect to agent, name is not in correct format");
+			return;
 		}
-		return db;
-	}
-	/**
-	* Returns all conversations for the current user.
-	*/
-	@callable() async getConversations() {
-		const db = this.resolveD1Context();
-		if (!db) return;
-		return getConversations(db, this.getUserId());
+		return super.onConnect(connection, ctx);
 	}
 	/**
 	* Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
 	* otherwise silently does nothing.
 	*
-	* Called automatically after every turn (from `persistMessages`) and on
-	* non-clean finish reasons (from `buildLLMParams`). Also available via
-	* `experimental_context.log` in tool `execute` functions.
-	*/
-	async log(message, payload) {
-		const db = this.resolveD1Context();
-		if (!db) return;
-		await insertAuditEvent(db, this.name, message, payload);
-	}
-	/**
-	* Records this conversation in the `conversations` D1 table and triggers
-	* LLM-based title/summary generation when appropriate. Called automatically
-	* from `persistMessages` after every 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.
+	* Called automatically at the end of each LLM turn (from `onFinish` in
+	* `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
+	* `execute` functions.
 	*/
-	async recordConversation(messageCount) {
-		const db = this.resolveD1Context();
-		if (!db) return;
-		if (!await getConversationSummary(db, this.name)) {
-			const { title, summary } = await generateTitleAndSummary(this.messages, this.fastModel);
-			await recordConversation(db, this.name, title, summary);
-			this.log("conversation summary generated");
-		} else {
-			await recordConversation(db, this.name);
-			if (messageCount % 30 === 0) {
-				generateConversationSummary(db, this.name, this.messages, this.fastModel);
-				this.log("conversation summary updated");
-			}
+	async logEvent(message, payload) {
+		try {
+			await insertAuditEvent(this.env.AGENT_DB, this.name, message, payload);
+		} catch (error) {
+			console.error("[ChatAgent] Failed to write audit event", error);
 		}
 	}
 	/**
 	* Builds the parameter object for a `streamText` or `generateText` call,
 	* pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
-	* Injects `log` into `experimental_context` and logs non-clean finish reasons.
+	* Injects `logEvent` into `experimental_context` and wires `onFinish` for
+	* turn-completed audit events and conversation recording.
 	*
 	* **Compaction** runs automatically when `fastModel` is set on the class, using
 	* `DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION` (30) as the threshold. Override the
-	* threshold by passing `maxMessagesBeforeCompaction`. Disable compaction entirely
-	* by passing `maxMessagesBeforeCompaction: undefined` explicitly.
-	*
-	* ```typescript
-	* // Compaction on (default threshold):
-	* const params = await this.buildLLMParams({ options, onFinish, model, system: "..." });
-	*
-	* // Compaction with custom threshold:
-	* const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: 50 });
-	*
-	* // Compaction off:
-	* const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: undefined });
-	*
-	* return streamText(params).toUIMessageStreamResponse();
-	* ```
+	* threshold by setting `maxMessagesBeforeCompaction` on the class. Disable compaction
+	* entirely by setting `maxMessagesBeforeCompaction = undefined` explicitly.
 	*/
 	async buildLLMParams(config) {
-		const maxMessagesBeforeCompaction = "maxMessagesBeforeCompaction" in config ? config.maxMessagesBeforeCompaction : 15;
-		const onFinishWithErrorLogging = async (result) => {
-			if (result.finishReason !== "stop" && result.finishReason !== "tool-calls") await this.log("turn error", { finishReason: result.finishReason });
-			return config.onFinish?.(result);
+		const activeSkills = await getStoredSkills(this.sql.bind(this));
+		const experimental_context = {
+			...config.options?.body,
+			logEvent: this.logEvent.bind(this)
 		};
-		return {
-			...await buildLLMParams({
-				...config,
-				onFinish: onFinishWithErrorLogging,
-				messages: this.messages,
-				activeSkills: await this.getLoadedSkills(),
-				fastModel: this.fastModel,
-				maxMessagesBeforeCompaction
-			}),
-			experimental_context: {
-				...config.options?.body,
-				log: this.log.bind(this)
-			}
+		const messages = await convertToModelMessages(this.messages);
+		const fastModel = this.getFastModel();
+		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);
 		};
-	}
-	/**
-	* Skill names persisted from previous turns, read from DO SQLite.
-	* Returns an empty array if no skills have been loaded yet.
-	*/
-	async getLoadedSkills() {
-		return getStoredSkills(this.sql.bind(this));
+		return buildLLMParams({
+			...config,
+			activeSkills,
+			messages: processedMessages,
+			experimental_context,
+			onFinish
+		});
 	}
 	/**
 	* Extracts skill state from activate_skill results, persists to DO SQLite,
-	* logs a turn summary, then strips all skill meta-tool messages before
-	* delegating to super.
+	* then strips all skill meta-tool messages before delegating to super.
 	*
 	* 1. Scans activate_skill tool results for SKILL_STATE_SENTINEL. When found,
 	*    the embedded JSON array of loaded skill names is written to DO SQLite.
 	*
-	* 2. Logs a turn summary via `log()`. Best-effort: fire-and-forget.
+	* 2. Strips all activate_skill and list_capabilities messages from history.
 	*
-	* 3. Strips all activate_skill and list_capabilities messages from history.
-	*
-	* 4. Delegates to super.persistMessages for message storage and WS broadcast.
+	* 3. Delegates to super.persistMessages for message storage and WS broadcast.
 	*/
 	async persistMessages(messages, excludeBroadcastIds = [], options) {
 		let latestSkillState;
@@ -699,11 +759,125 @@ var AIChatAgent = class extends AIChatAgent$1 {
 			}
 		}
 		if (latestSkillState !== void 0) saveStoredSkills(this.sql.bind(this), latestSkillState);
-		this.log("turn completed", buildTurnSummary(messages, latestSkillState ?? []));
-		this.recordConversation(messages.length);
 		const filtered = filterEphemeralMessages(messages);
-		return super.persistMessages(filtered, excludeBroadcastIds, options);
+		const result = await super.persistMessages(filtered, excludeBroadcastIds, options);
+		this.scheduleConversationForDeletion();
+		return result;
+	}
+	@callable({ description: "Returns all conversations for the current user" }) async getConversations() {
+		return getConversations(this.env.AGENT_DB, this.getUserId());
+	}
+	@callable({ description: "Delete a conversation by its id" }) async deleteConversation(id) {
+		if (!id.startsWith(`${this.getUserId()}:`)) {
+			console.error("[ChatAgent] Failed to delete conversation: Not owned by current user", {
+				conversationName: id,
+				userId: this.getUserId()
+			});
+			this.logEvent("Failed to delete conversation: Not owned by current user", {
+				conversationName: id,
+				userId: this.getUserId()
+			});
+			return false;
+		}
+		try {
+			await deleteConversationRow(this.env.AGENT_DB, id);
+		} catch (error) {
+			console.error("[ChatAgent] Failed to delete conversation row", {
+				conversationName: id,
+				error
+			});
+			return false;
+		}
+		await (id === this.name ? this : this.binding.getByName(id)).destroy();
+		return true;
+	}
+	async destroy() {
+		for (const connection of this.getConnections()) try {
+			connection.close(CONVERSATION_EXPIRED_CLOSE_CODE, CONVERSATION_EXPIRED_CLOSE_REASON);
+		} catch (error) {
+			console.error("[ChatAgent] Failed to close expired conversation connection", error);
+		}
+		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() {
+		const retentionMs = getConversationRetentionMs(this.conversationRetentionDays);
+		if (retentionMs === null) return;
+		const scheduleIds = getDeleteConversationScheduleIds(this.getSchedules());
+		await Promise.all(scheduleIds.map((scheduleId) => this.cancelSchedule(scheduleId)));
+		await this.schedule(new Date(Date.now() + retentionMs), DELETE_CONVERSATION_CALLBACK);
+	}
+};
+//#endregion
+//#region src/server/harnesses/ChatAgentHarness.ts
+var ChatAgentHarness = class extends ChatAgent {
+	get binding() {
+		const className = this.constructor.name;
+		return this.env[className];
+	}
+	conversationRetentionDays = 90;
+	/**
+	* Returns the tools for the agent.
+	* @param ctx - The context object for the agent built from the request body.
+	* @returns The tools for the agent.
+	*/
+	getTools(_ctx) {
+		return {};
+	}
+	/**
+	* Returns the skills for the agent.
+	* @param ctx - The context object for the agent built from the request body.
+	* @returns The skills for the agent.
+	*/
+	getSkills(_ctx) {
+		return [];
+	}
+	async onChatMessage(onFinish, options) {
+		const ctx = options?.body;
+		return streamText(await this.buildLLMParams({
+			options,
+			onFinish,
+			model: this.getModel(ctx),
+			system: this.getSystemPrompt(ctx),
+			skills: this.getSkills(ctx),
+			tools: this.getTools(ctx)
+		})).toUIMessageStreamResponse();
 	}
 };
 //#endregion
-export { AIChatAgent, buildLLMParams };
+export { Agent, ChatAgent, ChatAgentHarness, buildLLMParams };