agents 0.8.6 → 0.8.7

package/dist/experimental/memory/session/index.js

@@ -1,376 +1,755 @@
-//#region src/experimental/memory/utils/compaction.ts
-/** Default thresholds for microCompaction rules (in chars) */
-const DEFAULTS = {
-	truncateToolOutputs: 3e4,
-	truncateText: 1e4,
-	keepRecent: 4
-};
-/**
-* Parse microCompaction config into resolved rules.
-* Returns null if disabled.
-*/
-function parseMicroCompactionRules(config) {
-	if (config === false) return null;
-	if (config === true) return {
-		truncateToolOutputs: DEFAULTS.truncateToolOutputs,
-		truncateText: DEFAULTS.truncateText,
-		keepRecent: DEFAULTS.keepRecent
-	};
-	const keepRecent = config.keepRecent ?? DEFAULTS.keepRecent;
-	if (!Number.isInteger(keepRecent) || keepRecent < 0) throw new Error("keepRecent must be a non-negative integer");
-	const truncateToolOutputs = config.truncateToolOutputs === false ? false : config.truncateToolOutputs === true || config.truncateToolOutputs === void 0 ? DEFAULTS.truncateToolOutputs : config.truncateToolOutputs;
-	if (typeof truncateToolOutputs === "number" && truncateToolOutputs <= 0) throw new Error("truncateToolOutputs must be a positive number");
-	const truncateText = config.truncateText === false ? false : config.truncateText === true || config.truncateText === void 0 ? DEFAULTS.truncateText : config.truncateText;
-	if (typeof truncateText === "number" && truncateText <= 0) throw new Error("truncateText must be a positive number");
-	return {
-		truncateToolOutputs,
-		truncateText,
-		keepRecent
-	};
-}
+import { MessageType } from "../../../types.js";
+import { m as estimateStringTokens, p as estimateMessageTokens, t as COMPACTION_PREFIX } from "../../../compaction-helpers-BFTBIzpK.js";
+import { jsonSchema } from "ai";
+//#region src/experimental/memory/session/context.ts
 /**
-* Truncate oversized parts in a single message.
-* Returns the same reference if nothing changed (allows callers to skip no-op updates).
-*/
-function truncateMessageParts(msg, rules) {
-	let changed = false;
-	const compactedParts = msg.parts.map((part) => {
-		if (rules.truncateToolOutputs !== false && (part.type.startsWith("tool-") || part.type === "dynamic-tool") && "output" in part) {
-			const toolPart = part;
-			if (toolPart.output !== void 0) {
-				const outputJson = JSON.stringify(toolPart.output);
-				if (outputJson.length > rules.truncateToolOutputs) {
-					changed = true;
-					return {
-						...part,
-						output: `[Truncated ${outputJson.length} bytes] ${outputJson.slice(0, 500)}...`
-					};
-				}
-			}
-		}
-		if (rules.truncateText !== false && part.type === "text" && "text" in part) {
-			const textPart = part;
-			if (textPart.text.length > rules.truncateText) {
-				changed = true;
-				return {
-					...part,
-					text: `${textPart.text.slice(0, rules.truncateText)}... [truncated ${textPart.text.length} chars]`
-				};
-			}
-		}
-		return part;
-	});
-	return changed ? {
-		...msg,
-		parts: compactedParts
-	} : msg;
-}
-/**
-* Apply microCompaction to an array of messages.
-* Returns same reference for unchanged messages (enables skip-update optimization).
+* Context Block Management
 *
-* No keepRecent logic — the caller decides which messages to pass.
+* Persistent key-value blocks (MEMORY, USER, SOUL, etc.) that are:
+* - Loaded from their providers at init
+* - Frozen into a snapshot when toSystemPrompt() is called
+* - Updated via setBlock() which writes to the provider immediately
+*   but does NOT update the frozen snapshot (preserves LLM prefix cache)
+* - Re-snapshotted on next toSystemPrompt() call
 */
-function microCompact(messages, rules) {
-	return messages.map((msg) => truncateMessageParts(msg, rules));
-}
-/** Approximate token multiplier per whitespace-separated word */
-const WORDS_TOKEN_MULTIPLIER = 1.3;
 /**
-* Estimate token count for a string using a hybrid heuristic.
-*
-* Takes the max of two estimates:
-* - Character-based: `length / 4` — better for dense content (JSON, code, URLs)
-* - Word-based: `words * 1.3` — better for natural language prose
-*
-* This is a heuristic. Do not use where exact counts are required.
+* Manages context blocks with frozen snapshot support.
 */
