@economic/agents 0.0.1-alpha.8 → 0.0.1-beta.1

package/dist/index.mjs

@@ -1,18 +1,35 @@
-import { convertToModelMessages, generateText, jsonSchema, stepCountIs, streamText, tool } from "ai";
 import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
-//#region src/features/skills/meta-tools.ts
+import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, tool } from "ai";
+import { callable } from "agents";
+//#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 '[]')`;
+}
 /**
-* Names and descriptions for the built-in meta tools.
-*
-* The execute logic for these lives in createSkills() where it has
-* access to the closure state (loadedSkills).
+* 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.
 */
-const ACTIVATE_SKILL = "activate_skill";
-const LIST_CAPABILITIES = "list_capabilities";
+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 [];
+	}
+}
 /**
-* Builds the tool description for activate_skill, including the
-* current list of available skills with their descriptions.
+* 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";
 function buildActivateSkillDescription(skills) {
 	return [
 		"Load additional skills to help with the user's request.",
@@ -23,42 +40,27 @@ function buildActivateSkillDescription(skills) {
 	].join("\n");
 }
 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.";
-//#endregion
-//#region src/features/skills/index.ts
+/**
+* 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
 * activate_skill to load skill tools on demand. Which skills are loaded is
-* persisted to D1 across turns — no message-history parsing required.
-*
-* Guidance from loaded skills is injected as a system message just before
-* the current user turn, keeping the `system` prompt static and cacheable.
-* prepareStep keeps the guidance message updated if new skills load mid-turn.
-*
-* Usage with streamText (ai v6):
-* ```typescript
-* import { streamText, convertToModelMessages, stepCountIs } from "ai";
-*
-* // initialLoadedSkills comes from D1 (read at turn start by the agent).
-* // onSkillsChanged is called when new skills are loaded; the agent
-* // buffers the value and writes it to D1 at turn end in persistMessages.
-* const lt = createSkills({ tools, skills, initialLoadedSkills, onSkillsChanged });
-* const messages = injectGuidance(modelMessages, lt.getLoadedGuidance());
-*
-* const result = streamText({
-*   model,
-*   system: baseSystemPrompt, // static — never contains guidance, stays cacheable
-*   messages,
-*   tools: lt.tools,
-*   activeTools: lt.activeTools,
-*   prepareStep: lt.prepareStep, // keeps guidance message updated mid-turn
-*   stopWhen: stepCountIs(20),
-* });
-* ```
+* communicated to the CF layer via a sentinel in the activate_skill result
+* and persisted to DO SQLite — no D1 or message-history parsing required.
 */
 function createSkills(config) {
-	const { tools: alwaysOnTools, skills, filterSkill, onSkillsChanged } = config;
+	const { tools: alwaysOnTools, skills } = config;
 	const loadedSkills = new Set(config.initialLoadedSkills ?? []);
 	const skillMap = new Map(skills.map((s) => [s.name, s]));
 	const allTools = {};
@@ -101,24 +103,13 @@ function createSkills(config) {
 		}),
 		execute: async ({ skills: requested }) => {
 			const newlyLoaded = [];
-			const denied = [];
 			for (const skillName of requested) {
 				if (!skillMap.get(skillName)) continue;
 				if (loadedSkills.has(skillName)) continue;
-				if (!(filterSkill ? await filterSkill(skillName) : true)) {
-					denied.push(skillName);
-					continue;
-				}
 				loadedSkills.add(skillName);
 				newlyLoaded.push(skillName);
 			}
-			if (newlyLoaded.length > 0 && onSkillsChanged) await onSkillsChanged([...loadedSkills]);
-			if (newlyLoaded.length > 0) {
-				let result = `Loaded: ${newlyLoaded.join(", ")}.`;
-				if (denied.length > 0) result += ` Access denied for: ${denied.join(", ")}.`;
-				return result;
-			}
-			if (denied.length > 0) return `Access denied for: ${denied.join(", ")}.`;
+			if (newlyLoaded.length > 0) return `Loaded: ${newlyLoaded.join(", ")}.${SKILL_STATE_SENTINEL}${JSON.stringify([...loadedSkills])}`;
 			return ALREADY_LOADED_OUTPUT;
 		}
 	});
