agents 0.23.0 → 0.25.0

package/dist/sessions/index.js

@@ -1,6 +1,6 @@
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "../classPrivateFieldGet2-DZBYAB34.js";
-import { t as LifecycleCapability } from "../capability-BjSKYpzg.js";
 import { t as _classPrivateMethodInitSpec } from "../classPrivateMethodInitSpec-qMjJ6sHQ.js";
+import { t as LifecycleCapability } from "../capability-B4WbF81e.js";
 import { SqlError } from "../sql-error.js";
 import { n as sanitizeMessage, t as byteLength } from "../sanitize-D9TujEK8.js";
 import { i as estimatedDataUrlBytes, n as estimateMessageTokens, r as estimateStringTokens, t as estimateAttachmentTokens } from "../tokens-nHAKcN6M.js";
@@ -396,22 +396,46 @@ function extractAttachments(message) {
 	};
 	if (message.parts.length === 0) return {
 		message,
-		attachments
+		attachments,
+		references: []
 	};
 	const parts = walk(message.parts, 0);
+	const references = [...pointersOf(parts)];
 	if (parts === message.parts) return {
 		message,
-		attachments
+		attachments,
+		references
 	};
 	return {
 		message: {
 			...message,
 			parts
 		},
-		attachments
+		attachments,
+		references
 	};
 }
 /**
+* The attachment addresses a read of this stored form restores. It walks
+* exactly as {@link resolveAttachments} does, so a message holds a reference
+* for every pointer a read would put back and for nothing else.
+*/
+function pointersOf(value, into = /* @__PURE__ */ new Set(), depth = 0) {
+	if (depth > MAX_WALK_DEPTH || value === null || typeof value !== "object") return into;
+	if (Array.isArray(value)) {
+		for (const entry of value) pointersOf(entry, into, depth + 1);
+		return into;
+	}
+	const record = value;
+	const hash = parseAttachmentUrl(record.url) ?? parseAttachmentUrl(record.data);
+	if (hash) {
+		into.add(hash);
+		return into;
+	}
+	for (const entry of Object.values(record)) pointersOf(entry, into, depth + 1);
+	return into;
+}
+/**
 * Put payloads back inline, undoing extraction exactly.
 *
 * A pointer whose bytes cannot be loaded is left as it is: an unresolvable
@@ -747,6 +771,38 @@ const NEWEST_FIRST_WINDOW_ROWS = 8;
 * recent rows only, and `getRecentHistory` reports that as truncated.
 */
 const MAX_PATH_DEPTH = 1e4;
+/**
+* Hidden overlay rows: a stored `compaction_<id>` row whose `<id>` names one
+* of the session's own compaction records, so it duplicates an overlay the
+* session renders itself. Writes refuse overlays, but sessions written before
+* that guard (#1984) can hold one, usually with later rows parented to it.
+* Reads skip such a row and walk through it, so its children take its place.
+* A `compaction_` row with no matching record, such as a summary imported
+* from another session's history, is the only copy of that context and stays
+* visible.
+*/
+function hasOverlayPrefix(id) {
+	return id.startsWith(COMPACTION_PREFIX);
+}
+/**
+* SQL twin of the hidden-overlay test for the row id in `idColumn` of the
+* session in `sessionExpr`. The record lookup runs only for prefixed ids.
+* Both must be table-qualified: inside the lookup an unqualified `id` or
+* `session_id` binds to the compactions table, not the row being tested.
+*/
+function hiddenOverlayRowSql(idColumn, sessionExpr) {
+	return `(substr(${idColumn}, 1, 11) = '${COMPACTION_PREFIX}'
+    AND EXISTS (SELECT 1 FROM cf_agents_session_compactions oc
+      WHERE oc.session_id = ${sessionExpr}
+        AND oc.id = substr(${idColumn}, 12)))`;
+}
+/**
+* Digest of a message's stored form, stamped on the row by every write, so an
+* update can decide "unchanged" without reading the stored content back.
+*/
+function contentDigest(json) {
+	return createHash("sha256").update(json, "utf8").digest("hex");
+}
 var _reservedMetadataKeys = /* @__PURE__ */ new WeakMap();
 var _listeners = /* @__PURE__ */ new WeakMap();
 var _tails = /* @__PURE__ */ new WeakMap();
