@economic/agents 0.0.1-beta.5 → 0.0.1

package/README.md

@@ -565,24 +565,37 @@ The `conversations` table is created by the same `schema/schema.sql` file used f
 
 ### Upsert behaviour
 
-- **First turn**: a new row is inserted with `created_at` and `updated_at` both set to now. `title` and `summary` are `NULL`.
-- **Subsequent turns**: only `user_id` and `updated_at` are updated. `created_at`, `title`, and `summary` are never overwritten by the upsert.
-- `title` and `summary` are populated automatically after the conversation goes idle (see below).
+- **First turn**: `AIChatAgent` generates `title` and `summary` first, then inserts the row with `created_at` and `updated_at` both set to now and `title`/`summary` already populated.
+- **Subsequent turns**: the upsert only refreshes `updated_at`. `created_at`, `title`, and `summary` are preserved by the upsert path.
+- Every `SUMMARY_CONTEXT_MESSAGES` messages, `AIChatAgent` separately re-generates `title` and `summary` and writes them back without changing `created_at`.
 
 ### Automatic title and summary generation
 
-After every turn, `AIChatAgent` schedules a `generateSummary` callback to fire 30 minutes in the future. If another message arrives before the timer fires, the schedule is cancelled and reset — so the callback only runs once the conversation has been idle for 30 minutes.
+On the first persisted turn, `AIChatAgent` generates a title and summary from the current conversation and inserts them into the new D1 row.
 
-When `generateSummary` fires it:
-
-1. Fetches the current summary from D1 (if any).
-2. Takes the last 30 messages (`SUMMARY_CONTEXT_MESSAGES`) to keep the prompt bounded.
-3. Calls `fastModel` with `Output.object()` to generate a structured `{ title, summary }`.
-4. If a previous summary exists, it is included in the prompt so the model can detect direction changes.
-5. Writes the result back to the `conversations` row.
+On later turns, it always refreshes `updated_at`, and it re-generates the title/summary every `SUMMARY_CONTEXT_MESSAGES` messages using the latest window plus the previous summary.
 
 No subclass code is needed — this runs automatically when `AGENT_DB` is bound and `fastModel` is set on the class.
 