@@ -158,48 +149,23 @@ function createSkills(config) {
 	};
 }
 const ALREADY_LOADED_OUTPUT = "All requested skills were already loaded.";
-const DENIED_OUTPUT_PREFIX = "Access denied for:";
 /**
-* Removes ephemeral messages from the conversation before it is saved to D1.
-*
-* Three kinds of messages are stripped:
-*
-* 1. list_capabilities tool calls — always stripped. Capability discovery is
-*    only relevant within the current turn; it adds no useful context for
-*    future turns.
+* Removes ephemeral skill-related messages from a conversation.
 *
-* 2. activate_skill calls when nothing was newly loaded — stripped when all
-*    requested skills were already active, or when all were denied. In both
-*    cases nothing changed, so persisting the call would only add noise.
-*
-* 3. Guidance system messages — stripped by exact content match against the
-*    provided guidance string. Guidance is always recomputed from loaded skill
-*    definitions at turn start, so persisting it would create a redundant
-*    second source of truth alongside the loaded_skills D1 column.
-*
-* When skills ARE successfully loaded, the short "Loaded: X" result is kept
-* in history for model context — so the model can see what was loaded in
-* prior turns. Skill state is restored from D1 loaded_skills, not from these
-* strings.
+* 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 (e.g. a step that did nothing but call list_capabilities).
+* is dropped.
 */