@@ -782,8 +838,10 @@ var SessionsCore = class {
         content_chunks INTEGER NOT NULL DEFAULT 0,
         token_estimate INTEGER NOT NULL DEFAULT 0,
         created_at INTEGER NOT NULL,
+        content_hash TEXT,
         PRIMARY KEY (session_id, id)
       ) WITHOUT ROWID`, []);
+		_assertClassBrand(_SessionsCore_brand, this, _addMessageContentHashColumn).call(this);
 		this.io.sqlWrite(`CREATE TABLE IF NOT EXISTS cf_agents_session_message_chunks (
         session_id TEXT NOT NULL,
         id TEXT NOT NULL,
@@ -923,12 +981,15 @@ var SessionsCore = class {
 		return _assertClassBrand(_SessionsCore_brand, this, _tail).call(this, sessionId).leafId;
 	}
 	getLatestLeaf(sessionId) {
-		const leafId = this.latestLeafId(sessionId);
+		let leafId = this.latestLeafId(sessionId);
+		while (leafId !== null && _assertClassBrand(_SessionsCore_brand, this, _hiddenOverlayIds).call(this, sessionId, [leafId]).has(leafId)) {
+			const [row] = this.io.sql("SELECT parent_id FROM cf_agents_session_messages WHERE session_id = ? AND id = ?", [sessionId, leafId]);
+			leafId = row?.parent_id ?? null;
+		}
 		return leafId ? this.getMessage(sessionId, leafId) : null;
 	}
 	getBranches(sessionId, messageId) {
-		const rows = this.io.sql(`SELECT id, content, content_chunks FROM cf_agents_session_messages
-       WHERE session_id = ? AND parent_id = ? ORDER BY seq ASC`, [sessionId, messageId]);
+		const rows = _assertClassBrand(_SessionsCore_brand, this, _childRows).call(this, sessionId, messageId);
 		const continued = _assertClassBrand(_SessionsCore_brand, this, _continuations).call(this, sessionId, rows.filter((row) => row.content_chunks > 0).map((row) => row.id));
 		const result = [];
 		for (const row of rows) {
@@ -946,38 +1007,7 @@ var SessionsCore = class {
 	* budget over these rows bounds real hydrated memory.
 	*/
 	pathRowStats(sessionId, leafId) {
-		const leaf = _assertClassBrand(_SessionsCore_brand, this, _resolveLeafId).call(this, sessionId, leafId);
-		if (!leaf) return [];
-		return this.io.sql(`WITH RECURSIVE path(id, parent_id, depth) AS (
-        SELECT id, parent_id, 0 FROM cf_agents_session_messages
-        WHERE session_id = ? AND id = ?
-        UNION ALL
-        SELECT m.id, m.parent_id, p.depth + 1 FROM cf_agents_session_messages m
-        JOIN path p ON m.id = p.parent_id
-        WHERE m.session_id = ? AND p.depth < ${MAX_PATH_DEPTH}
-      )
-      SELECT path.id AS id, am.role AS role,
-        LENGTH(CAST(am.content AS BLOB)) + CASE WHEN am.content_chunks = 0 THEN 0
-          ELSE COALESCE((
-            SELECT SUM(LENGTH(CAST(c.content AS BLOB)))
-            FROM cf_agents_session_message_chunks c
-            WHERE c.session_id = am.session_id AND c.id = am.id
-          ), 0) END
-        + COALESCE((
-            SELECT SUM((meta.bytes + 2) / 3 * 4)
-            FROM cf_agents_session_attachment_refs r
-            JOIN cf_agents_session_attachment_meta meta ON meta.hash = r.hash
-            WHERE r.session_id = am.session_id AND r.message_id = am.id
-          ), 0) AS bytes,
-        am.token_estimate AS tokenEstimate
-      FROM path JOIN cf_agents_session_messages am
-        ON am.session_id = ? AND am.id = path.id
-      ORDER BY path.depth DESC`, [
-			sessionId,
-			leaf,
-			sessionId,
-			sessionId
-		]);
+		return _assertClassBrand(_SessionsCore_brand, this, _pathRows).call(this, sessionId, leafId).rows;
 	}
 	/**
 	* Stream the path ending at `leafId` (default: active leaf), root → leaf
@@ -1010,7 +1040,7 @@ var SessionsCore = class {
 	* skipped, showing the raw recent messages.
 	*/
 	async getRecentHistory(sessionId, maxContentBytes, leafId) {
-		const stats = this.pathRowStats(sessionId, leafId);
+		const { rows: stats, walked, oldestId } = _assertClassBrand(_SessionsCore_brand, this, _pathRows).call(this, sessionId, leafId);
 		if (stats.length === 0) return {
 			messages: [],
 			truncated: false,
@@ -1027,7 +1057,7 @@ var SessionsCore = class {
 		}
 		const messages = [];
 		for await (const message of _assertClassBrand(_SessionsCore_brand, this, _streamStats).call(this, sessionId, stats.slice(start))) messages.push(message);
-		const capped = stats.length > MAX_PATH_DEPTH && _assertClassBrand(_SessionsCore_brand, this, _hasParent).call(this, sessionId, stats[0].id);
+		const capped = walked > MAX_PATH_DEPTH && oldestId !== null && _assertClassBrand(_SessionsCore_brand, this, _hasParent).call(this, sessionId, oldestId);
 		return {
 			messages,
 			truncated: start > 0 || capped,
@@ -1044,7 +1074,7 @@ var SessionsCore = class {
 		const leafId = this.latestLeafId(sessionId);
 		const memo = _classPrivateFieldGet2(_pathTokens, this).get(sessionId);
 		if (memo && memo.leafId === leafId) return Math.max(0, Math.ceil(memo.total));
-		const stats = this.pathRowStats(sessionId);
+		const { rows: stats, walked } = _assertClassBrand(_SessionsCore_brand, this, _pathRows).call(this, sessionId);
 		const counted = new Set(stats.map((row) => row.id));
 		let tokens = stats.reduce((sum, row) => sum + row.tokenEstimate, 0);
 		for (const span of planOverlays(stats.map((row) => row.id), this.getCompactions(sessionId))) {
@@ -1058,7 +1088,7 @@ var SessionsCore = class {
 			leafId,
 			counted,
 			total: tokens,
-			depth: stats.length
+			depth: walked
 		});
 		return Math.max(0, Math.ceil(tokens));
 	}
@@ -1109,14 +1139,15 @@ var SessionsCore = class {
 		let parent;
 		if (parentId === void 0) parent = tail.leafId;
 		else parent = parentId && this.exists(sessionId, parentId) ? parentId : null;
-		const { message: staged, attachments } = extractAttachments(message);
-		const slices = splitContent(JSON.stringify(staged));
+		const { message: staged, attachments, references } = extractAttachments(message);
+		const json = JSON.stringify(staged);
+		const slices = splitContent(json);
 		const seq = tail.nextSeq;
 		this.io.transaction(() => {
 			for (const attachment of attachments) _classPrivateFieldGet2(_attachments, this).put(attachment.payload, attachment.hash);
 			this.io.sqlWrite(`INSERT INTO cf_agents_session_messages
-          (session_id, id, seq, parent_id, role, content, content_chunks, token_estimate, created_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+          (session_id, id, seq, parent_id, role, content, content_chunks, token_estimate, created_at, content_hash)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
 				sessionId,
 				message.id,
 				seq,
@@ -1125,10 +1156,11 @@ var SessionsCore = class {
 				slices[0],
 				slices.length - 1,
 				tokenEstimate,
-				Date.now()
+				Date.now(),
+				contentDigest(json)
 			]);
 			_assertClassBrand(_SessionsCore_brand, this, _writeContinuations).call(this, sessionId, message.id, slices);
-			_classPrivateFieldGet2(_attachments, this).addRefs(sessionId, message.id, attachments.map((attachment) => attachment.hash));
+			_classPrivateFieldGet2(_attachments, this).addRefs(sessionId, message.id, references);
 			_assertClassBrand(_SessionsCore_brand, this, _indexFts).call(this, sessionId, staged, false);
 		});
 		_classPrivateFieldGet2(_tails, this).set(sessionId, {
@@ -1155,26 +1187,38 @@ var SessionsCore = class {
 	/**
 	* Durable update of an existing row. An identical row writes nothing: no
 	* row, no continuation, no FTS, no event. The no-op guard compares the
-	* FULL reassembled content, not just the slice the message row holds.
+	* FULL content, through the digest the last write stamped, so neither the
+	* payload nor a continuation row is read. A row without a digest compares
+	* the reassembled content once and is stamped.
 	*/
 	update(sessionId, message, tokenEstimate) {
-		const oldRows = this.io.sql("SELECT content, content_chunks, token_estimate FROM cf_agents_session_messages WHERE session_id = ? AND id = ?", [sessionId, message.id]);
+		const oldRows = this.io.sql("SELECT content_chunks, token_estimate, content_hash FROM cf_agents_session_messages WHERE session_id = ? AND id = ?", [sessionId, message.id]);
 		if (oldRows.length === 0) return "missing";
 		const old = oldRows[0];
-		const oldContent = old.content_chunks === 0 ? old.content : old.content + (_assertClassBrand(_SessionsCore_brand, this, _continuations).call(this, sessionId, [message.id]).get(message.id) ?? "");
-		const { message: staged, attachments } = extractAttachments(message);
+		const { message: staged, attachments, references } = extractAttachments(message);
 		const json = JSON.stringify(staged);
-		if (oldContent === json) return "unchanged";
+		const digest = contentDigest(json);
+		if (old.content_hash !== null) {
+			if (old.content_hash === digest) return "unchanged";
+		} else if (_assertClassBrand(_SessionsCore_brand, this, _content).call(this, sessionId, message.id) === json) {
+			this.io.sqlWrite("UPDATE cf_agents_session_messages SET content_hash = ? WHERE session_id = ? AND id = ?", [
+				digest,
+				sessionId,
+				message.id
+			]);
+			return "unchanged";
+		}
 		const slices = splitContent(json);
 		this.io.transaction(() => {
 			for (const attachment of attachments) _classPrivateFieldGet2(_attachments, this).put(attachment.payload, attachment.hash);
 			this.io.sqlWrite(`UPDATE cf_agents_session_messages
-         SET role = ?, content = ?, content_chunks = ?, token_estimate = ?
+         SET role = ?, content = ?, content_chunks = ?, token_estimate = ?, content_hash = ?
          WHERE session_id = ? AND id = ?`, [
 				message.role,
 				slices[0],
 				slices.length - 1,
 				tokenEstimate,
+				digest,
 				sessionId,
 				message.id
 			]);
@@ -1185,7 +1229,7 @@ var SessionsCore = class {
 				slices.length - 1
 			]);
 			_assertClassBrand(_SessionsCore_brand, this, _writeContinuations).call(this, sessionId, message.id, slices);
-			_classPrivateFieldGet2(_attachments, this).replaceRefs(sessionId, message.id, attachments.map((attachment) => attachment.hash));
+			_classPrivateFieldGet2(_attachments, this).replaceRefs(sessionId, message.id, references);
 			_assertClassBrand(_SessionsCore_brand, this, _indexFts).call(this, sessionId, staged, true);
 		});
 		const memo = _classPrivateFieldGet2(_pathTokens, this).get(sessionId);
@@ -1316,6 +1360,7 @@ var SessionsCore = class {
          INNER JOIN cf_agents_session_messages m
            ON m.session_id = f.session_id AND m.id = f.id
          WHERE cf_agents_session_fts MATCH ? AND f.session_id = ?
+           AND NOT ${hiddenOverlayRowSql("f.id", "f.session_id")}
          ORDER BY rank LIMIT ?`, [
 			sanitized,
 			sessionId,
@@ -1332,15 +1377,16 @@ var SessionsCore = class {
 	*/
 	/** Returns `false` when the id already exists and nothing was written. */
 	importMessage(sessionId, message, options) {
-		const { message: staged, attachments } = extractAttachments(message);
-		const slices = splitContent(JSON.stringify(staged));
+		const { message: staged, attachments, references } = extractAttachments(message);
+		const json = JSON.stringify(staged);
+		const slices = splitContent(json);
 		const tail = _assertClassBrand(_SessionsCore_brand, this, _tail).call(this, sessionId);
 		let inserted = 0;
 		this.io.transaction(() => {
 			for (const attachment of attachments) _classPrivateFieldGet2(_attachments, this).put(attachment.payload, attachment.hash);
 			inserted = this.io.sqlWrite(`INSERT OR IGNORE INTO cf_agents_session_messages
-          (session_id, id, seq, parent_id, role, content, content_chunks, token_estimate, created_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+          (session_id, id, seq, parent_id, role, content, content_chunks, token_estimate, created_at, content_hash)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
 				sessionId,
 				message.id,
 				tail.nextSeq,
@@ -1349,11 +1395,12 @@ var SessionsCore = class {
 				slices[0],
 				slices.length - 1,
 				this.estimateRowTokens(message),
-				options.createdAt
+				options.createdAt,
+				contentDigest(json)
 			]);
 			if (inserted === 0) return;
 			_assertClassBrand(_SessionsCore_brand, this, _writeContinuations).call(this, sessionId, message.id, slices);
-			_classPrivateFieldGet2(_attachments, this).addRefs(sessionId, message.id, attachments.map((attachment) => attachment.hash));
+			_classPrivateFieldGet2(_attachments, this).addRefs(sessionId, message.id, references);
 			_assertClassBrand(_SessionsCore_brand, this, _indexFts).call(this, sessionId, staged, false);
 		});
 		if (inserted === 0) return false;
@@ -1365,6 +1412,15 @@ var SessionsCore = class {
 		return true;
 	}
 };
+/**
+* Add the digest column to a message table that predates it. Nullable, so
+* no existing row is rewritten; a `null` digest falls back to reading the
+* row back once.
+*/
+function _addMessageContentHashColumn() {
+	if (this.io.sql("SELECT name FROM pragma_table_info('cf_agents_session_messages')", []).map((row) => row.name).includes("content_hash")) return;
+	this.io.sqlWrite("ALTER TABLE cf_agents_session_messages ADD COLUMN content_hash TEXT", []);
+}
 function _tableExists(name) {
 	return this.io.sql("SELECT name FROM sqlite_master WHERE type IN ('table', 'view') AND name = ?", [name]).length > 0;
 }
@@ -1448,6 +1504,74 @@ function _resolveLeafId(sessionId, leafId) {
 	return this.latestLeafId(sessionId);
 }
 /**
+* Which of `ids` are hidden overlay rows. Reads the session's compaction
+* records only when some id carries the prefix.
+*/
+function _hiddenOverlayIds(sessionId, ids) {
+	if (!ids.some(hasOverlayPrefix)) return /* @__PURE__ */ new Set();
+	const overlays = new Set(this.getCompactions(sessionId).map((compaction) => `${COMPACTION_PREFIX}${compaction.id}`));
+	return new Set(ids.filter((id) => overlays.has(id)));
+}
+/** Children of a row in `seq` order, hidden overlay rows replaced by theirs. */
+function _childRows(sessionId, parentId) {
+	const rows = this.io.sql(`SELECT id, seq, content, content_chunks FROM cf_agents_session_messages
+       WHERE session_id = ? AND parent_id = ? ORDER BY seq ASC`, [sessionId, parentId]);
+	const hidden = _assertClassBrand(_SessionsCore_brand, this, _hiddenOverlayIds).call(this, sessionId, rows.map((row) => row.id));
+	if (hidden.size === 0) return rows;
+	return rows.flatMap((row) => hidden.has(row.id) ? _assertClassBrand(_SessionsCore_brand, this, _childRows).call(this, sessionId, row.id) : [row]).sort((a, b) => a.seq - b.seq);
+}
+/**
+* `pathRowStats` plus what the walk itself saw: the path cap counts stored
+* rows, hidden overlay rows included, so whether the walk was cut short
+* is judged from the unfiltered path.
+*/
+function _pathRows(sessionId, leafId) {
+	const leaf = _assertClassBrand(_SessionsCore_brand, this, _resolveLeafId).call(this, sessionId, leafId);
+	if (!leaf) return {
+		rows: [],
+		walked: 0,
+		oldestId: null
+	};
+	const walked = this.io.sql(`WITH RECURSIVE path(id, parent_id, depth) AS (
+        SELECT id, parent_id, 0 FROM cf_agents_session_messages
+        WHERE session_id = ? AND id = ?
+        UNION ALL
+        SELECT m.id, m.parent_id, p.depth + 1 FROM cf_agents_session_messages m
+        JOIN path p ON m.id = p.parent_id
+        WHERE m.session_id = ? AND p.depth < ${MAX_PATH_DEPTH}
+      )
+      SELECT path.id AS id, am.role AS role,
+        LENGTH(CAST(am.content AS BLOB)) + CASE WHEN am.content_chunks = 0 THEN 0
+          ELSE COALESCE((
+            SELECT SUM(LENGTH(CAST(c.content AS BLOB)))
+            FROM cf_agents_session_message_chunks c
+            WHERE c.session_id = am.session_id AND c.id = am.id
+          ), 0) END
+        + COALESCE((
+            SELECT SUM((meta.bytes + 2) / 3 * 4)
+            FROM cf_agents_session_attachment_refs r
+            JOIN cf_agents_session_attachment_meta meta ON meta.hash = r.hash
+            WHERE r.session_id = am.session_id AND r.message_id = am.id
+          ), 0) AS bytes,
+        am.token_estimate AS tokenEstimate,
+        ${hiddenOverlayRowSql("path.id", "am.session_id")} AS hidden
+      FROM path JOIN cf_agents_session_messages am
+        ON am.session_id = ? AND am.id = path.id
+      ORDER BY path.depth DESC`, [
+		sessionId,
+		leaf,
+		sessionId,
+		sessionId
+	]);
+	const rows = [];
+	for (const { hidden, ...row } of walked) if (!hidden) rows.push(row);
+	return {
+		rows,
+		walked: walked.length,
+		oldestId: walked[0]?.id ?? null
+	};
+}
+/**
 * The active branch path as ids alone, root → leaf. The cheapest walk the
 * tree allows — one row per step, following `parent_id` by primary key —
 * for readers that will hydrate only a few rows and do not need the sizes
@@ -1464,9 +1588,12 @@ function _pathIds(sessionId, leafId) {
           JOIN path p ON m.id = p.parent_id
           WHERE m.session_id = ? AND p.depth < ${MAX_PATH_DEPTH}
         )
-        SELECT id FROM path ORDER BY depth DESC`, [
+        SELECT path.id AS id FROM path
+        WHERE NOT ${hiddenOverlayRowSql("path.id", "?")}
+        ORDER BY depth DESC`, [
 		sessionId,
 		leaf,
+		sessionId,
 		sessionId
 	]).map((row) => row.id);
 }
@@ -1569,6 +1696,7 @@ async function* _streamStats(sessionId, stats, signal, newestFirst = false, plan
 async function* _walkFromLeaf(sessionId, leafId, signal) {
 	const compactions = this.getCompactions(sessionId);
 	const spanEnds = new Set(compactions.map((c) => c.toMessageId));
+	const hiddenIds = new Set(compactions.map((c) => `${COMPACTION_PREFIX}${c.id}`));
 	let next = _assertClassBrand(_SessionsCore_brand, this, _resolveLeafId).call(this, sessionId, leafId);
 	let depth = 0;
 	while (next !== null && depth <= MAX_PATH_DEPTH) {
@@ -1580,9 +1708,11 @@ async function* _walkFromLeaf(sessionId, leafId, signal) {
 		const [row] = this.io.sql(`SELECT parent_id, content, content_chunks FROM cf_agents_session_messages
          WHERE session_id = ? AND id = ?`, [sessionId, next]);
 		if (!row) return;
-		const json = row.content_chunks === 0 ? row.content : row.content + (_assertClassBrand(_SessionsCore_brand, this, _continuations).call(this, sessionId, [next]).get(next) ?? "");
-		const parsed = _assertClassBrand(_SessionsCore_brand, this, _parse).call(this, json);
-		if (parsed) yield _assertClassBrand(_SessionsCore_brand, this, _inline).call(this, parsed);
+		if (!hiddenIds.has(next)) {
+			const json = row.content_chunks === 0 ? row.content : row.content + (_assertClassBrand(_SessionsCore_brand, this, _continuations).call(this, sessionId, [next]).get(next) ?? "");
+			const parsed = _assertClassBrand(_SessionsCore_brand, this, _parse).call(this, json);
+			if (parsed) yield _assertClassBrand(_SessionsCore_brand, this, _inline).call(this, parsed);
+		}
 		next = row.parent_id;
 		depth++;
 	}
@@ -1649,6 +1779,50 @@ function _parse(json) {
 	return null;
 }
 //#endregion
+//#region src/sessions/mirror.ts
+/**
+* The default reduction, per event:
+*
+* - `append` of a new row: replace the cached entry with its id, or push it.
+*   A duplicate append (`inserted: false`) changed nothing.
+* - `update`: replace the cached entry with its id; a row the cache does not
+*   hold stays out.
+* - `delete`: drop the removed ids. `clear`: empty the cache.
+* - `import`, `compact`, `compaction`: nothing, since no in-place patch
+*   expresses them. A host that must react intercepts them.
+*/
+function mirrorSessionChanges(subscribe, sessionId, options) {
+	const transform = options.transform ?? ((message) => message);
+	return subscribe(async (event) => {
+		if (event.sessionId !== sessionId) return;
+		if (await options.intercept?.(event)) return;
+		switch (event.type) {
+			case "append":
+			case "update": {
+				if (event.type === "append" && !event.inserted) return;
+				const cache = options.get();
+				const index = cache.findIndex((m) => m.id === event.message.id);
+				if (index === -1 && event.type === "update") return;
+				const message = transform(event.message);
+				const previous = index === -1 ? void 0 : cache[index];
+				if (index === -1) cache.push(message);
+				else cache[index] = message;
+				options.onApplied?.(event, message, previous);
+				return;
+			}
+			case "delete": {
+				const removed = new Set(event.messageIds);
+				options.set(options.get().filter((m) => !removed.has(m.id)));
+				return;
+			}
+			case "clear":
+				options.set([]);
+				return;
+			default: return;
+		}
+	});
+}
+//#endregion
 //#region src/sessions/handle.ts
 var _core$1 = /* @__PURE__ */ new WeakMap();
 var _ready = /* @__PURE__ */ new WeakMap();
@@ -1682,6 +1856,13 @@ var Session = class {
 		return this;
 	}
 	/**
+	* Keep an in-memory transcript in step with this session's change feed,
+	* so write sites never hand-patch it. Returns the unsubscribe function.
+	*/
+	mirror(options) {
+		return mirrorSessionChanges((listener) => _classPrivateFieldGet2(_core$1, this).subscribe(listener), this.sessionId, options);
+	}
+	/**
 	* Stream the active branch path root → leaf (leaf → root with
 	* `newestFirst`) with compaction overlays applied. Peak memory is one
 	* bounded content window, never the whole transcript, and a consumer that
@@ -1768,9 +1949,18 @@ var Session = class {
 	/**
 	* Append one message. Idempotent on id: a repeated append returns the row
 	* already stored and dispatches an `append` event with `inserted: false`.
+	*
+	* A compaction overlay (a `compaction_` id) is derived on read and is never
+	* stored. Clients post their transcript back after every compaction, so
+	* this and every other write drops one silently: nothing is written and no
+	* event is dispatched.
 	*/
 	async appendMessage(message, options = {}) {
 		await _classPrivateFieldGet2(_ready, this).call(this);
+		if (isCompactionMessage(message)) return {
+			inserted: false,
+			message
+		};
 		const prepared = _assertClassBrand(_Session_brand, this, _prepare).call(this, message, options.source);
 		const result = _classPrivateFieldGet2(_core$1, this).append(this.sessionId, prepared.message, options.parentId, prepared.tokenEstimate);
 		await _classPrivateFieldGet2(_core$1, this).notify({
@@ -1786,10 +1976,12 @@ var Session = class {
 	/**
 	* Update one stored row. Returns the stored form, or `null` when the id is
 	* not in this session. An unchanged message writes nothing and dispatches
-	* no event.
+	* no event. A compaction overlay is never a stored row, so it reports
+	* `null`.
 	*/
 	async updateMessage(message, options = {}) {
 		await _classPrivateFieldGet2(_ready, this).call(this);
+		if (isCompactionMessage(message)) return null;
 		const prepared = _assertClassBrand(_Session_brand, this, _prepare).call(this, message, options.source);
 		const outcome = _classPrivateFieldGet2(_core$1, this).update(this.sessionId, prepared.message, prepared.tokenEstimate);
 		if (outcome === "missing") return null;
@@ -1817,6 +2009,13 @@ var Session = class {
 		return {
 			abandon: () => _classPrivateFieldGet2(_core$1, this).forgetCaches(this.sessionId),
 			upsert: (message, options = {}) => {
+				if (isCompactionMessage(message)) return {
+					result: {
+						inserted: false,
+						message
+					},
+					after: () => Promise.resolve()
+				};
 				const prepared = _assertClassBrand(_Session_brand, this, _prepare).call(this, message, options.source);
 				if (!_classPrivateFieldGet2(_core$1, this).exists(this.sessionId, message.id)) {
 					const result = _classPrivateFieldGet2(_core$1, this).append(this.sessionId, prepared.message, options.parentId, prepared.tokenEstimate);
@@ -1851,6 +2050,10 @@ var Session = class {
 	}
 	async upsertMessage(message, options = {}) {
 		await _classPrivateFieldGet2(_ready, this).call(this);
+		if (isCompactionMessage(message)) return {
+			inserted: false,
+			message
+		};
 		if (!_classPrivateFieldGet2(_core$1, this).exists(this.sessionId, message.id)) return this.appendMessage(message, options);
 		return {
 			inserted: false,
@@ -1863,6 +2066,12 @@ var Session = class {
 	* `import` change event so a host cache can mark itself stale; it is not
 	* an `append`, so a cache does not patch itself per imported row, and an
 	* id that already exists writes nothing and dispatches nothing.
+	*
+	* Unlike the other writes, a `compaction_` id is imported as given: a
+	* summary copied from another session's `history()` is the only record of
+	* the context it replaced, and later rows may be parented to it. History
+	* reads hide such a row only when it duplicates one of this session's own
+	* compaction overlays.
 	*/
 	async importMessage(message, options) {
 		await _classPrivateFieldGet2(_ready, this).call(this);