agents 0.12.3 → 0.13.0

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

@@ -1,5 +1,5 @@
 import "../../../types.js";
-import { m as estimateStringTokens, p as estimateMessageTokens, t as COMPACTION_PREFIX } from "../../../compaction-helpers-CSaqCmdE.js";
+import { m as estimateStringTokens, p as estimateMessageTokens, t as COMPACTION_PREFIX } from "../../../compaction-helpers-DvcZnvQ1.js";
 import { z } from "zod";
 //#region src/experimental/memory/session/search.ts
 /**
@@ -65,12 +65,7 @@ var AgentSearchProvider = class {
       WHERE label = ${this.label}
     `[0]?.count ?? 0;
 		if (count === 0) return null;
-		return `${count} entries indexed. Recent:\n${this.agent.sql`
-      SELECT key FROM cf_agents_search_entries
-      WHERE label = ${this.label}
-      ORDER BY updated_at DESC
-      LIMIT 20
-    `.map((r) => `- ${r.key}`).join("\n")}`;
+		return `${count} entries indexed.`;
 	}
 	async search(query) {
 		this.ensureTable();
@@ -131,17 +126,22 @@ function isSkillProvider(provider) {
 *
 * Descriptions are pulled from R2 custom metadata (`description` key).
 * If a prefix is provided, it is prepended on storage operations and
-* stripped from keys in metadata.
+* stripped from keys in metadata. `keys`, when provided, is matched against
+* these prefix-relative keys.
 *
 * @example
 * ```ts
-* const skills = new R2SkillProvider(env.SKILLS_BUCKET, { prefix: "skills/" });
+* const skills = new R2SkillProvider(env.SKILLS_BUCKET, {
+*   prefix: "skills/",
+*   keys: ["code-review", "debugging"]
+* });
 * ```
 */
 var R2SkillProvider = class {
 	constructor(bucket, options) {
 		this.bucket = bucket;
 		this.prefix = options?.prefix ?? "";
+		this.keys = options?.keys?.length ? new Set(options.keys) : null;
 	}
 	async get() {
 		const entries = [];
@@ -155,6 +155,7 @@ var R2SkillProvider = class {
 			});
 			for (const obj of listed.objects) {
 				const key = obj.key.slice(this.prefix.length);
+				if (!this.allowsKey(key)) continue;
 				const desc = obj.customMetadata?.description;
 				entries.push(`- ${key}${desc ? `: ${desc}` : ""}`);
 			}
@@ -164,6 +165,7 @@ var R2SkillProvider = class {
 		return entries.length > 0 ? entries.join("\n") : null;
 	}
 	async load(key) {
+		if (!this.allowsKey(key)) return null;
 		const obj = await this.bucket.get(this.prefix + key);
 		if (!obj) return null;
 		return obj.text();
@@ -171,9 +173,27 @@ var R2SkillProvider = class {
 	async set(key, content, description) {
 		await this.bucket.put(this.prefix + key, content, { customMetadata: description ? { description } : void 0 });
 	}
+	allowsKey(key) {
+		return this.keys === null || this.keys.has(key);
+	}
 };
 //#endregion
 //#region src/experimental/memory/session/context.ts
+function slugify(text) {
+	return text.slice(0, 60).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function stableHash(text) {
+	let hash = 2166136261;
+	for (let i = 0; i < text.length; i++) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36);
+}
+function contextEntryKey(metadataTitle, content) {
+	if (metadataTitle?.trim()) return slugify(metadataTitle) || `entry-${stableHash(metadataTitle)}`;
+	return `${slugify(content) || "entry"}-${stableHash(content)}`;
+}
 /**
 * Check if a provider is writable (has a `set` method).
 */
@@ -405,7 +425,8 @@ var ContextBlocks = class {
 		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);
+		const needsSep = existing.content.length > 0 && !content.startsWith("\n");
+		return this.setBlock(label, existing.content + (needsSep ? "\n" : "") + content);
 	}
 	/**
 	* Get the system prompt string with context blocks.
@@ -429,18 +450,17 @@ var ContextBlocks = class {
 		const parts = [];
 		const sep = "═".repeat(46);
 		for (const block of this.blocks.values()) {
-			if (!block.content && !block.isSearchable) continue;
+			if (!block.content && !block.writable && !block.isSearchable && !block.isSkill) continue;
 			let header = block.label.toUpperCase();
-			const hints = [];
-			if (block.description) hints.push(block.description);
-			if (block.isSkill) hints.push("use load_context to load");
-			if (block.isSearchable) hints.push("use search_context to search");
-			if (hints.length > 0) header += ` (${hints.join(" — ")})`;
+			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.writable) header += " [readonly]";
+			if (block.isSearchable) header += " [searchable]";
+			else if (block.isSkill) header += " [loadable]";
+			else if (!block.writable) header += " [readonly]";
+			else header += " [writable]";
 			parts.push(`${sep}\n${header}\n${sep}\n${block.content}`);
 		}
 		this.snapshot = parts.join("\n\n");
@@ -477,9 +497,9 @@ var ContextBlocks = class {
 		return Array.from(this.blocks.values()).filter((b) => b.isSearchable).map((b) => b.label);
 	}
 	/**
-	* 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
+	* Return the cached system prompt. If no cached prompt exists,
+	* loads blocks from providers, renders, and persists to the store.
+	* Subsequent calls return the stored value without re-rendering.
 	*/
 	async freezeSystemPrompt() {
 		if (this.promptStore) {
@@ -492,10 +512,13 @@ var ContextBlocks = class {
 		return prompt;
 	}
 	/**
-	* Re-render the system prompt from current block state and persist.
+	* Force reload blocks from providers, re-render the system prompt,
+	* and persist to the store. Use this after block content has changed
+	* or to invalidate the cached prompt.
 	*/
 	async refreshSystemPrompt() {
-		if (!this.loaded) await this.load();
+		this.loaded = false;
+		await this.load();
 		const prompt = this.refreshSnapshot();
 		if (this.promptStore) await this.promptStore.set(prompt);
 		return prompt;
@@ -515,14 +538,11 @@ var ContextBlocks = class {
 		const hasSearch = this.hasSearchBlocks();
 		const toolSet = {};
 		if (writable.length > 0) {
-			const regularBlocks = writable.filter((b) => !b.isSkill && !b.isSearchable);
+			const blockDescriptions = writable.map((b) => {
+				const kind = b.isSkill ? "skill collection, keyed entries" : b.isSearchable ? "searchable, keyed entries" : "writable";
+				return `- "${b.label}" (${kind}): ${b.description ?? "no description"}`;
+			});
 			const keyedBlocks = writable.filter((b) => b.isSkill || b.isSearchable);
-			const blockDescriptions = [];
-			for (const b of regularBlocks) blockDescriptions.push(`- "${b.label}": ${b.description ?? "no description"}`);
-			for (const b of keyedBlocks) {
-				const kind = b.isSkill ? "skill collection (requires key and optional description)" : "searchable (requires key)";
-				blockDescriptions.push(`- "${b.label}": ${kind}`);
-			}
 			const properties = {
 				label: {
 					type: "string",
@@ -531,7 +551,7 @@ var ContextBlocks = class {
 				},
 				content: {
 					type: "string",
-					description: "Content to write"
+					description: "The main content to write to the block."
 				},
 				action: {
 					type: "string",
@@ -539,34 +559,38 @@ var ContextBlocks = class {
 					description: "replace (default) or append"
 				}
 			};
-			const required = ["label", "content"];
-			if (keyedBlocks.length > 0) properties.key = {
-				type: "string",
-				description: "Entry key (required for keyed blocks: " + keyedBlocks.map((b) => `"${b.label}"`).join(", ") + ")"
-			};
-			if (keyedBlocks.some((b) => b.isSkill)) properties.description = {
-				type: "string",
-				description: "Short description for the skill entry"
+			if (keyedBlocks.length > 0) properties.metadata = {
+				type: "object",
+				description: "Optional metadata for keyed entries (skill collections, searchable blocks: " + keyedBlocks.map((b) => `"${b.label}"`).join(", ") + "). Short content doesn't need metadata; longer loadable entries (skills) benefit from a title and description so the model can pick the right one without loading it.",
+				properties: {
+					title: {
+						type: "string",
+						description: "Short title. Used as a stable identifier — entries with the same title are updated in place, different titles create new entries."
+					},
+					description: {
+						type: "string",
+						description: "One-line summary shown alongside the title in the system prompt so the model can decide when to load the entry."
+					}
+				}
 			};
+			const metadataHint = keyedBlocks.length > 0 ? "\n\nFor keyed blocks (skill collections / searchable), pass `metadata: { title, description }` — title stabilises updates, description helps the model pick entries. Metadata is optional; short content rarely needs it, long loadable entries benefit most." : "";
 			toolSet.set_context = {
-				description: `Write to a context block. Available blocks:\n${blockDescriptions.join("\n")}\n\nWrites are durable and persist across sessions.`,
+				description: `Write to a context block. Available blocks:\n${blockDescriptions.join("\n")}\n\nWrites are durable and persist across sessions.${metadataHint}`,
 				inputSchema: z.fromJSONSchema({
 					type: "object",
 					properties,
-					required
+					required: ["label", "content"]
 				}),
-				execute: async ({ label, content, key, description, action }) => {
+				execute: async ({ label, content, metadata, action }) => {
 					try {
 						const block = this.blocks.get(label);
 						if (!block) return `Error: block "${label}" not found`;
-						if (block.isSkill) {
-							if (!key) return `Error: key is required for skill block "${label}"`;
-							await this.setSkill(label, key, content, description);
-							return `Written skill "${key}" to ${label}.`;
-						}
-						if (block.isSearchable) {
-							if (!key) return `Error: key is required for searchable block "${label}"`;
-							await this.setSearchEntry(label, key, content);
+						if (block.isSkill || block.isSearchable) {
+							const title = metadata?.title;
+							const description = metadata?.description;
+							const key = contextEntryKey(title, content);
+							if (block.isSkill) await this.setSkill(label, key, content, description ?? title);
+							else await this.setSearchEntry(label, key, content);
 							return `Indexed "${key}" in ${label}.`;
 						}
 						const updated = action === "append" ? await this.appendToBlock(label, content) : await this.setBlock(label, content);
@@ -598,6 +622,7 @@ var ContextBlocks = class {
 				}),
 				execute: async ({ label, key }) => {
 					try {
+						if (!skillLabels.includes(label)) return `Error: "${label}" is not a skill block. Skill blocks: ${skillLabels.join(", ")}`;
 						return await this.loadSkill(label, key) ?? `Not found: ${key}`;
 					} catch (err) {
 						return `Error: ${err instanceof Error ? err.message : String(err)}`;
@@ -623,6 +648,7 @@ var ContextBlocks = class {
 					required: ["label", "key"]
 				}),
 				execute: async ({ label, key }) => {
+					if (!skillLabels.includes(label)) return `Error: "${label}" is not a skill block. Skill blocks: ${skillLabels.join(", ")}`;
 					if (!this.unloadSkill(label, key)) return `Skill "${key}" is not currently loaded in "${label}".`;
 					return `Unloaded "${key}" from ${label}. Context reclaimed.`;
 				}
@@ -631,7 +657,7 @@ var ContextBlocks = class {
 		if (hasSearch) {
 			const searchLabels = this.getSearchLabels();
 			toolSet.search_context = {
-				description: "Search for information in a searchable context block. Available searchable blocks: " + searchLabels.map((l) => `"${l}"`).join(", ") + ".",
+				description: "Search for information in a searchable context block. ONLY these blocks are searchable: " + searchLabels.map((l) => `"${l}"`).join(", ") + ". Other blocks cannot be searched.",
 				inputSchema: z.fromJSONSchema({
 					type: "object",
 					properties: {
@@ -649,6 +675,7 @@ var ContextBlocks = class {
 				}),
 				execute: async ({ label, query }) => {
 					try {
+						if (!searchLabels.includes(label)) return `Error: "${label}" is not searchable. Searchable blocks: ${searchLabels.join(", ")}`;
 						return await this.searchContext(label, query) ?? "No results found.";
 					} catch (err) {
 						return `Error: ${err instanceof Error ? err.message : String(err)}`;
@@ -779,7 +806,7 @@ var AgentSessionProvider = class {
 		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;
+		let parent = parentId !== void 0 ? parentId : this.latestLeafRow()?.id ?? null;
 		if (parent) {
 			if (this.agent.sql`
         SELECT id FROM assistant_messages WHERE id = ${parent} AND session_id = ${this.sessionId}
@@ -969,6 +996,9 @@ var AgentContextProvider = class {
 function isBroadcaster(obj) {
 	return typeof obj === "object" && obj !== null && "broadcast" in obj && typeof obj.broadcast === "function";
 }
+function isSqlProvider(arg) {
+	return "sql" in arg && typeof arg.sql === "function";
+}
 var Session = class Session {
 	constructor(storage, options) {
 		this._ready = false;
@@ -977,11 +1007,14 @@ var Session = class Session {
 		this._ready = true;
 	}
 	/**
-	* Chainable session creation with auto-wired SQLite providers.
-	* Chain methods in any order — providers are resolved lazily on first use.
+	* Chainable session creation with auto-wired providers.
+	*
+	* Pass a `SqlProvider` (Agent with `sql` method) for auto-wired SQLite,
+	* or a `SessionProvider` directly for custom storage (Postgres, etc.).
 	*
 	* @example
 	* ```ts
+	* // Auto-wired SQLite (DO Agent)
 	* const session = Session.create(this)
 	*   .withContext("soul", { provider: { get: async () => "You are helpful." } })
 	*   .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
@@ -993,12 +1026,22 @@ var Session = class Session {
 	*     provider: new R2SkillProvider(env.SKILLS_BUCKET, { prefix: "skills/" })
 	*   })
 	*   .withCachedPrompt();
+	*
+	* // Custom storage provider (Postgres, etc.)
+	* const session = Session.create(postgresProvider)
+	*   .withContext("memory", {
+	*     maxTokens: 1100,
+	*     provider: new PostgresContextProvider(conn, "memory")
+	*   })
+	*   .withCachedPrompt(new PostgresContextProvider(conn, "_prompt"));
 	* ```
 	*/
-	static create(agent) {
+	static create(provider) {
 		const session = Object.create(Session.prototype);
-		session._agent = agent;
-		if (isBroadcaster(agent)) session._broadcaster = agent;
+		if (isSqlProvider(provider)) {
+			session._agent = provider;
+			if (isBroadcaster(provider)) session._broadcaster = provider;
+		} else session._storageProvider = provider;
 		session._pending = [];
 		session._ready = false;
 		return session;
@@ -1034,11 +1077,20 @@ var Session = class Session {
 		this._tokenThreshold = tokenThreshold;
 		return this;
 	}
+	/**
+	* @internal
+	* Framework hook for cache-owning callers that need to mirror message
+	* storage changes. Application code should use the normal Session methods.
+	*/
+	internal_onMessagesChanged(listener) {
+		this._messageChangeListener = listener ?? void 0;
+		return this;
+	}
 	_ensureReady() {
 		if (this._ready) return;
 		const configs = (this._pending ?? []).map(({ label, options: opts }) => {
 			let provider = opts.provider;
-			if (!provider) {
+			if (!provider && this._agent) {
 				const key = this._sessionId ? `${label}_${this._sessionId}` : label;
 				provider = new AgentContextProvider(this._agent, key);
 			}
@@ -1050,25 +1102,40 @@ var Session = class Session {
 			};
 		});
 		let promptStore;
-		if (this._cachedPrompt === true) {
+		if (this._cachedPrompt === true && this._agent) {
 			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);
+		} else if (this._cachedPrompt && this._cachedPrompt !== true) promptStore = this._cachedPrompt;
+		if (this._storageProvider) this.storage = this._storageProvider;
+		else if (this._agent) this.storage = new AgentSessionProvider(this._agent, this._sessionId);
+		else throw new Error("Session.create() requires a SqlProvider or SessionProvider");
 		this.context = new ContextBlocks(configs, promptStore);
 		this.context.setUnloadCallback((label, key) => {
-			this._reclaimLoadedSkill(label, key);
+			this._reclaimLoadedSkill(label, key).catch(() => {});
 		});
-		this._restoreLoadedSkills();
 		this._ready = true;
+		this._restorePromise = this._restoreLoadedSkills().catch(() => {});
+	}
+	/**
+	* Await the background skill-restore kicked off by `_ensureReady()`.
+	* Idempotent and cheap — every async public method calls this so that
+	* `_loadedSkills` reflects conversation history before any read or write.
+	*/
+	async _ensureRestored() {
+		this._ensureReady();
+		if (this._restorePromise) await this._restorePromise;
+	}
+	async _notifyMessagesChanged(event) {
+		await this._messageChangeListener?.(event);
 	}
 	/**
 	* Reconstruct which skills are loaded by scanning conversation history
 	* for load_context tool results that haven't been unloaded.
-	* Called during init to survive hibernation/eviction.
+	* Runs once per init to survive hibernation / eviction, including for
+	* async SessionProviders (e.g. Postgres) where we must `await` history.
 	*/
-	_restoreLoadedSkills() {
-		const history = this.storage.getHistory();
+	async _restoreLoadedSkills() {
+		const history = await this.storage.getHistory();
 		const loaded = /* @__PURE__ */ new Set();
 		for (const msg of history) {
 			if (msg.role !== "assistant") continue;
@@ -1087,11 +1154,22 @@ var Session = class Session {
 		if (loaded.size > 0) this.context.restoreLoadedSkills(loaded);
 	}
 	/**
-	* Replace a load_context tool result in conversation history
-	* with a short marker to reclaim context space.
+	* Reclaim context-window tokens consumed by a previously loaded skill.
+	*
+	* When a skill is loaded via the `load_context` tool, its full body is
+	* embedded as that tool call's `output-available` result inside the
+	* assistant message — which means every subsequent turn replays the
+	* entire skill as part of the conversation history and pays for it in
+	* input tokens.
+	*
+	* This method walks back through history, finds the matching
+	* `load_context` tool result for `(label, key)`, and replaces its bulky
+	* `output` with a short marker `[skill unloaded: <key>]`. The skill
+	* content is dropped from future turns and the tokens are reclaimed.
+	* The skill itself stays available to reload via `load_context`.
 	*/
-	_reclaimLoadedSkill(label, key) {
-		const history = this.storage.getHistory();
+	async _reclaimLoadedSkill(label, key) {
+		const history = await this.storage.getHistory();
 		for (let i = history.length - 1; i >= 0; i--) {
 			const msg = history[i];
 			if (msg.role !== "assistant") continue;
@@ -1110,7 +1188,7 @@ var Session = class Session {
 				return part;
 			});
 			if (changed) {
-				this.storage.updateMessage({
+				await this.updateMessage({
 					...msg,
 					parts: newParts
 				});
@@ -1118,24 +1196,24 @@ var Session = class Session {
 			}
 		}
 	}
-	getHistory(leafId) {
-		this._ensureReady();
+	async getHistory(leafId) {
+		await this._ensureRestored();
 		return this.storage.getHistory(leafId);
 	}
-	getMessage(id) {
-		this._ensureReady();
+	async getMessage(id) {
+		await this._ensureRestored();
 		return this.storage.getMessage(id);
 	}
-	getLatestLeaf() {
-		this._ensureReady();
+	async getLatestLeaf() {
+		await this._ensureRestored();
 		return this.storage.getLatestLeaf();
 	}
-	getBranches(messageId) {
-		this._ensureReady();
+	async getBranches(messageId) {
+		await this._ensureRestored();
 		return this.storage.getBranches(messageId);
 	}
-	getPathLength(leafId) {
-		this._ensureReady();
+	async getPathLength(leafId) {
+		await this._ensureRestored();
 		return this.storage.getPathLength(leafId);
 	}
 	_broadcast(type, data) {
@@ -1145,8 +1223,8 @@ var Session = class Session {
 			...data
 		}));
 	}
-	_emitStatus(phase, extra) {
-		const tokenEstimate = estimateMessageTokens(this.getHistory());
+	async _emitStatus(phase, extra) {
+		const tokenEstimate = estimateMessageTokens(await this.getHistory());
 		this._broadcast("cf_agent_session", {
 			phase,
 			tokenEstimate,
@@ -1159,35 +1237,65 @@ var Session = class Session {
 		this._broadcast("cf_agent_session_error", { error });
 	}
 	async appendMessage(message, parentId) {
-		this._ensureReady();
-		this.storage.appendMessage(message, parentId);
-		const tokenEstimate = this._emitStatus("idle");
+		await this._appendMessage(message, parentId);
+	}
+	async _appendMessage(message, parentId) {
+		await this._ensureRestored();
+		if (await this.storage.getMessage(message.id)) {
+			await this._emitStatus("idle");
+			await this._notifyMessagesChanged({
+				type: "append",
+				message,
+				parentId,
+				inserted: false
+			});
+			return;
+		}
+		await this.storage.appendMessage(message, parentId);
+		const tokenEstimate = await this._emitStatus("idle");
+		let compacted = false;
 		if (this._tokenThreshold != null && this._compactionFn && tokenEstimate > this._tokenThreshold) try {
-			await this.compact();
+			compacted = Boolean(await this.compact());
 		} catch {}
+		if (!compacted) await this._notifyMessagesChanged({
+			type: "append",
+			message,
+			parentId,
+			inserted: true
+		});
 	}
-	updateMessage(message) {
-		this._ensureReady();
-		this.storage.updateMessage(message);
-		this._emitStatus("idle");
+	async updateMessage(message) {
+		await this._ensureRestored();
+		await this.storage.updateMessage(message);
+		await this._emitStatus("idle");
+		await this._notifyMessagesChanged({
+			type: "update",
+			message
+		});
 	}
-	deleteMessages(messageIds) {
-		this._ensureReady();
-		this.storage.deleteMessages(messageIds);
-		this._emitStatus("idle");
+	async deleteMessages(messageIds) {
+		await this._ensureRestored();
+		await this.storage.deleteMessages(messageIds);
+		await this._emitStatus("idle");
+		await this._notifyMessagesChanged({
+			type: "delete",
+			messageIds
+		});
 	}
-	clearMessages() {
-		this._ensureReady();
-		this.storage.clearMessages();
+	async clearMessages() {
+		await this._ensureRestored();
+		await this.storage.clearMessages();
 		this.context.clearSkillState();
-		this._emitStatus("idle");
+		await this.context.refreshSystemPrompt();
+		await this._emitStatus("idle");
+		await this._notifyMessagesChanged({ type: "clear" });
 	}
-	addCompaction(summary, fromMessageId, toMessageId) {
-		this._ensureReady();
+	async addCompaction(summary, fromMessageId, toMessageId) {
+		await this._ensureRestored();
 		return this.storage.addCompaction(summary, fromMessageId, toMessageId);
 	}
-	getCompactions() {
-		this._ensureReady();
+	async getCompactions() {
+		await this._ensureRestored();
 		return this.storage.getCompactions();
 	}
 	/**
@@ -1195,29 +1303,30 @@ var Session = class Session {
 	* Requires `onCompaction()` to be called first.
 	*/
 	async compact() {
-		this._ensureReady();
+		await this._ensureRestored();
 		if (!this._compactionFn) throw new Error("No compaction function registered. Call onCompaction() first.");
-		const tokensBefore = this._emitStatus("compacting");
+		const tokensBefore = await this._emitStatus("compacting");
 		let result;
 		try {
-			result = await this._compactionFn(this.getHistory());
+			result = await this._compactionFn(await this.getHistory());
 		} catch (err) {
 			this._emitError(err instanceof Error ? err.message : String(err));
 			return null;
 		}
 		if (!result) {
-			this._emitStatus("idle");
+			await this._emitStatus("idle");
 			return null;
 		}
-		if (!new Set(this.getHistory().map((m) => m.id)).has(result.toMessageId)) {
-			this._emitStatus("idle");
+		if (!new Set((await this.getHistory()).map((m) => m.id)).has(result.toMessageId)) {
+			await this._emitStatus("idle");
 			return null;
 		}
-		const existing = this.getCompactions();
+		const existing = await this.getCompactions();
 		const fromId = existing.length > 0 ? existing[0].fromMessageId : result.fromMessageId;
-		this.addCompaction(result.summary, fromId, result.toMessageId);
+		await this.addCompaction(result.summary, fromId, result.toMessageId);
 		await this.refreshSystemPrompt();
-		this._emitStatus("idle", { compacted: { tokensBefore } });
+		await this._emitStatus("idle", { compacted: { tokensBefore } });
+		await this._notifyMessagesChanged({ type: "compact" });
 		return {
 			...result,
 			fromMessageId: fromId
@@ -1232,16 +1341,21 @@ var Session = class Session {
 		return this.context.getBlocks();
 	}
 	async replaceContextBlock(label, content) {
-		this._ensureReady();
+		await this._ensureRestored();
 		return this.context.setBlock(label, content);
 	}
 	async appendContextBlock(label, content) {
-		this._ensureReady();
+		await this._ensureRestored();
 		return this.context.appendToBlock(label, content);
 	}
 	/**
 	* Dynamically register a new context block after session initialization.
-	* Used by extensions to contribute context blocks at runtime.
+	*
+	* This is a **builder / runtime API**, not an LLM tool. The LLM writes
+	* into existing context blocks via the `set_context` tool (see
+	* `ContextBlocks.tools()`); it cannot declare new blocks itself. This
+	* method is how extension / host code contributes blocks at runtime
+	* (e.g. an extension's `onLoad` handler registering its own memory block).
 	*
 	* The block's provider is initialized and loaded immediately.
 	* Call `refreshSystemPrompt()` afterward to include the new block
@@ -1252,10 +1366,11 @@ var Session = class Session {
 	* via `Session.create(agent)` (not the direct constructor).
 	*/
 	async addContext(label, options) {
-		this._ensureReady();
+		await this._ensureRestored();
 		const opts = options ?? {};
 		let provider = opts.provider;
 		if (!provider) {
+			if (!this._agent) throw new Error(`addContext("${label}") requires an explicit provider when Session uses a SessionProvider`);
 			const key = this._sessionId ? `${label}_${this._sessionId}` : label;
 			provider = new AgentContextProvider(this._agent, key);
 		}
@@ -1281,34 +1396,40 @@ var Session = class Session {
 	/**
 	* Unload a previously loaded skill, reclaiming context space.
 	* The tool result in conversation history is replaced with a short marker.
+	*
+	* Async so that the session's background skill-state restore (which
+	* reads conversation history) is awaited first — otherwise a freshly
+	* rehydrated DO could report "not loaded" for a skill that's actually
+	* present in history.
 	*/
-	unloadSkill(label, key) {
-		this._ensureReady();
+	async unloadSkill(label, key) {
+		await this._ensureRestored();
 		return this.context.unloadSkill(label, key);
 	}
 	/**
 	* Get currently loaded skill keys (as "label:key" strings).
+	* Async for the same reason as `unloadSkill` — must wait for restore.
 	*/
-	getLoadedSkillKeys() {
-		this._ensureReady();
+	async getLoadedSkillKeys() {
+		await this._ensureRestored();
 		return this.context.getLoadedSkillKeys();
 	}
 	async freezeSystemPrompt() {
-		this._ensureReady();
+		await this._ensureRestored();
 		return this.context.freezeSystemPrompt();
 	}
 	async refreshSystemPrompt() {
-		this._ensureReady();
+		await this._ensureRestored();
 		return this.context.refreshSystemPrompt();
 	}
-	search(query, options) {
-		this._ensureReady();
+	async search(query, options) {
+		await this._ensureRestored();
 		if (!this.storage.searchMessages) throw new Error("Session provider does not support search");
 		return this.storage.searchMessages(query, options?.limit ?? 20);
 	}
 	/** Returns set_context and load_context tools. */
 	async tools() {
-		this._ensureReady();
+		await this._ensureRestored();
 		return this.context.tools();
 	}
 };
@@ -1482,8 +1603,8 @@ var SessionManager = class SessionManager {
       SELECT * FROM assistant_sessions ORDER BY updated_at DESC
     `;
 	}
-	delete(sessionId) {
-		this.getSession(sessionId).clearMessages();
+	async delete(sessionId) {
+		await this.getSession(sessionId).clearMessages();
 		this.agent.sql`DELETE FROM assistant_sessions WHERE id = ${sessionId}`;
 		this._sessions.delete(sessionId);
 	}
@@ -1501,7 +1622,7 @@ var SessionManager = class SessionManager {
 	}
 	async upsert(sessionId, message, parentId) {
 		const session = this.getSession(sessionId);
-		if (session.getMessage(message.id)) session.updateMessage(message);
+		if (await session.getMessage(message.id)) await session.updateMessage(message);
 		else await session.appendMessage(message, parentId);
 		this._touch(sessionId);
 		return message.id;
@@ -1516,21 +1637,21 @@ var SessionManager = class SessionManager {
 		this._touch(sessionId);
 		return lastParent;
 	}
-	getHistory(sessionId, leafId) {
+	async getHistory(sessionId, leafId) {
 		return this.getSession(sessionId).getHistory(leafId);
 	}
-	getMessageCount(sessionId) {
+	async getMessageCount(sessionId) {
 		return this.getSession(sessionId).getPathLength();
 	}
-	clearMessages(sessionId) {
-		this.getSession(sessionId).clearMessages();
+	async clearMessages(sessionId) {
+		await this.getSession(sessionId).clearMessages();
 		this._touch(sessionId);
 	}
-	deleteMessages(sessionId, messageIds) {
-		this.getSession(sessionId).deleteMessages(messageIds);
+	async deleteMessages(sessionId, messageIds) {
+		await this.getSession(sessionId).deleteMessages(messageIds);
 		this._touch(sessionId);
 	}
-	getBranches(sessionId, messageId) {
+	async getBranches(sessionId, messageId) {
 		return this.getSession(sessionId).getBranches(messageId);
 	}
 	/**
@@ -1539,7 +1660,7 @@ var SessionManager = class SessionManager {
 	*/
 	async fork(sessionId, atMessageId, newName) {
 		const info = this.create(newName, { parentSessionId: sessionId });
-		const history = this.getSession(sessionId).getHistory(atMessageId);
+		const history = await this.getSession(sessionId).getHistory(atMessageId);
 		const newSession = this.getSession(info.id);
 		let parentId = null;
 		for (const msg of history) {
@@ -1554,10 +1675,10 @@ var SessionManager = class SessionManager {
 		this._touch(info.id);
 		return info;
 	}
-	addCompaction(sessionId, summary, fromId, toId) {
+	async addCompaction(sessionId, summary, fromId, toId) {
 		return this.getSession(sessionId).addCompaction(summary, fromId, toId);
 	}
-	getCompactions(sessionId) {
+	async getCompactions(sessionId) {
 		return this.getSession(sessionId).getCompactions();
 	}
 	async compactAndSplit(sessionId, summary, newName) {
@@ -1642,6 +1763,300 @@ var SessionManager = class SessionManager {
 	}
 };
 //#endregion
-export { AgentContextProvider, AgentSearchProvider, AgentSessionProvider, R2SkillProvider, Session, SessionManager, isSearchProvider, isSkillProvider, isWritableProvider };
+//#region src/experimental/memory/session/providers/postgres-adapter.ts
+function isPostgresConnection(client) {
+	return typeof client.execute === "function";
+}
+/**
+* Normalise an incoming client into a `PostgresConnection`. When given a
+* `pg`-style client we translate `?` placeholders to `$1, $2, ...` so the
+* providers can keep using the portable `?` syntax internally.
+*/
+function toPostgresConnection(client) {
+	if (isPostgresConnection(client)) return client;
+	const pg = client;
+	return { async execute(query, args) {
+		let idx = 0;
+		const pgQuery = query.replace(/\?/g, () => `$${++idx}`);
+		return { rows: (await pg.query(pgQuery, args ?? [])).rows };
+	} };
+}
+//#endregion
+//#region src/experimental/memory/session/providers/postgres.ts
+var PostgresSessionProvider = class {
+	/**
+	* @param client A raw `pg.Client` (recommended) or any `PostgresConnection`.
+	*   Must already be connected — this provider never opens or closes the
+	*   underlying client.
+	* @param sessionId Session identifier. Different ids are fully isolated
+	*   rows within the shared tables. Defaults to `""`.
+	*/
+	constructor(client, sessionId) {
+		this.conn = toPostgresConnection(client);
+		this.sessionId = sessionId ?? "";
+	}
+	async getMessage(id) {
+		const { rows } = await this.conn.execute("SELECT content FROM assistant_messages WHERE id = ? AND session_id = ?", [id, this.sessionId]);
+		return rows.length > 0 ? this.parse(rows[0].content) : null;
+	}
+	async getHistory(leafId) {
+		const leaf = leafId ? (await this.conn.execute("SELECT id FROM assistant_messages WHERE id = ? AND session_id = ?", [leafId, this.sessionId])).rows[0] : await this.latestLeafRow();
+		if (!leaf) return [];
+		const { rows } = await this.conn.execute(`WITH RECURSIVE path AS (
+        SELECT id, parent_id, content, 0 as depth FROM assistant_messages WHERE id = ? AND session_id = ?
+        UNION ALL
+        SELECT m.id, m.parent_id, m.content, p.depth + 1 FROM assistant_messages m
+        JOIN path p ON m.id = p.parent_id
+        WHERE m.session_id = ? AND p.depth < 10000
+      )
+      SELECT content FROM path ORDER BY depth DESC`, [
+			leaf.id,
+			this.sessionId,
+			this.sessionId
+		]);
+		const messages = this.parseRows(rows);
+		const compactions = await this.getCompactions();
+		if (compactions.length === 0) return messages;
+		return this.applyCompactions(messages, compactions);
+	}
+	async getLatestLeaf() {
+		const row = await this.latestLeafRow();
+		return row ? this.parse(row.content) : null;
+	}
+	async getBranches(messageId) {
+		const { rows } = await this.conn.execute("SELECT content FROM assistant_messages WHERE parent_id = ? AND session_id = ? ORDER BY created_at ASC", [messageId, this.sessionId]);
+		return this.parseRows(rows);
+	}
+	async getPathLength(leafId) {
+		const leaf = leafId ? (await this.conn.execute("SELECT id FROM assistant_messages WHERE id = ? AND session_id = ?", [leafId, this.sessionId])).rows[0] : await this.latestLeafRow();
+		if (!leaf) return 0;
+		const { rows } = await this.conn.execute(`WITH RECURSIVE path AS (
+        SELECT id, parent_id, 0 as depth FROM assistant_messages WHERE id = ? AND session_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 = ? AND p.depth < 10000
+      )
+      SELECT COUNT(*) as count FROM path`, [
+			leaf.id,
+			this.sessionId,
+			this.sessionId
+		]);
+		return Number(rows[0]?.count ?? 0);
+	}
+	async appendMessage(message, parentId) {
+		let parent = parentId !== void 0 ? parentId : (await this.latestLeafRow())?.id ?? null;
+		if (parent) {
+			const { rows } = await this.conn.execute("SELECT id FROM assistant_messages WHERE id = ? AND session_id = ?", [parent, this.sessionId]);
+			if (rows.length === 0) parent = null;
+		}
+		const json = JSON.stringify(message);
+		const text = this.extractSearchableText(json);
+		await this.conn.execute(`INSERT INTO assistant_messages (id, session_id, parent_id, role, content, text_content)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT (session_id, id) DO NOTHING`, [
+			message.id,
+			this.sessionId,
+			parent,
+			message.role,
+			json,
+			text
+		]);
+	}
+	async updateMessage(message) {
+		const json = JSON.stringify(message);
+		await this.conn.execute("UPDATE assistant_messages SET content = ?, text_content = ? WHERE id = ? AND session_id = ?", [
+			json,
+			this.extractSearchableText(json),
+			message.id,
+			this.sessionId
+		]);
+	}
+	async deleteMessages(messageIds) {
+		for (const id of messageIds) await this.conn.execute("DELETE FROM assistant_messages WHERE id = ? AND session_id = ?", [id, this.sessionId]);
+	}
+	async clearMessages() {
+		await this.conn.execute("DELETE FROM assistant_messages WHERE session_id = ?", [this.sessionId]);
+		await this.conn.execute("DELETE FROM assistant_compactions WHERE session_id = ?", [this.sessionId]);
+	}
+	async addCompaction(summary, fromMessageId, toMessageId) {
+		const id = crypto.randomUUID();
+		await this.conn.execute("INSERT INTO assistant_compactions (id, session_id, summary, from_message_id, to_message_id) VALUES (?, ?, ?, ?, ?)", [
+			id,
+			this.sessionId,
+			summary,
+			fromMessageId,
+			toMessageId
+		]);
+		return {
+			id,
+			summary,
+			fromMessageId,
+			toMessageId,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+	async getCompactions() {
+		const { rows } = await this.conn.execute("SELECT * FROM assistant_compactions WHERE session_id = ? ORDER BY created_at ASC", [this.sessionId]);
+		return rows.map((r) => ({
+			id: r.id,
+			summary: r.summary,
+			fromMessageId: r.from_message_id,
+			toMessageId: r.to_message_id,
+			createdAt: r.created_at instanceof Date ? r.created_at.toISOString() : String(r.created_at)
+		}));
+	}
+	async searchMessages(query, limit = 20) {
+		const { rows } = await this.conn.execute(`SELECT id, role, text_content FROM assistant_messages
+       WHERE session_id = ? AND content_tsv @@ plainto_tsquery('english', ?)
+       ORDER BY ts_rank(content_tsv, plainto_tsquery('english', ?)) DESC
+       LIMIT ?`, [
+			this.sessionId,
+			query,
+			query,
+			limit
+		]);
+		return rows.map((r) => ({
+			id: r.id,
+			role: r.role,
+			content: r.text_content ?? "",
+			createdAt: ""
+		}));
+	}
+	async latestLeafRow() {
+		const { rows } = await this.conn.execute(`SELECT m.id, m.content FROM assistant_messages m
+       LEFT JOIN assistant_messages c ON c.parent_id = m.id AND c.session_id = ?
+       WHERE c.id IS NULL AND m.session_id = ?
+       ORDER BY m.created_at DESC LIMIT 1`, [this.sessionId, this.sessionId]);
+		return rows[0] ?? null;
+	}
+	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_${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;
+	}
+	/**
+	* Extract just the human-readable text from a message's JSON blob
+	* and store it in `text_content`, which feeds the generated `content_tsv`
+	* column used for FTS. The full structured message (parts, tool calls,
+	* metadata) is still stored verbatim in `content` — this is the source
+	* of truth. Indexing the raw JSON would return FTS hits on keys like
+	* `"role"`, `"parts"`, `"dynamic-tool"`, etc.
+	*/
+	extractSearchableText(json) {
+		const msg = this.parse(json);
+		if (!msg) return json;
+		return msg.parts.filter((p) => p.type === "text" && p.text).map((p) => p.text).join("\n");
+	}
+};
+//#endregion
+//#region src/experimental/memory/session/providers/postgres-context.ts
+var PostgresContextProvider = class {
+	/**
+	* @param client A raw `pg.Client` (recommended) or any `PostgresConnection`.
+	*   Must already be connected.
+	* @param label Block label used as the primary key row in
+	*   `cf_agents_context_blocks`. Pass a session-scoped label (e.g.
+	*   `` `memory_${sessionId}` ``) for per-session state.
+	*/
+	constructor(client, label) {
+		this.conn = toPostgresConnection(client);
+		this.label = label;
+	}
+	async get() {
+		const { rows } = await this.conn.execute("SELECT content FROM cf_agents_context_blocks WHERE label = ?", [this.label]);
+		return rows[0]?.content ?? null;
+	}
+	async set(content) {
+		await this.conn.execute(`INSERT INTO cf_agents_context_blocks (label, content)
+       VALUES (?, ?)
+       ON CONFLICT (label) DO UPDATE SET content = EXCLUDED.content, updated_at = NOW()`, [this.label, content]);
+	}
+};
+//#endregion
+//#region src/experimental/memory/session/providers/postgres-search.ts
+var PostgresSearchProvider = class {
+	/**
+	* @param client A raw `pg.Client` (recommended) or any `PostgresConnection`.
+	*   Must already be connected.
+	*/
+	constructor(client) {
+		this.label = "";
+		this.conn = toPostgresConnection(client);
+	}
+	init(label) {
+		this.label = label;
+	}
+	async get() {
+		const { rows } = await this.conn.execute("SELECT COUNT(*) as count FROM cf_agents_search_entries WHERE label = ?", [this.label]);
+		const count = Number(rows[0]?.count ?? 0);
+		if (count === 0) return null;
+		return `${count} entries indexed.`;
+	}
+	async search(query) {
+		if (!query.trim()) return null;
+		const { rows } = await this.conn.execute(`SELECT key, content FROM cf_agents_search_entries
+       WHERE label = ? AND content_tsv @@ plainto_tsquery('english', ?)
+       ORDER BY ts_rank(content_tsv, plainto_tsquery('english', ?)) DESC
+       LIMIT 10`, [
+			this.label,
+			query,
+			query
+		]);
+		if (rows.length === 0) return "No results found.";
+		return rows.map((r) => `[${r.key}]\n${r.content}`).join("\n\n");
+	}
+	async set(key, content) {
+		await this.conn.execute(`INSERT INTO cf_agents_search_entries (label, key, content)
+       VALUES (?, ?, ?)
+       ON CONFLICT (label, key) DO UPDATE SET
+         content = EXCLUDED.content,
+         updated_at = NOW()`, [
+			this.label,
+			key,
+			content
+		]);
+	}
+};
+//#endregion
+export { AgentContextProvider, AgentSearchProvider, AgentSessionProvider, PostgresContextProvider, PostgresSearchProvider, PostgresSessionProvider, R2SkillProvider, Session, SessionManager, isSearchProvider, isSkillProvider, isWritableProvider };
 
 //# sourceMappingURL=index.js.map