-function filterEphemeralMessages(messages, guidanceToStrip) {
+function filterEphemeralMessages(messages) {
 	return messages.flatMap((msg) => {
-		if (msg.role === "system" && guidanceToStrip) {
-			if (msg.parts?.some((p) => "text" in p && p.text === guidanceToStrip)) return [];
-		}
 		if (msg.role !== "assistant" || !msg.parts?.length) return [msg];
 		const filtered = msg.parts.filter((part) => {
 			if (!("toolCallId" in part)) return true;
-			const { type, output } = part;
-			if (type === `tool-list_capabilities`) return false;
-			if (type === `tool-activate_skill`) {
-				if (typeof output !== "string") return true;
-				return output !== ALREADY_LOADED_OUTPUT && !output.startsWith(DENIED_OUTPUT_PREFIX);
-			}
-			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];
@@ -209,122 +175,57 @@ function filterEphemeralMessages(messages, guidanceToStrip) {
 		}];
 	});
 }
-/**
-* Injects loaded skill guidance as a system message just before the last
-* message in the array (typically the current user turn).
-*
-* Guidance is kept separate from the static `system` prompt so that the
-* system prompt stays identical on every turn and can be prompt-cached.
-* Positioning just before the last message means guidance survives any
-* compaction strategy that preserves recent context.
-*
-* Pass `previousGuidance` (the string injected on the prior call) to remove
-* the stale guidance message before inserting the updated one. Removal is by
-* exact content match — not by role — so other system messages (memories,
-* user preferences, etc.) are left untouched.
-*
-* At turn start, omit `previousGuidance` — guidance is never persisted to D1
-* (it is stripped by filterEphemeralMessages before saving), so there is
-* nothing to remove. prepareStep uses previousGuidance within a turn to
-* handle guidance updates when new skills are loaded mid-turn.
-*
-* ```typescript
-* // Turn start — just inject
-* const messages = injectGuidance(modelMessages, skills.getLoadedGuidance());
-*
-* // prepareStep — remove stale guidance then re-inject updated guidance
-* const messages = injectGuidance(stepMessages, newGuidance, previousGuidance);
-* ```
-*/
-function injectGuidance(messages, guidance, previousGuidance) {
-	if (!guidance) return messages;
-	const base = previousGuidance ? messages.filter((m) => !(m.role === "system" && m.content === previousGuidance)) : messages;
-	const insertAt = base.findLastIndex((m) => m.role === "user");
-	return [
-		...base.slice(0, insertAt),
-		{
-			role: "system",
-			content: guidance
-		},
-		...base.slice(insertAt)
-	];
-}
-//#endregion
-//#region src/agents/chat/compaction/index.ts
-/**
-* Message compaction for long-running conversations.
-*
-* When the stored conversation history exceeds COMPACT_TOKEN_THRESHOLD, older
-* messages are summarised via an LLM call and replaced with a single system
-* message containing the summary, followed by the recent verbatim tail.
-*
-* Entry point: compactIfNeeded() — called once per turn from persistMessages.
-*
-* To remove compaction entirely: delete this directory, remove the import in
-* AIChatAgentBase, and change `toSave` back to `filtered`.
-*/
-const COMPACT_TOKEN_THRESHOLD = 14e4;
 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 — the same heuristic used by slack-bot. Counts text from
-* text parts, tool inputs/outputs, and reasoning parts.
+* approximation. Counts text from text/reasoning parts, tool inputs/outputs.
 */
 function estimateMessagesTokens(messages) {
 	let totalChars = 0;
 	for (const msg of messages) {
-		if (!msg.parts) continue;
-		for (const part of msg.parts) {
-			if ((part.type === "text" || part.type === "reasoning") && "text" in part) {
-				totalChars += part.text.length;
-				continue;
-			}
-			if ("toolCallId" in part) {
-				const toolPart = part;
-				if (toolPart.input) totalChars += JSON.stringify(toolPart.input).length;
-				if (toolPart.output !== void 0) {
-					const outputStr = typeof toolPart.output === "string" ? toolPart.output : JSON.stringify(toolPart.output);
-					totalChars += outputStr.length;
-				}
-			}
+		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.
-* Text parts are included verbatim; tool calls show name and a truncated result.
-* step-start and empty messages are omitted.
 */
 function formatMessagesForSummary(messages) {
 	const lines = [];
 	for (const msg of messages) {
 		const roleLabel = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
 		const parts = [];
-		for (const part of msg.parts ?? []) {
-			if (part.type === "step-start") continue;
-			if ((part.type === "text" || part.type === "reasoning") && "text" in part) {
-				const text = part.text.trim();
-				if (text) parts.push(text);
-				continue;
-			}
-			if ("toolCallId" in part) {
-				const toolPart = part;
-				const toolName = toolPart.type.startsWith("tool-") ? toolPart.type.slice(5) : toolPart.type;
-				const rawOutput = toolPart.output === void 0 ? "no result" : typeof toolPart.output === "string" ? toolPart.output : JSON.stringify(toolPart.output);
-				const preview = rawOutput.slice(0, TOOL_RESULT_PREVIEW_CHARS);
-				const ellipsis = rawOutput.length > TOOL_RESULT_PREVIEW_CHARS ? "..." : "";
-				parts.push(`[Tool: ${toolName}, result: ${preview}${ellipsis}]`);
-			}
+		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");
 }
 /**
-* Calls the LLM to produce a concise summary of old + recent message windows.
-* Weights the prompt toward recent exchanges, matching slack-bot's approach.
+* 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.
@@ -357,363 +258,375 @@ Write a concise summary:`;
 }
 /**
 * Summarizes older messages into a single system message and appends the
-* recent verbatim tail. Returns messages unchanged if the history is already
-* short enough to fit within tailSize.
+* 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);
-	const summary = await generateCompactionSummary(oldMessages, recentTail, model);
 	return [{
-		id: `compact_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
 		role: "system",
-		parts: [{
-			type: "text",
-			text: `[Conversation summary - older context was compacted]\n${summary}`,
-			state: "done"
-		}]
+		content: `[Conversation summary - older context was compacted]\n${await generateCompactionSummary(oldMessages, recentTail, model)}`
 	}, ...recentTail];
 }
 /**
-* Entry point called from persistMessages once per turn.
-*
-* Returns messages unchanged when:
-* - model is undefined (compaction disabled on this agent)
-* - estimated token count is under COMPACT_TOKEN_THRESHOLD
-*
-* Otherwise delegates to compactMessages.
+* 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/agents/chat/AIChatAgentBase.ts
+//#region src/server/llm.ts
 /**
-* Base class for chat agents with lazy skill loading.
+* Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
 *
-* Owns:
-* - D1 persistence for loaded skill state (skill names survive DO eviction)
-* - Ephemeral message filtering (list_capabilities, no-op activate_skill calls)
-* - Message compaction (LLM summarisation when history exceeds token threshold)
-* - History replay to newly connected clients (onConnect override)
-* - Skill context preparation for use with the @withSkills decorator
+* Handles message conversion, optional compaction, skill wiring (`activate_skill`,
+* `list_capabilities`, `prepareStep`), and context/abort signal extraction from
+* the Cloudflare Agents SDK `options` object.
 *
-* Conversation messages are stored in Durable Object SQLite, managed
-* automatically by the Cloudflare AIChatAgent — no D1 write needed for messages.
+* The returned object can be spread directly into `streamText` or `generateText`:
 *
-* D1 is written only when skills change (activate_skill was called this turn),
-* not on every turn.
+* ```typescript
+* const params = await buildLLMParams({ ... });
+* return streamText(params).toUIMessageStreamResponse();
+* ```
+*/
+async function buildLLMParams(config) {
+	const { options, messages, activeSkills = [], skills, fastModel, maxMessagesBeforeCompaction, ...rest } = config;
+	const rawMessages = await convertToModelMessages(messages);
+	const processedMessages = fastModel && maxMessagesBeforeCompaction !== void 0 ? await compactIfNeeded(rawMessages, fastModel, maxMessagesBeforeCompaction) : rawMessages;
+	const baseParams = {
+		...rest,
+		messages: processedMessages,
+		experimental_context: options?.body,
+		abortSignal: options?.abortSignal,
+		stopWhen: rest.stopWhen ?? stepCountIs(20)
+	};
+	if (!skills?.length) return baseParams;
+	const skillsCtx = createSkills({
+		tools: rest.tools ?? {},
+		skills,
+		initialLoadedSkills: activeSkills,
+		systemPrompt: typeof rest.system === "string" ? rest.system : void 0
+	});
+	const prepareStep = async (stepOptions) => {
+		const skillsResult = await skillsCtx.prepareStep(stepOptions) ?? {};
+		return {
+			activeTools: skillsResult.activeTools ?? [],
+			system: skillsResult.system
+		};
+	};
+	return {
+		...baseParams,
+		system: skillsCtx.getSystem() || rest.system,
+		tools: skillsCtx.tools,
+		activeTools: skillsCtx.activeTools,
+		prepareStep
+	};
+}
+//#endregion
+//#region src/server/features/audit/index.ts
+/**
+* Inserts a single audit event row into the shared `audit_events` D1 table.
 *
-* ## Usage
+* Called by `AIChatAgent.log()`. Not intended for direct use.
+*/
+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();
+}
+/**
+* Builds the payload for a "turn completed" audit event from the final message list.
 *
-* Extend this class when you want full control over `streamText`. Implement
-* `getTools()`, `getSkills()`, and your own `onChatMessage` decorated with
-* `@withSkills`:
+* 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.
+*/
+function buildTurnSummary(messages, loadedSkills) {
+	const toolCallNames = [];
+	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);
+		}
+	}
+	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)
+	};
+}
+function extractMessageText(msg) {
+	if (!msg?.parts) return "";
+	return msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ").trim();
+}
+//#endregion
+//#region src/server/features/conversations/index.ts
+/**
+* Records a conversation row in the `conversations` D1 table.
+*
+* Called by `AIChatAgent` 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 —
+* `created_at`, `title`, and `summary` are never overwritten, preserving
+* any user edits.
+*/
+async function recordConversation(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 (?, ?, ?, ?, ?)
+       ON CONFLICT(durable_object_name) DO UPDATE SET
+         updated_at = excluded.updated_at`).bind(durableObjectName, title ?? null, summary ?? null, now, now).run();
+}
+/**
+* Returns the current `title` and `summary` for a conversation row,
+* or `null` if the row does not exist yet.
+*/
+async function getConversationSummary(db, durableObjectName) {
+	return await db.prepare(`SELECT title, summary FROM conversations WHERE durable_object_name = ?`).bind(durableObjectName).first() ?? null;
+}
+/**
+* Returns all conversations for a user, ordered by most recent.
+*/
+async function getConversations(db, userId) {
+	const { results } = await db.prepare(`SELECT * FROM conversations WHERE durable_object_name LIKE ? ORDER BY updated_at DESC`).bind(`${userId}:%`).all();
+	return results;
+}
+/**
+* Writes a generated `title` and `summary` back to the `conversations` row.
+*/
+async function updateConversationSummary(db, durableObjectName, title, summary) {
+	await db.prepare(`UPDATE conversations SET title = ?, summary = ? WHERE durable_object_name = ?`).bind(title, summary, durableObjectName).run();
+}
+/**
+* Generates a title and summary for a conversation using the provided model.
+* Returns the result without writing to D1.
 *
-* ```typescript
-* export class MyAgent extends AIChatAgentBase {
-*   getTools()  { return []; }
-*   getSkills() { return [searchSkill, codeSkill]; }
-*   getDB()     { return this.env.AGENT_DB; }
+* Pass `existingSummary` so the model can detect direction changes when
+* updating an existing summary. Omit it (or pass undefined) for the initial
+* generation.
 *
-*   @withSkills
-*   async onChatMessage(onFinish, ctx: SkillContext, options?) {
-*     const { messages, ...skillArgs } = ctx;
-*     return streamText({
-*       model: openai("gpt-4o"),
-*       system: "You are a helpful assistant.",
-*       messages,
-*       ...skillArgs,
-*       onFinish,
-*       stopWhen: stepCountIs(20),
-*     }).toUIMessageStreamResponse();
-*   }
-* }
-* ```
+* Only the last `SUMMARY_CONTEXT_MESSAGES` messages are used to keep the
+* prompt bounded regardless of total conversation length.
+*/
+async function generateTitleAndSummary(messages, model, existingSummary) {
+	const recentMessages = await convertToModelMessages(messages.slice(-30));
+	const previousContext = existingSummary ? `Previous summary: ${existingSummary}\n\nMost recent messages:` : "Conversation:";
+	const { output } = await generateText({
+		model,
+		output: Output.object({ schema: jsonSchema({
+			type: "object",
+			properties: {
+				title: {
+					type: "string",
+					description: "Short title for the conversation, max 8 words"
+				},
+				summary: {
+					type: "string",
+					description: "2-3 sentence summary. If the conversation direction has changed from the previous summary, reflect the new direction."
+				}
+			},
+			required: ["title", "summary"]
+		}) }),
+		prompt: `${previousContext}\n\n${formatMessagesForSummary(recentMessages)}`
+	});
+	return output;
+}
+/**
+* Generates a title and summary for a conversation using the provided model
+* and writes the result back to D1.
 *
-* For a batteries-included experience where the base class owns `onChatMessage`,
-* extend `AIChatAgent` instead.
+* Fetches any existing summary first so the model can detect direction changes.
+* 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
+* the first turn.
 */
-var AIChatAgentBase = class extends AIChatAgent$1 {
-	/**
-	* Maximum number of messages stored in DO SQLite.
-	*
-	* Lowered from the Cloudflare AIChatAgent default of 200. When compaction
-	* is enabled, one slot is reserved for the summary message so the verbatim
-	* tail is maxPersistedMessages - 1 recent messages. Raise or lower per agent.
-	*/
-	maxPersistedMessages = 50;
-	/**
-	* Query parameter names to read from the WebSocket connection URL and
-	* forward to tools via experimental_context.
-	*
-	* Browsers cannot set custom headers on WebSocket upgrade requests, so
-	* auth tokens and other metadata must be passed as query parameters instead.
-	*
-	* ```typescript
-	* passthroughRequestHeaders = ['authorization', 'x-user-id'];
-	* ```
-	*
-	* Values are read from the URL at connect time and stored in _requestHeaders
-	* for the lifetime of the Durable Object instance.
-	*/
-	passthroughRequestHeaders = [];
-	/**
-	* Return a LanguageModel to use for compaction summarisation.
-	*
-	* Return undefined (default) to disable compaction — messages are kept up
-	* to maxPersistedMessages and older ones are dropped by the Cloudflare
-	* AIChatAgent's built-in hard cap.
-	*
-	* Override to use a cheaper or faster model for summarisation, or to enable
-	* compaction in subclasses that do not override it automatically.
-	*/
-	getCompactionModel() {}
-	/**
-	* Return the D1 database binding for persisting loaded skill state.
-	*
-	* Override in your subclass to return the binding from env:
-	* ```typescript
-	* protected getDB() { return this.env.AGENT_DB; }
-	* ```
-	*
-	* Defaults to undefined — when undefined, loaded skills reset on every new
-	* conversation (skills still work within a turn, just not across turns).
-	*/
-	getDB() {}
-	/**
-	* Optional permission hook. Return false to deny the agent access to a
-	* skill when activate_skill is called. Defaults to allow-all.
-	*/
-	async filterSkill(_skillName) {
-		return true;
+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);
+}
+//#endregion
+//#region src/server/agents/AIChatAgent.ts
+/**
+* Base class for Cloudflare Agents SDK chat agents with lazy skill loading
+* and built-in audit logging.
+*
+* 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.
+*
+* Skill loading, compaction, and LLM communication are delegated to
+* `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
+*/
+var AIChatAgent = class extends AIChatAgent$1 {
+	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");
+			return;
+		}
 	}