-function estimateStringTokens(text) {
-	if (!text) return 0;
-	const charEstimate = text.length / 4;
-	const wordEstimate = text.split(/\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;
-	return Math.ceil(Math.max(charEstimate, wordEstimate));
-}
-/**
-* Estimate total token count for an array of UIMessages.
-*
-* Walks each message's parts (text, tool invocations, tool results)
-* and applies per-message overhead.
-*
-* This is a heuristic. Do not use where exact counts are required.
-*/
-function estimateMessageTokens(messages) {
-	let tokens = 0;
-	for (const msg of messages) {
-		tokens += 4;
-		for (const part of msg.parts) if (part.type === "text") tokens += estimateStringTokens(part.text);
-		else if (part.type.startsWith("tool-") || part.type === "dynamic-tool") {
-			const toolPart = part;
-			if (toolPart.input) tokens += estimateStringTokens(JSON.stringify(toolPart.input));
-			if (toolPart.output) tokens += estimateStringTokens(JSON.stringify(toolPart.output));
+var ContextBlocks = class {
+	constructor(configs, promptStore) {
+		this.blocks = /* @__PURE__ */ new Map();
+		this.snapshot = null;
+		this.loaded = false;
+		this.configs = configs;
+		this.promptStore = promptStore ?? null;
+	}
+	isLoaded() {
+		return this.loaded;
+	}
+	/**
+	* Load all blocks from their providers.
+	* Called once at session init.
+	*/
+	async load() {
+		for (const config of this.configs) {
+			let content = null;
+			if (config.provider) content = await config.provider.get();
+			content = content ?? config.initialContent ?? "";
+			this.blocks.set(config.label, {
+				label: config.label,
+				description: config.description,
+				content,
+				tokens: estimateStringTokens(content),
+				maxTokens: config.maxTokens,
+				readonly: config.readonly
+			});
 		}
+		this.loaded = true;
 	}
-	return tokens;
-}
-//#endregion
-//#region src/experimental/memory/session/session.ts
-var Session = class {
-	constructor(storage, options) {
-		this.storage = storage;
-		this.microCompactionRules = parseMicroCompactionRules(options?.microCompaction ?? true);
-		this.compactionConfig = options?.compaction ?? null;
+	/**
+	* Get a block by label.
+	*/
+	getBlock(label) {
+		return this.blocks.get(label) ?? null;
 	}
-	getMessages(options) {
-		return this.storage.getMessages(options);
+	/**
+	* Get all blocks.
+	*/
+	getBlocks() {
+		return Array.from(this.blocks.values());
 	}
-	getMessage(id) {
-		return this.storage.getMessage(id);
+	/**
+	* Set block content. Writes to provider immediately.
+	* Does NOT update the frozen snapshot.
+	*/
+	async setBlock(label, content) {
+		if (!this.loaded) await this.load();
+		const config = this.configs.find((c) => c.label === label);
+		const existing = this.blocks.get(label);
+		if (existing?.readonly || config?.readonly) throw new Error(`Block "${label}" is readonly`);
+		const tokens = estimateStringTokens(content);
+		const maxTokens = config?.maxTokens ?? existing?.maxTokens;
+		if (maxTokens !== void 0 && tokens > maxTokens) throw new Error(`Block "${label}" exceeds maxTokens: ${tokens} > ${maxTokens}`);
+		const block = {
+			label,
+			description: config?.description ?? existing?.description,
+			content,
+			tokens,
+			maxTokens,
+			readonly: false
+		};
+		this.blocks.set(label, block);
+		if (config?.provider?.set) await config.provider.set(content);
+		return block;
 	}
-	getLastMessages(n) {
-		return this.storage.getLastMessages(n);
+	/**
+	* Append content to a block.
+	*/
+	async appendToBlock(label, content) {
+		if (!this.loaded) await this.load();
+		const existing = this.blocks.get(label);
+		if (!existing) throw new Error(`Block "${label}" not found`);
+		return this.setBlock(label, existing.content + content);
 	}
-	async append(messages) {
-		await this.storage.appendMessages(messages);
-		if (this.shouldAutoCompact()) {
-			if ((await this.compact()).success) return;
-		}
-		if (this.microCompactionRules) {
-			const rules = this.microCompactionRules;
-			const older = this.storage.getOlderMessages(rules.keepRecent);
-			if (older.length > 0) {
-				const compacted = microCompact(older, rules);
-				for (let i = 0; i < older.length; i++) if (compacted[i] !== older[i]) this.storage.updateMessage(compacted[i]);
+	/**
+	* Get the system prompt string with context blocks.
+	*
+	* Returns a frozen snapshot: first call renders and caches,
+	* subsequent calls return the same string (preserves LLM prefix cache).
+	* Call refreshSnapshot() to re-render after block changes take effect.
+	*/
+	toSystemPrompt() {
+		if (!this.loaded) throw new Error("Context blocks not loaded. Call load() first.");
+		if (this.snapshot !== null) return this.snapshot;
+		return this.captureSnapshot();
+	}
+	/**
+	* Force re-render the snapshot from current block state.
+	* Call this at the start of a new session to pick up changes
+	* made by setBlock() during the previous session.
+	*/
+	refreshSnapshot() {
+		return this.captureSnapshot();
+	}
+	captureSnapshot() {
+		const parts = [];
+		const sep = "═".repeat(46);
+		for (const block of this.blocks.values()) {
+			if (!block.content) continue;
+			let header = block.label.toUpperCase();
+			if (block.description) header += ` (${block.description})`;
+			if (block.maxTokens) {
+				const pct = Math.round(block.tokens / block.maxTokens * 100);
+				header += ` [${pct}% — ${block.tokens}/${block.maxTokens} tokens]`;
 			}
+			if (block.readonly) header += " [readonly]";
+			parts.push(`${sep}\n${header}\n${sep}\n${block.content}`);
 		}
+		this.snapshot = parts.join("\n\n");
+		return this.snapshot;
 	}
-	updateMessage(message) {
-		this.storage.updateMessage(message);
-	}
-	deleteMessages(messageIds) {
-		this.storage.deleteMessages(messageIds);
+	/**
+	* Get writable blocks (for tool description).
+	*/
+	getWritableBlocks() {
+		return Array.from(this.blocks.values()).filter((b) => !b.readonly);
 	}
-	clearMessages() {
-		this.storage.clearMessages();
+	/**
+	* Get writable block configs — doesn't require blocks to be loaded.
+	*/
+	getWritableConfigs() {
+		return this.configs.filter((c) => !c.readonly);
 	}
-	async compact() {
-		const messages = this.storage.getMessages();
-		if (messages.length === 0) return { success: true };
-		try {
-			let result = messages;
-			if (this.compactionConfig?.fn) result = await this.compactionConfig.fn(result);
-			await this.storage.replaceMessages(result);
-			return { success: true };
-		} catch (err) {
-			return {
-				success: false,
-				error: err instanceof Error ? err.message : String(err)
-			};
+	/**
+	* Frozen system prompt. On first call:
+	* 1. Checks store for a persisted prompt (survives DO eviction)
+	* 2. If none, loads blocks from providers, renders, and persists
+	*
+	* Subsequent calls return the stored version — true prefix cache stability.
+	*/
+	async freezeSystemPrompt() {
+		if (this.promptStore) {
+			const stored = await this.promptStore.get();
+			if (stored !== null) return stored;
 		}
+		if (!this.loaded) await this.load();
+		const prompt = this.toSystemPrompt();
+		if (this.promptStore?.set) await this.promptStore.set(prompt);
+		return prompt;
 	}
 	/**
-	* Pre-check for auto-compaction using token estimate heuristic.
+	* Re-render the system prompt from current block state and persist.
+	* Call after compaction or at session boundaries to pick up writes.
 	*/
-	shouldAutoCompact() {
-		if (!this.compactionConfig?.tokenThreshold) return false;
-		return estimateMessageTokens(this.storage.getMessages()) > this.compactionConfig.tokenThreshold;
+	async refreshSystemPrompt() {
+		if (!this.loaded) await this.load();
+		const prompt = this.refreshSnapshot();
+		if (this.promptStore?.set) await this.promptStore.set(prompt);
+		return prompt;
+	}
+	/**
+	* AI tool for updating context blocks. Loads blocks lazily on first execute.
+	*/
+	async tools() {
+		if (!this.loaded) await this.load();
+		const writable = this.getWritableBlocks();
+		if (writable.length === 0) return {};
+		const blockDescriptions = writable.map((b) => `- "${b.label}": ${b.description ?? "no description"}`).join("\n");
+		const ctx = this;
+		return { update_context: {
+			description: `Update a context block. Available blocks:\n${blockDescriptions}\n\nWrites are durable and persist across sessions.`,
+			inputSchema: jsonSchema({
+				type: "object",
+				properties: {
+					label: {
+						type: "string",
+						enum: writable.map((b) => b.label),
+						description: "Block label to update"
+					},
+					content: {
+						type: "string",
+						description: "Content to write"
+					},
+					action: {
+						type: "string",
+						enum: ["replace", "append"],
+						description: "replace (default) or append"
+					}
+				},
+				required: ["label", "content"]
+			}),
+			execute: async ({ label, content, action }) => {
+				try {
+					const block = action === "append" ? await ctx.appendToBlock(label, content) : await ctx.setBlock(label, content);
+					return `Written to ${label}. Usage: ${block.maxTokens ? `${Math.round(block.tokens / block.maxTokens * 100)}% (${block.tokens}/${block.maxTokens} tokens)` : `${block.tokens} tokens`}`;
+				} catch (err) {
+					return `Error: ${err instanceof Error ? err.message : String(err)}`;
+				}
+			}
+		} };
 	}
 };
 //#endregion
 //#region src/experimental/memory/session/providers/agent.ts
-/**
-* Session provider that wraps an Agent's SQLite storage.
-* Provides pure CRUD — compaction is handled by the Session wrapper.
-*
-* @example
-* ```typescript
-* import { Session, AgentSessionProvider } from "agents/experimental/memory/session";
-*
-* // In your Agent class:
-* session = new Session(new AgentSessionProvider(this));
-*
-* // With compaction options:
-* session = new Session(new AgentSessionProvider(this), {
-*   microCompaction: { truncateToolOutputs: 2000, keepRecent: 10 },
-*   compaction: { tokenThreshold: 20000, fn: summarize }
-* });
-* ```
-*/
 var AgentSessionProvider = class {
-	constructor(agent) {
+	/**
+	* @param agent - Agent or any object with a `sql` tagged template method
+	* @param sessionId - Optional session ID to isolate multiple sessions in the same DO.
+	*                    Messages are filtered by session_id within shared tables.
+	*/
+	constructor(agent, sessionId) {
 		this.initialized = false;
 		this.agent = agent;
+		this.sessionId = sessionId ?? "";
 	}
-	/**
-	* Ensure the messages table exists
-	*/
 	ensureTable() {
 		if (this.initialized) return;
 		this.agent.sql`
-      CREATE TABLE IF NOT EXISTS cf_agents_session_messages (
+      CREATE TABLE IF NOT EXISTS assistant_messages (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL DEFAULT '',
+        parent_id TEXT,
+        role TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `;
+		this.agent.sql`
+      CREATE INDEX IF NOT EXISTS idx_assistant_msg_parent
+      ON assistant_messages(parent_id)
+    `;
+		this.agent.sql`
+      CREATE INDEX IF NOT EXISTS idx_assistant_msg_session
+      ON assistant_messages(session_id)
+    `;
+		this.agent.sql`
+      CREATE TABLE IF NOT EXISTS assistant_compactions (
         id TEXT PRIMARY KEY,
-        message TEXT NOT NULL,
+        session_id TEXT NOT NULL DEFAULT '',
+        summary TEXT NOT NULL,
+        from_message_id TEXT NOT NULL,
+        to_message_id TEXT NOT NULL,
         created_at DATETIME DEFAULT CURRENT_TIMESTAMP
       )
+    `;
+		this.agent.sql`
+      CREATE VIRTUAL TABLE IF NOT EXISTS assistant_fts
+      USING fts5(id UNINDEXED, session_id UNINDEXED, role UNINDEXED, content, tokenize='porter unicode61')
+    `;
+		this.agent.sql`
+      CREATE TABLE IF NOT EXISTS assistant_config (
+        session_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        PRIMARY KEY (session_id, key)
+      )
     `;
 		this.initialized = true;
 	}
-	/**
-	* Get all messages in AI SDK format
-	*/
-	getMessages(options) {
+	getMessage(id) {
+		this.ensureTable();
+		const rows = this.agent.sql`
+      SELECT content FROM assistant_messages WHERE id = ${id} AND session_id = ${this.sessionId}
+    `;
+		return rows.length > 0 ? this.parse(rows[0].content) : null;
+	}
+	getHistory(leafId) {
+		this.ensureTable();
+		const leaf = leafId ? this.agent.sql`
+          SELECT id FROM assistant_messages WHERE id = ${leafId} AND session_id = ${this.sessionId}
+        `[0] : this.latestLeafRow();
+		if (!leaf) return [];
+		const path = this.agent.sql`
+      WITH RECURSIVE path AS (
+        SELECT *, 0 as depth FROM assistant_messages WHERE id = ${leaf.id}
+        UNION ALL
+        SELECT m.*, p.depth + 1 FROM assistant_messages m
+        JOIN path p ON m.id = p.parent_id
+        WHERE m.session_id = ${this.sessionId} AND p.depth < 10000
+      )
+      SELECT content FROM path ORDER BY depth DESC
+    `;
+		const messages = this.parseRows(path);
+		const compactions = this.getCompactions();
+		if (compactions.length === 0) return messages;
+		return this.applyCompactions(messages, compactions);
+	}
+	getLatestLeaf() {
+		this.ensureTable();
+		const row = this.latestLeafRow();
+		return row ? this.parse(row.content) : null;
+	}
+	getBranches(messageId) {
 		this.ensureTable();
-		if (options?.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 0)) throw new Error("limit must be a non-negative integer");
-		if (options?.offset !== void 0 && (!Number.isInteger(options.offset) || options.offset < 0)) throw new Error("offset must be a non-negative integer");
-		const role = options?.role ?? null;
-		const before = options?.before?.toISOString() ?? null;
-		const after = options?.after?.toISOString() ?? null;
-		const limit = options?.limit ?? -1;
-		const offset = options?.offset ?? 0;
 		const rows = this.agent.sql`
-      SELECT id, message, created_at FROM cf_agents_session_messages
-      WHERE (${role} IS NULL OR json_extract(message, '$.role') = ${role})
-        AND (${before} IS NULL OR created_at < ${before})
-        AND (${after} IS NULL OR created_at > ${after})
-      ORDER BY created_at ASC, rowid ASC
-      LIMIT ${limit} OFFSET ${offset}
+      SELECT content FROM assistant_messages
+      WHERE parent_id = ${messageId} AND session_id = ${this.sessionId} ORDER BY created_at ASC
     `;
 		return this.parseRows(rows);
 	}
-	/**
-	* Append one or more messages to storage.
-	*/
-	async appendMessages(messages) {
+	getPathLength(leafId) {
 		this.ensureTable();
-		const messageArray = Array.isArray(messages) ? messages : [messages];
-		const now = (/* @__PURE__ */ new Date()).toISOString();
-		for (const message of messageArray) {
-			const json = JSON.stringify(message);
-			this.agent.sql`
-        INSERT INTO cf_agents_session_messages (id, message, created_at)
-        VALUES (${message.id}, ${json}, ${now})
-        ON CONFLICT(id) DO UPDATE SET message = excluded.message
-      `;
+		const leaf = leafId ? this.agent.sql`
+          SELECT id FROM assistant_messages WHERE id = ${leafId} AND session_id = ${this.sessionId}
+        `[0] : this.latestLeafRow();
+		if (!leaf) return 0;
+		return this.agent.sql`
+      WITH RECURSIVE path AS (
+        SELECT id, parent_id, 0 as depth FROM assistant_messages WHERE id = ${leaf.id}
+        UNION ALL
+        SELECT m.id, m.parent_id, p.depth + 1 FROM assistant_messages m
+        JOIN path p ON m.id = p.parent_id
+        WHERE m.session_id = ${this.sessionId} AND p.depth < 10000
+      )
+      SELECT COUNT(*) as count FROM path
+    `[0]?.count ?? 0;
+	}
+	appendMessage(message, parentId) {
+		this.ensureTable();
+		if (this.agent.sql`
+      SELECT id FROM assistant_messages WHERE id = ${message.id} AND session_id = ${this.sessionId}
+    `.length > 0) return;
+		let parent = parentId ?? this.latestLeafRow()?.id ?? null;
+		if (parent) {
+			if (this.agent.sql`
+        SELECT id FROM assistant_messages WHERE id = ${parent} AND session_id = ${this.sessionId}
+      `.length === 0) parent = null;
 		}
+		const json = JSON.stringify(message);
+		this.agent.sql`
+      INSERT INTO assistant_messages (id, session_id, parent_id, role, content)
+      VALUES (${message.id}, ${this.sessionId}, ${parent}, ${message.role}, ${json})
+    `;
+		this.indexFTS(message);
 	}
-	/**
-	* Update an existing message
-	*/
 	updateMessage(message) {
 		this.ensureTable();
-		const json = JSON.stringify(message);
 		this.agent.sql`
-      UPDATE cf_agents_session_messages
-      SET message = ${json}
-      WHERE id = ${message.id}
+      UPDATE assistant_messages SET content = ${JSON.stringify(message)}
+      WHERE id = ${message.id} AND session_id = ${this.sessionId}
     `;
+		this.indexFTS(message);
 	}
-	/**
-	* Delete messages by their IDs
-	*/
 	deleteMessages(messageIds) {
 		this.ensureTable();
-		for (const id of messageIds) this.agent.sql`DELETE FROM cf_agents_session_messages WHERE id = ${id}`;
+		for (const id of messageIds) {
+			this.agent.sql`DELETE FROM assistant_messages WHERE id = ${id} AND session_id = ${this.sessionId}`;
+			this.deleteFTS(id);
+		}
 	}
-	/**
-	* Clear all messages from the session
-	*/
 	clearMessages() {
 		this.ensureTable();
-		this.agent.sql`DELETE FROM cf_agents_session_messages`;
+		this.agent.sql`DELETE FROM assistant_messages WHERE session_id = ${this.sessionId}`;
+		this.agent.sql`DELETE FROM assistant_compactions WHERE session_id = ${this.sessionId}`;
+		const ftsRows = this.agent.sql`
+      SELECT rowid FROM assistant_fts WHERE session_id = ${this.sessionId}
+    `;
+		for (const row of ftsRows) this.agent.sql`DELETE FROM assistant_fts WHERE rowid = ${row.rowid}`;
 	}
-	/**
-	* Get a single message by ID
-	*/
-	getMessage(id) {
+	addCompaction(summary, fromMessageId, toMessageId) {
 		this.ensureTable();
-		const rows = this.agent.sql`
-      SELECT message FROM cf_agents_session_messages WHERE id = ${id}
+		const id = crypto.randomUUID();
+		this.agent.sql`
+      INSERT INTO assistant_compactions (id, session_id, summary, from_message_id, to_message_id)
+      VALUES (${id}, ${this.sessionId}, ${summary}, ${fromMessageId}, ${toMessageId})
     `;
-		if (rows.length === 0) return null;
+		return {
+			id,
+			summary,
+			fromMessageId,
+			toMessageId,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+	getCompactions() {
+		this.ensureTable();
+		return this.agent.sql`
+      SELECT * FROM assistant_compactions WHERE session_id = ${this.sessionId} ORDER BY created_at ASC
+    `.map((r) => ({
+			id: r.id,
+			summary: r.summary,
+			fromMessageId: r.from_message_id,
+			toMessageId: r.to_message_id,
+			createdAt: r.created_at
+		}));
+	}
+	searchMessages(query, limit = 20) {
+		this.ensureTable();
+		const sanitized = `"${query.replace(/"/g, "\"\"")}"`;
 		try {
-			const parsed = JSON.parse(rows[0].message);
-			return this.isValidMessage(parsed) ? parsed : null;
+			return this.agent.sql`
+        SELECT f.id, f.role, f.content FROM assistant_fts f
+        INNER JOIN assistant_messages m ON m.id = f.id AND m.session_id = f.session_id
+        WHERE assistant_fts MATCH ${sanitized} AND f.session_id = ${this.sessionId}
+        ORDER BY rank LIMIT ${limit}
+      `.map((r) => ({
+				id: r.id,
+				role: r.role,
+				content: r.content
+			}));
 		} catch {
-			return null;
+			return [];
 		}
 	}
-	/**
-	* Get the last N messages (most recent)
-	*/
-	getLastMessages(n) {
-		this.ensureTable();
+	latestLeafRow() {
+		return this.agent.sql`
+      SELECT m.id, m.content FROM assistant_messages m
+      LEFT JOIN assistant_messages c ON c.parent_id = m.id AND c.session_id = ${this.sessionId}
+      WHERE c.id IS NULL AND m.session_id = ${this.sessionId}
+      ORDER BY m.created_at DESC, m.rowid DESC LIMIT 1
+    `[0] ?? null;
+	}
+	indexFTS(message) {
+		const text = message.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ");
+		this.deleteFTS(message.id);
+		if (text) this.agent.sql`
+        INSERT INTO assistant_fts (id, session_id, role, content)
+        VALUES (${message.id}, ${this.sessionId}, ${message.role}, ${text})
+      `;
+	}
+	deleteFTS(id) {
 		const rows = this.agent.sql`
-      SELECT message FROM cf_agents_session_messages
-      ORDER BY created_at DESC, rowid DESC
-      LIMIT ${n}
+      SELECT rowid FROM assistant_fts WHERE id = ${id} AND session_id = ${this.sessionId}
     `;
-		return this.parseRows([...rows].reverse());
+		for (const row of rows) this.agent.sql`DELETE FROM assistant_fts WHERE rowid = ${row.rowid}`;
 	}
-	/**
-	* Fetch messages outside the recent window (for microCompaction).
-	* Returns all messages except the most recent `keepRecent`.
-	*/
-	getOlderMessages(keepRecent) {
-		this.ensureTable();
-		const rows = this.agent.sql`
-      SELECT id, message FROM cf_agents_session_messages
-      WHERE rowid NOT IN (
-        SELECT rowid FROM cf_agents_session_messages
-        ORDER BY created_at DESC, rowid DESC
-        LIMIT ${keepRecent}
+	applyCompactions(messages, compactions) {
+		const ids = messages.map((m) => m.id);
+		const result = [];
+		let i = 0;
+		while (i < messages.length) {
+			const matching = compactions.filter((c) => c.fromMessageId === ids[i]);
+			const comp = matching.length > 1 ? matching[matching.length - 1] : matching[0];
+			if (comp) {
+				const endIdx = ids.indexOf(comp.toMessageId);
+				if (endIdx >= i) {
+					result.push({
+						id: `${COMPACTION_PREFIX}${comp.id}`,
+						role: "assistant",
+						parts: [{
+							type: "text",
+							text: comp.summary
+						}],
+						createdAt: /* @__PURE__ */ new Date()
+					});
+					i = endIdx + 1;
+					continue;
+				}
+			}
+			result.push(messages[i]);
+			i++;
+		}
+		return result;
+	}
+	parse(json) {
+		try {
+			const msg = JSON.parse(json);
+			if (typeof msg?.id === "string" && typeof msg?.role === "string" && Array.isArray(msg?.parts)) return msg;
+		} catch {}
+		return null;
+	}
+	parseRows(rows) {
+		const result = [];
+		for (const row of rows) {
+			const msg = this.parse(row.content);
+			if (msg) result.push(msg);
+		}
+		return result;
+	}
+};
+//#endregion
+//#region src/experimental/memory/session/providers/agent-context.ts
+var AgentContextProvider = class {
+	constructor(agent, label) {
+		this.initialized = false;
+		this.agent = agent;
+		this.label = label;
+	}
+	ensureTable() {
+		if (this.initialized) return;
+		this.agent.sql`
+      CREATE TABLE IF NOT EXISTS cf_agents_context_blocks (
+        label TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
       )
     `;
-		return this.parseRows(rows);
+		this.initialized = true;
 	}
-	/**
-	* Bulk replace all messages.
-	* Preserves original created_at timestamps for surviving messages.
-	*/
-	async replaceMessages(messages) {
+	async get() {
+		this.ensureTable();
+		return this.agent.sql`
+      SELECT content FROM cf_agents_context_blocks WHERE label = ${this.label}
+    `[0]?.content ?? null;
+	}
+	async set(content) {
 		this.ensureTable();
-		const existingRows = this.agent.sql`
-      SELECT id, created_at FROM cf_agents_session_messages
+		this.agent.sql`
+      INSERT INTO cf_agents_context_blocks (label, content)
+      VALUES (${this.label}, ${content})
+      ON CONFLICT(label) DO UPDATE SET content = ${content}, updated_at = CURRENT_TIMESTAMP
     `;
-		const timestampMap = /* @__PURE__ */ new Map();
-		for (const row of existingRows) timestampMap.set(row.id, row.created_at);
-		this.agent.sql`DELETE FROM cf_agents_session_messages`;
-		const now = (/* @__PURE__ */ new Date()).toISOString();
-		for (const message of messages) {
-			const json = JSON.stringify(message);
-			const created_at = timestampMap.get(message.id) ?? now;
-			this.agent.sql`
-        INSERT INTO cf_agents_session_messages (id, message, created_at)
-        VALUES (${message.id}, ${json}, ${created_at})
-        ON CONFLICT(id) DO UPDATE SET message = excluded.message
-      `;
-		}
+	}
+};
+//#endregion
+//#region src/experimental/memory/session/session.ts
+function isBroadcaster(obj) {
+	return typeof obj === "object" && obj !== null && "broadcast" in obj && typeof obj.broadcast === "function";
+}
+var Session = class Session {
+	constructor(storage, options) {
+		this._ready = false;
+		this.storage = storage;
+		this.context = new ContextBlocks(options?.context ?? [], options?.promptStore);
+		this._ready = true;
 	}
 	/**
-	* Validate message structure
+	* Chainable session creation with auto-wired SQLite providers.
+	* Chain methods in any order — providers are resolved lazily on first use.
+	*
+	* @example
+	* ```ts
+	* const session = Session.create(this)
+	*   .withContext("soul", { initialContent: "You are helpful.", readonly: true })
+	*   .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
+	*   .withCachedPrompt();
+	*
+	* // Custom storage (R2, KV, etc.)
+	* const session = Session.create(this)
+	*   .withContext("workspace", {
+	*     provider: {
+	*       get: () => env.BUCKET.get("ws.md").then(o => o?.text() ?? null),
+	*       set: (c) => env.BUCKET.put("ws.md", c),
+	*     }
+	*   })
+	*   .withCachedPrompt();
+	* ```
 	*/
-	isValidMessage(msg) {
-		if (typeof msg !== "object" || msg === null) return false;
-		const m = msg;
-		if (typeof m.id !== "string" || m.id.length === 0) return false;
-		if (m.role !== "user" && m.role !== "assistant" && m.role !== "system") return false;
-		if (!Array.isArray(m.parts)) return false;
-		return true;
+	static create(agent) {
+		const session = Object.create(Session.prototype);
+		session._agent = agent;
+		if (isBroadcaster(agent)) session._broadcaster = agent;
+		session._pending = [];
+		session._ready = false;
+		return session;
+	}
+	forSession(sessionId) {
+		this._sessionId = sessionId;
+		return this;
+	}
+	withContext(label, options) {
+		this._pending.push({
+			label,
+			options: options ?? {}
+		});
+		return this;
+	}
+	withCachedPrompt(provider) {
+		this._cachedPrompt = provider ?? true;
+		return this;
 	}
 	/**
-	* Parse message rows from SQL results into UIMessages.
+	* Register a compaction function. Called by `compact()` to compress
+	* message history into a summary overlay.
 	*/
-	parseRows(rows) {
-		const messages = [];
-		for (const row of rows) try {
-			const parsed = JSON.parse(row.message);
-			if (this.isValidMessage(parsed)) messages.push(parsed);
-		} catch {
-			if (row.id) console.warn(`[AgentSessionProvider] Skipping malformed message ${row.id}`);
+	onCompaction(fn) {
+		this._compactionFn = fn;
+		return this;
+	}
+	/**
+	* Auto-compact when estimated token count exceeds the threshold.
+	* Checked after each `appendMessage`. Requires `onCompaction()`.
+	*/
+	compactAfter(tokenThreshold) {
+		this._tokenThreshold = tokenThreshold;
+		return this;
+	}
+	_ensureReady() {
+		if (this._ready) return;
+		const configs = (this._pending ?? []).map(({ label, options: opts }) => {
+			let provider = opts.provider;
+			if (!provider && !opts.readonly) {
+				const key = this._sessionId ? `${label}_${this._sessionId}` : label;
+				provider = new AgentContextProvider(this._agent, key);
+			}
+			return {
+				label,
+				description: opts.description,
+				initialContent: opts.initialContent,
+				maxTokens: opts.maxTokens,
+				readonly: opts.readonly,
+				provider
+			};
+		});
+		let promptStore;
+		if (this._cachedPrompt === true) {
+			const key = this._sessionId ? `_system_prompt_${this._sessionId}` : "_system_prompt";
+			promptStore = new AgentContextProvider(this._agent, key);
+		} else if (this._cachedPrompt) promptStore = this._cachedPrompt;
+		this.storage = new AgentSessionProvider(this._agent, this._sessionId);
+		this.context = new ContextBlocks(configs, promptStore);
+		this._ready = true;
+	}
+	getHistory(leafId) {
+		this._ensureReady();
+		return this.storage.getHistory(leafId);
+	}
+	getMessage(id) {
+		this._ensureReady();
+		return this.storage.getMessage(id);
+	}
+	getLatestLeaf() {
+		this._ensureReady();
+		return this.storage.getLatestLeaf();
+	}
+	getBranches(messageId) {
+		this._ensureReady();
+		return this.storage.getBranches(messageId);
+	}
+	getPathLength(leafId) {
+		this._ensureReady();
+		return this.storage.getPathLength(leafId);
+	}
+	_broadcast(type, data) {
+		if (!this._broadcaster) return;
+		this._broadcaster.broadcast(JSON.stringify({
+			type,
+			...data
+		}));
+	}
+	_emitStatus(phase, extra) {
+		const tokenEstimate = estimateMessageTokens(this.getHistory());
+		this._broadcast(MessageType.CF_AGENT_SESSION, {
+			phase,
+			tokenEstimate,
+			tokenThreshold: this._tokenThreshold ?? null,
+			...extra
+		});
+		return tokenEstimate;
+	}
+	_emitError(error) {
+		this._broadcast(MessageType.CF_AGENT_SESSION_ERROR, { error });
+	}
+	async appendMessage(message, parentId) {
+		this._ensureReady();
+		this.storage.appendMessage(message, parentId);
+		const tokenEstimate = this._emitStatus("idle");
+		if (this._tokenThreshold != null && this._compactionFn && tokenEstimate > this._tokenThreshold) try {
+			await this.compact();
+		} catch {}
+	}
+	updateMessage(message) {
+		this._ensureReady();
+		this.storage.updateMessage(message);
+		this._emitStatus("idle");
+	}
+	deleteMessages(messageIds) {
+		this._ensureReady();
+		this.storage.deleteMessages(messageIds);
+		this._emitStatus("idle");
+	}
+	clearMessages() {
+		this._ensureReady();
+		this.storage.clearMessages();
+		this._emitStatus("idle");
+	}
+	addCompaction(summary, fromMessageId, toMessageId) {
+		this._ensureReady();
+		return this.storage.addCompaction(summary, fromMessageId, toMessageId);
+	}
+	getCompactions() {
+		this._ensureReady();
+		return this.storage.getCompactions();
+	}
+	/**
+	* Run the registered compaction function and store the result as an overlay.
+	* Requires `onCompaction()` to be called first.
+	*/
+	async compact() {
+		this._ensureReady();
+		if (!this._compactionFn) throw new Error("No compaction function registered. Call onCompaction() first.");
+		const tokensBefore = this._emitStatus("compacting");
+		let result;
+		try {
+			result = await this._compactionFn(this.getHistory());
+		} catch (err) {
+			this._emitError(err instanceof Error ? err.message : String(err));
+			return null;
+		}
+		if (!result) {
+			this._emitStatus("idle");
+			return null;
 		}
-		return messages;
+		if (!new Set(this.getHistory().map((m) => m.id)).has(result.toMessageId)) {
+			this._emitStatus("idle");
+			return null;
+		}
+		const existing = this.getCompactions();
+		const fromId = existing.length > 0 ? existing[0].fromMessageId : result.fromMessageId;
+		this.addCompaction(result.summary, fromId, result.toMessageId);
+		await this.refreshSystemPrompt();
+		this._emitStatus("idle", { compacted: { tokensBefore } });
+		return {
+			...result,
+			fromMessageId: fromId
+		};
+	}
+	getContextBlock(label) {
+		this._ensureReady();
+		return this.context.getBlock(label);
+	}
+	getContextBlocks() {
+		this._ensureReady();
+		return this.context.getBlocks();
+	}
+	async replaceContextBlock(label, content) {
+		this._ensureReady();
+		return this.context.setBlock(label, content);
+	}
+	async appendContextBlock(label, content) {
+		this._ensureReady();
+		return this.context.appendToBlock(label, content);
+	}
+	async freezeSystemPrompt() {
+		this._ensureReady();
+		return this.context.freezeSystemPrompt();
+	}
+	async refreshSystemPrompt() {
+		this._ensureReady();
+		return this.context.refreshSystemPrompt();
+	}
+	search(query, options) {
+		this._ensureReady();
+		if (!this.storage.searchMessages) throw new Error("Session provider does not support search");
+		return this.storage.searchMessages(query, options?.limit ?? 20);
+	}
+	/** Returns update_context tool for writing to context blocks. */
+	async tools() {
+		this._ensureReady();
+		return this.context.tools();
 	}
 };
 //#endregion
-export { AgentSessionProvider, Session };
+export { AgentContextProvider, AgentSessionProvider, Session };
 
 //# sourceMappingURL=index.js.map