+### Automatic conversation retention
+
+Set `conversationRetentionDays` on your subclass to automatically delete inactive conversations after that many days:
+
+```typescript
+export class MyAgent extends AIChatAgent<Env> {
+  protected fastModel = openai("gpt-4o-mini");
+  protected conversationRetentionDays = 90;
+}
+```
+
+After each persisted turn, the base class resets a per-conversation scheduled callback on the Durable Object. When it fires, the callback:
+
+1. Deletes the matching row from the D1 `conversations` table.
+2. Closes any active WebSocket connections for that conversation.
+3. Wipes the Durable Object's SQLite storage with `deleteAll()`.
+
+If `conversationRetentionDays` is `undefined`, retention cleanup is disabled and old conversation URLs stay resumable indefinitely.
+
 ### Querying conversation lists
 
 From a connected agent client, prefer the built-in callable (see **`getConversations` (callable)** under [`AIChatAgent`](#aichatagent)): `await agent.call("getConversations")`.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
+import { Connection, ConnectionContext } from "agents";
 import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/ai-chat";
 import { LanguageModel, ToolSet, UIMessage, generateText, streamText } from "ai";
-import { Connection, ConnectionContext } from "agents";
 
 //#region src/server/features/skills/index.d.ts
 /**
@@ -26,48 +26,28 @@ interface Skill {
 //#endregion
 //#region src/server/llm.d.ts
 type LLMParams = Parameters<typeof streamText>[0] & Parameters<typeof generateText>[0];
-type BuildLLMParamsConfig = Omit<LLMParams, "messages" | "experimental_context" | "abortSignal"> & {
-  /** CF options object — extracts `abortSignal` and `experimental_context` (from `body`). */options: OnChatMessageOptions | undefined; /** Conversation history (`this.messages`). Converted to `ModelMessage[]` internally. */
-  messages: UIMessage[]; /** Skill names loaded in previous turns. Pass `await this.getLoadedSkills()`. */
-  activeSkills?: string[]; /** Skills available for on-demand loading this turn. */
+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. */
   skills?: Skill[];
-  /**
-   * Number of recent messages to keep verbatim during compaction. Older messages
-   * beyond this count are summarised by `fastModel` before being sent to the LLM.
-   *
-   * Defaults to `DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION` (30) when not provided.
-   * Set explicitly to `undefined` to disable compaction entirely.
-   *
-   * Compaction only runs when `fastModel` is also set on the agent class.
-   *
-   * @internal Injected by `AIChatAgent.buildLLMParams` — do not set this directly.
-   */
-  maxMessagesBeforeCompaction?: number;
-  /**
-   * The fast/cheap model used for compaction and background summarization.
-   * Provided automatically from `AIChatAgent.fastModel` — do not set this directly.
-   *
-   * @internal
-   */
-  fastModel?: LanguageModel;
 };
 /**
  * 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();
  * ```
  */
-declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams>;
+declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
 //#endregion
 //#region src/server/agents/AIChatAgent.d.ts
+interface AIChatAgentEnv {
+  AGENT_DB: D1Database;
+}
 /**
  * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
  * and built-in audit logging.
@@ -79,7 +59,7 @@ declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams
  * Skill loading, compaction, and LLM communication are delegated to
  * `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
  */
-declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends AIChatAgent$1<Env> {
+declare abstract class AIChatAgent<Env extends Cloudflare.Env & AIChatAgentEnv = Cloudflare.Env & AIChatAgentEnv> extends AIChatAgent$1<Env> {
   /**
    * Fast/cheap language model used for background tasks: compaction and conversation summarization.
    *
@@ -93,17 +73,25 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
    */
   protected abstract fastModel: LanguageModel;
-  protected getUserId(): string;
-  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
-   * Resolves the D1 database binding required for all D1 writes.
-   * Returns null and silently no-ops if AGENT_DB is not bound.
+   * Number of days of inactivity before the full conversation is deleted.
+   *
+   * Leave `undefined` to disable automatic retention cleanup.
+   */
+  protected conversationRetentionDays?: number;
+  /**
+   * 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.
    */
-  private resolveD1Context;
+  protected maxMessagesBeforeCompaction?: number | undefined;
   /**
-   * Returns all conversations for the current user.
+   * Returns the user ID from the durable object name.
    */
-  getConversations(): Promise<Record<string, unknown>[] | undefined>;
+  protected getUserId(): string;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
    * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
    * otherwise silently does nothing.
@@ -113,18 +101,6 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    * `experimental_context.log` in tool `execute` functions.
    */
   protected log(message: string, payload?: Record<string, unknown>): Promise<void>;
-  /**
-   * 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.
-   */
-  private recordConversation;
   /**
    * Builds the parameter object for a `streamText` or `generateText` call,
    * pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
@@ -132,28 +108,13 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    *
    * **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.
    * ```
    */
-  protected buildLLMParams<TBody = Record<string, unknown>>(config: Omit<BuildLLMParamsConfig, "messages" | "activeSkills" | "fastModel">): ReturnType<typeof buildLLMParams>;
-  /**
-   * Skill names persisted from previous turns, read from DO SQLite.
-   * Returns an empty array if no skills have been loaded yet.
-   */
-  protected getLoadedSkills(): Promise<string[]>;
+  protected buildLLMParams<TBody = Record<string, unknown>>(config: BuildLLMParamsConfig & {
+    options?: OnChatMessageOptions;
+  }): Promise<LLMParams>;
   /**
    * Extracts skill state from activate_skill results, persists to DO SQLite,
    * logs a turn summary, then strips all skill meta-tool messages before
@@ -171,6 +132,22 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
   persistMessages(messages: UIMessage[], excludeBroadcastIds?: string[], options?: {
     _deleteStaleRows?: boolean;
   }): Promise<void>;
+  getConversations(): Promise<Record<string, unknown>[]>;
+  /**
+   * 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.
+   */
+  private recordConversation;
+  private deleteConversation;
+  private scheduleConversationForDeletion;
+  private clearConversationMemoryState;
 }
 //#endregion
 //#region src/server/types.d.ts

package/dist/index.mjs

@@ -1,35 +1,10 @@
+import { callable } from "agents";
 import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
 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 '[]')`;
-}
-/**
-* 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,46 +221,41 @@ 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,
+		system,
+		tools,
 		experimental_transform: composedTransform,
-		messages: processedMessages,
-		experimental_context: options?.body,
-		abortSignal: options?.abortSignal,
 		stopWhen: rest.stopWhen ?? stepCountIs(20)
 	};
 	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
@@ -415,39 +272,111 @@ 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();
 }
+const TOOL_RESULT_PREVIEW_CHARS = 200;
+const SUMMARY_MAX_TOKENS = 4e3;
 /**
-* Builds the payload for a "turn completed" audit event from the final message list.
-*
-* 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.
+* 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);
 }
-function extractMessageText(msg) {
-	if (!msg?.parts) return "";
-	return msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ").trim();
+/**
+* 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");
+}
+/**
+* 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.
 *
@@ -480,6 +409,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) {
@@ -535,6 +470,25 @@ async function generateConversationSummary(db, durableObjectName, messages, mode
 	await updateConversationSummary(db, durableObjectName, title, summary);
 }
 //#endregion
+//#region src/server/features/conversations/retention.ts
+const DELETE_CONVERSATION_CALLBACK = "deleteConversation";
+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);
+}
+function clearConversationRuntimeState(state) {
+	for (const controller of state.chatMessageAbortControllers?.values() ?? []) controller.abort();
+	state.messages.length = 0;
+	state.clearResumableStream();
+	state.chatMessageAbortControllers?.clear();
+	state.pendingResumeConnections?.clear();
+}
+//#endregion
 //#region src/server/agents/AIChatAgent.ts
 /**
 * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
@@ -548,36 +502,38 @@ async function generateConversationSummary(db, durableObjectName, messages, mode
 * `buildLLMParams` from `@economic/agents`, which you call inside `onChatMessage`.
 */
 var AIChatAgent = class extends AIChatAgent$1 {
+	/**
+	* 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.env.AGENT_DB) {
+			console.error("[AIChatAgent] Connection rejected: no AGENT_DB bound");
+			connection.close(3e3, "Could not connect to agent, database not found");
+			return;
+		}
 		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");
+			connection.close(3e3, "Could not connect to agent, name is not in correct format");
 			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;
-		}
-		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,
@@ -588,34 +544,10 @@ var AIChatAgent = class extends AIChatAgent$1 {
 	* `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.
-	*/
-	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");
-			}
+		try {
+			await insertAuditEvent(this.env.AGENT_DB, this.name, message, payload);
+		} catch (error) {
+			console.error("[AIChatAgent] Failed to write audit event", error);
 		}
 	}
 	/**
@@ -625,49 +557,24 @@ var AIChatAgent = class extends AIChatAgent$1 {
 	*
 	* **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);
-		};
-		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 activeSkills = await getStoredSkills(this.sql.bind(this));
+		const context = {
+			...config.options?.body,
+			log: this.log.bind(this)
 		};
-	}
-	/**
-	* 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));
+		const messages = await convertToModelMessages(this.messages);
+		const processedMessages = this.fastModel && this.maxMessagesBeforeCompaction !== void 0 ? await compactIfNeeded(messages, this.fastModel, this.maxMessagesBeforeCompaction) : messages;
+		return buildLLMParams({
+			...config,
+			activeSkills,
+			messages: processedMessages,
+			experimental_context: context
+		});
 	}
 	/**
 	* Extracts skill state from activate_skill results, persists to DO SQLite,
@@ -699,11 +606,115 @@ 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.recordConversation(filtered);
+		this.scheduleConversationForDeletion();
+		this.log("turn completed", buildTurnSummaryForLog(messages, latestSkillState ?? []));
+		return result;
+	}
+	@callable({ description: "Returns all conversations for the current user" }) async getConversations() {
+		return getConversations(this.env.AGENT_DB, this.getUserId());
+	}
+	/**
+	* 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.
+	*/
+	async recordConversation(messages) {
+		if (!await getConversationSummary(this.env.AGENT_DB, this.name)) {
+			const { title, summary } = await generateTitleAndSummary(messages, this.fastModel);
+			await recordConversation(this.env.AGENT_DB, this.name, title, summary);
+			this.log("[AIChatAgent] Conversation summary generated");
+		} else {
+			await recordConversation(this.env.AGENT_DB, this.name);
+			if (messages.length % 30 === 0) {
+				generateConversationSummary(this.env.AGENT_DB, this.name, messages, this.fastModel);
+				this.log("[AIChatAgent] Conversation summary updated");
+			}
+		}
+	}
+	async deleteConversation() {
+		try {
+			await deleteConversationRow(this.env.AGENT_DB, this.name);
+		} catch (error) {
+			console.error("[AIChatAgent] Failed to delete conversation row", {
+				conversationName: this.name,
+				error
+			});
+			return;
+		}
+		for (const connection of this.getConnections()) try {
+			connection.close(CONVERSATION_EXPIRED_CLOSE_CODE, CONVERSATION_EXPIRED_CLOSE_REASON);
+		} catch (error) {
+			console.error("[AIChatAgent] Failed to close expired conversation connection", error);
+		}
+		this.clearConversationMemoryState();
+		await this.ctx.storage.deleteAll();
+		this.log("[AiChatAgent] 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);
+	}
+	clearConversationMemoryState() {
+		const mutableState = this;
+		clearConversationRuntimeState({
+			chatMessageAbortControllers: mutableState._chatMessageAbortControllers,
+			clearResumableStream: () => this._resumableStream.clearAll(),
+			messages: mutableState.messages,
+			pendingResumeConnections: mutableState._pendingResumeConnections
+		});
+		mutableState._approvalPersistedMessageId = null;
+		mutableState._lastBody = void 0;
+		mutableState._lastClientTools = void 0;
+		mutableState._streamCompletionPromise = null;
+		mutableState._streamCompletionResolve = null;
+		mutableState._streamingMessage = null;
 	}
 };
+/**
+* Builds the payload for a "turn completed" audit event from the final message list.
+*
+* 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 buildTurnSummaryForLog(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
 export { AIChatAgent, buildLLMParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-beta.5",
+  "version": "0.0.1",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [
@@ -8,6 +8,7 @@
     "schema"
   ],
   "type": "module",
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
     "./react": "./dist/react.mjs",