-	/** @internal Captured header values, keyed by lowercase name. */
-	_requestHeaders = {};
 	/**
-	* Buffered skill state from the current turn.
-	*
-	* Set by the onSkillsChanged callback when activate_skill loads new skills
-	* mid-turn. Flushed to D1 in persistMessages at turn end — only written
-	* when this value is set, so D1 is not touched on turns where no new skills
-	* are loaded.
+	* Resolves the D1 database binding required for all D1 writes.
+	* Returns null and silently no-ops if AGENT_DB is not bound.
 	*/
-	_pendingSkills;
+	resolveD1Context() {
+		const db = this.env.AGENT_DB;
+		if (!db) {
+			console.error("[AIChatAgent] Skipping logging: D1 database not found");
+			return null;
+		}
+		return db;
+	}
 	/**
-	* Reads loaded skill names from D1 for this agent.
-	*
-	* Returns an empty array if no record exists (first turn, or no skills
-	* loaded yet). Conversation messages are not read here — the Cloudflare
-	* AIChatAgent provides those via this.messages from DO SQLite.
+	* Returns all conversations for the current user.
 	*/
-	async _readSkillState() {
-		const row = await this.getDB()?.prepare("SELECT loaded_skills FROM agent_state WHERE agent_id = ?").bind(this.name).first();
-		if (!row?.loaded_skills) return [];
-		return JSON.parse(row.loaded_skills);
+	@callable() async getConversations() {
+		const db = this.resolveD1Context();
+		if (!db) return;
+		return getConversations(db, this.getUserId());
 	}
 	/**
-	* Writes loaded skill names to D1 for this agent.
+	* Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
+	* otherwise silently does nothing.
 	*
-	* Uses INSERT OR REPLACE so the first skill load creates the row and
-	* subsequent loads update it. Only called when skills actually changed
-	* this turn (_pendingSkills is set).
+	* 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 _writeSkillState(skills) {
-		await this.getDB()?.prepare("INSERT OR REPLACE INTO agent_state (agent_id, loaded_skills, last_updated) VALUES (?, ?, ?)").bind(this.name, JSON.stringify(skills), Date.now()).run();
+	async log(message, payload) {
+		const db = this.resolveD1Context();
+		if (!db) return;
+		await insertAuditEvent(db, this.name, message, payload);
 	}
 	/**
-	* Flush persisted message history to a newly connected client.
-	*
-	* The Cloudflare AIChatAgent broadcasts message updates to existing
-	* connections via persistMessages, but does nothing for connections that
-	* arrive after a conversation has ended. Without this override, a page
-	* refresh produces an empty UI even though the history is intact in DO SQLite.
+	* Records this conversation in the `conversations` D1 table and triggers
+	* LLM-based title/summary generation when appropriate. Called automatically
+	* from `persistMessages` after every turn.
 	*
-	* Skips replay when a stream is active — CF_AGENT_STREAM_RESUMING handles
-	* that case and replays in-progress chunks via its own protocol.
+	* 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 onConnect(connection, ctx) {
-		if (this.passthroughRequestHeaders.length > 0) {
-			this._requestHeaders = {};
-			const params = new URL(ctx.request.url).searchParams;
-			for (const name of this.passthroughRequestHeaders) {
-				const value = params.get(name);
-				if (value !== null) this._requestHeaders[name] = value;
+	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");
 			}
 		}
-		await super.onConnect(connection, ctx);
-		if (!this._activeStreamId && this.messages.length > 0) connection.send(JSON.stringify({
-			type: "cf_agent_chat_messages",
-			messages: this.messages
-		}));
 	}
 	/**
-	* Strips ephemeral content, conditionally saves skill state to D1, then
-	* delegates to super for DO SQLite persistence and WebSocket broadcast.
+	* 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.
 	*
-	* The Cloudflare AIChatAgent calls persistMessages once per turn after all
-	* steps complete, so overriding here is the correct place to act — it runs
-	* after the full assistant message (including all tool results) is assembled.
+	* **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.
 	*
-	* Two things happen here:
+	* ```typescript
+	* // Compaction on (default threshold):
+	* const params = await this.buildLLMParams({ options, onFinish, model, system: "..." });
 	*
-	* 1. Ephemeral tool calls are stripped — list_capabilities (always) and
-	*    activate_skill when nothing was newly loaded (no state change).
+	* // Compaction with custom threshold:
+	* const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: 50 });
 	*
-	* 2. If skills changed this turn (_pendingSkills is set), the updated list
-	*    is written to D1. Turns where no skills were loaded do not touch D1.
+	* // Compaction off:
+	* const params = await this.buildLLMParams({ options, onFinish, model, maxMessagesBeforeCompaction: undefined });
 	*
-	* Message persistence itself is handled by super.persistMessages, which
-	* writes to DO SQLite — no D1 write needed for messages.
+	* return streamText(params).toUIMessageStreamResponse();
+	* ```
 	*/
-	async persistMessages(messages, excludeBroadcastIds = [], options) {
-		const filtered = filterEphemeralMessages(messages);
-		if (this._pendingSkills !== void 0) {
-			await this._writeSkillState(this._pendingSkills);
-			this._pendingSkills = void 0;
-		}
-		const toSave = await compactIfNeeded(filtered, this.getCompactionModel(), this.maxPersistedMessages - 1);
-		return super.persistMessages(toSave, excludeBroadcastIds, options);
+	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);
+		};
+		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)
+			}
+		};
 	}
 	/**
-	* Widened onChatMessage signature that accommodates the @withSkills decorator.
-	*
-	* The decorator transforms the consumer's 3-arg form (onFinish, ctx, options) into
-	* a 2-arg wrapper at runtime. This declaration widens the base class signature so
-	* that TypeScript accepts the consumer's 3-arg override without errors.
-	*
-	* @ts-ignore — intentional: widens the Cloudflare AIChatAgent's (onFinish, options?) signature.
+	* Skill names persisted from previous turns, read from DO SQLite.
+	* Returns an empty array if no skills have been loaded yet.
 	*/
-	onChatMessage(onFinish, ctxOrOptions) {
-		return super.onChatMessage(onFinish, ctxOrOptions);
+	async getLoadedSkills() {
+		return getStoredSkills(this.sql.bind(this));
 	}
 	/**
-	* Called by the @withSkills decorator at the start of each turn.
+	* 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.
 	*
-	* Reads loaded skill state from D1, seeds createSkills, and returns a
-	* SkillContext ready to use in a streamText call.
+	* 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.
 	*
-	* Guidance is exposed as `ctx.guidance` — compose your system prompt as:
-	* `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
-	*
-	* Messages are plain (no guidance injected). Guidance stays out of the
-	* messages array — Anthropic/Gemini only allow system messages at position 0.
-	*/
-	async _prepareSkillContext() {
-		const loadedSkills = await this._readSkillState();
-		const skills = createSkills({
-			tools: this.getTools(),
-			skills: this.getSkills(),
-			initialLoadedSkills: loadedSkills,
-			onSkillsChanged: async (updated) => {
-				this._pendingSkills = updated;
-			},
-			filterSkill: (name) => this.filterSkill(name)
-		});
-		return {
-			tools: skills.tools,
-			activeTools: skills.activeTools,
-			prepareStep: skills.prepareStep,
-			guidance: skills.getLoadedGuidance(),
-			messages: await convertToModelMessages(this.messages),
-			headers: this._requestHeaders
-		};
-	}
-};
-function withSkills(fn, _context) {
-	const wrapper = async function(onFinish, maybeOptions) {
-		const ctx = await this._prepareSkillContext();
-		return fn.call(this, onFinish, ctx, maybeOptions);
-	};
-	return wrapper;
-}
-//#endregion
-//#region src/agents/chat/AIChatAgent.ts
-/**
-* Batteries-included base class for chat agents with lazy skill loading.
-*
-* Owns the full `onChatMessage` lifecycle. Implement four abstract methods and
-* get lazy skill loading, cross-turn skill persistence, guidance injection,
-* ephemeral message cleanup, and message compaction for free.
-*
-* Conversation messages are stored in Durable Object SQLite by the Cloudflare
-* AIChatAgent automatically — available as this.messages at the start of each
-* turn. Loaded skill state is stored in D1 (via getDB()) and read at turn start.
-* Guidance is injected as a system message just before the current user turn,
-* keeping the `system` param static and cacheable across all turns.
-*
-* ```typescript
-* export class MyAgent extends AIChatAgent {
-*   getModel()        { return openai("gpt-4o"); }
-*   getTools()        { return tools; }
-*   getSkills()       { return [searchSkill, codeSkill]; }
-*   getSystemPrompt() { return "You are a helpful assistant."; }
-*   getDB()           { return this.env.AGENT_DB; }
-* }
-* ```
-*
-* ## Passing auth headers to tools
-*
-* Set `passthroughRequestHeaders` to capture headers from the WebSocket upgrade
-* request. They are forwarded automatically to every tool via `experimental_context`:
-*
-* ```typescript
-* passthroughRequestHeaders = ['authorization', 'x-user-id'];
-* ```
-*
-* Tools receive them as the second `execute` argument:
-*
-* ```typescript
-* execute: async (args, { experimental_context }) => {
-*   const { authorization } = experimental_context?.headers ?? {};
-* }
-* ```
-*
-* If you need full control over the `streamText` call (custom model options,
-* streaming transforms, varying the model per request, etc.) use
-* `AIChatAgentBase` with the `@withSkills` decorator instead.
-*/
-var AIChatAgent = class extends AIChatAgentBase {
-	/**
-	* Return the model used for compaction summarisation.
+	* 2. Logs a turn summary via `log()`. Best-effort: fire-and-forget.
 	*
-	* Defaults to getModel() — the agent's primary model — so compaction is
-	* enabled automatically. Override to substitute a cheaper or faster model
-	* for summarisation (e.g. a smaller model when the primary is expensive).
+	* 3. Strips all activate_skill and list_capabilities messages from history.
 	*
-	* To opt out of message compaction: override and return undefined.
+	* 4. Delegates to super.persistMessages for message storage and WS broadcast.
 	*/
-	getCompactionModel() {
-		return this.getModel();
-	}
-	async onChatMessage(onFinish, options) {
-		const loadedSkills = await this._readSkillState();
-		const skills = createSkills({
-			tools: this.getTools(),
-			skills: this.getSkills(),
-			systemPrompt: this.getSystemPrompt(),
-			initialLoadedSkills: loadedSkills,
-			onSkillsChanged: async (updated) => {
-				this._pendingSkills = updated;
-			},
-			filterSkill: (name) => this.filterSkill(name)
-		});
-		return streamText({
-			model: this.getModel(),
-			system: skills.getSystem(),
-			messages: await convertToModelMessages(this.messages),
-			tools: skills.tools,
-			activeTools: skills.activeTools,
-			prepareStep: skills.prepareStep,
-			experimental_context: { headers: this._requestHeaders },
-			stopWhen: stepCountIs(20),
-			abortSignal: options?.abortSignal,
-			onFinish
-		}).toUIMessageStreamResponse();
+	async persistMessages(messages, excludeBroadcastIds = [], options) {
+		let latestSkillState;
+		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, output } = part;
+				if (type !== `tool-activate_skill` || typeof output !== "string") continue;
+				const sentinelIdx = output.indexOf(SKILL_STATE_SENTINEL);
+				if (sentinelIdx !== -1) try {
+					const stateJson = output.slice(sentinelIdx + 18);
+					latestSkillState = JSON.parse(stateJson);
+				} catch {}
+			}
+		}
+		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);
 	}
 };
 //#endregion
-export { AIChatAgent, AIChatAgentBase, COMPACT_TOKEN_THRESHOLD, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };
+export { AIChatAgent, buildLLMParams };