@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/src/session/session-migrations.ts

@@ -0,0 +1,78 @@
+import { Snowflake } from "@oh-my-pi/pi-utils";
+import { type CompactionEntry, CURRENT_SESSION_VERSION, type FileEntry, type SessionHeader } from "./session-entries";
+
+/** Generate a unique short ID (8 hex chars, collision-checked) */
+export function generateId(byId: { has(id: string): boolean }): string {
+	for (let i = 0; i < 100; i++) {
+		const id = crypto.randomUUID().slice(-8);
+		if (!byId.has(id)) return id;
+	}
+	return Snowflake.next(); // fallback to full snowflake id
+}
+
+/** Migrate v1 → v2: add id/parentId tree structure. Mutates in place. */
+function migrateV1ToV2(entries: FileEntry[]): void {
+	const ids = new Set<string>();
+	let prevId: string | null = null;
+
+	for (const entry of entries) {
+		if (entry.type === "session") {
+			entry.version = 2;
+			continue;
+		}
+
+		entry.id = generateId(ids);
+		entry.parentId = prevId;
+		prevId = entry.id;
+
+		// Convert firstKeptEntryIndex to firstKeptEntryId for compaction
+		if (entry.type === "compaction") {
+			const comp = entry as CompactionEntry & { firstKeptEntryIndex?: number };
+			if (typeof comp.firstKeptEntryIndex === "number") {
+				const targetEntry = entries[comp.firstKeptEntryIndex];
+				if (targetEntry && targetEntry.type !== "session") {
+					comp.firstKeptEntryId = targetEntry.id;
+				}
+				delete comp.firstKeptEntryIndex;
+			}
+		}
+	}
+}
+
+/** Migrate v2 → v3: rename hookMessage role to custom. Mutates in place. */
+function migrateV2ToV3(entries: FileEntry[]): void {
+	for (const entry of entries) {
+		if (entry.type === "session") {
+			entry.version = 3;
+			continue;
+		}
+
+		if (entry.type === "message") {
+			const msg = entry.message as { role?: string };
+			if (msg.role === "hookMessage") {
+				(entry.message as { role: string }).role = "custom";
+			}
+		}
+	}
+}
+
+/**
+ * Run all necessary migrations to bring entries to current version.
+ * Mutates entries in place. Returns true if any migration was applied.
+ */
+export function migrateToCurrentVersion(entries: FileEntry[]): boolean {
+	const header = entries.find(e => e.type === "session") as SessionHeader | undefined;
+	const version = header?.version ?? 1;
+
+	if (version >= CURRENT_SESSION_VERSION) return false;
+
+	if (version < 2) migrateV1ToV2(entries);
+	if (version < 3) migrateV2ToV3(entries);
+
+	return true;
+}
+
+/** Exported for testing */
+export function migrateSessionEntries(entries: FileEntry[]): void {
+	migrateToCurrentVersion(entries);
+}

package/src/session/session-paths.ts

@@ -0,0 +1,193 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getTerminalId } from "@oh-my-pi/pi-tui";
+import { getSessionsDir, getTerminalSessionsDir, isEnoent, logger, resolveEquivalentPath } from "@oh-my-pi/pi-utils";
+import type { SessionStorage } from "./session-storage";
+
+const migratedSessionRoots = new Set<string>();
+
+/**
+ * Merge or rename a legacy session directory into its canonical target.
+ * Best effort: callers decide whether migration failures should surface.
+ */
+function migrateSessionDirPath(oldPath: string, newPath: string): void {
+	const existing = fs.statSync(newPath, { throwIfNoEntry: false });
+	if (existing?.isDirectory()) {
+		for (const file of fs.readdirSync(oldPath)) {
+			const src = path.join(oldPath, file);
+			const dst = path.join(newPath, file);
+			if (!fs.existsSync(dst)) {
+				fs.renameSync(src, dst);
+			}
+		}
+		fs.rmSync(oldPath, { recursive: true, force: true });
+		return;
+	}
+	if (existing) {
+		fs.rmSync(newPath, { recursive: true, force: true });
+	}
+	fs.renameSync(oldPath, newPath);
+}
+
+function encodeLegacyAbsoluteSessionDirName(cwd: string): string {
+	const resolvedCwd = path.resolve(cwd);
+	return `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+
+function encodeRelativeSessionDirName(prefix: string, relative: string): string {
+	const encoded = relative.replace(/[/\\:]/g, "-");
+	return encoded ? (prefix.endsWith("-") ? `${prefix}${encoded}` : `${prefix}-${encoded}`) : prefix;
+}
+
+function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolvedCwd: string } {
+	const resolvedCwd = path.resolve(cwd);
+	const canonicalCwd = resolveEquivalentPath(resolvedCwd);
+	const home = os.homedir();
+	const canonicalHome = resolveEquivalentPath(home);
+	const tempRoot = os.tmpdir();
+	const canonicalTempRoot = resolveEquivalentPath(tempRoot);
+	const homeRelative = path.relative(canonicalHome, canonicalCwd);
+	const tempRelative = path.relative(canonicalTempRoot, canonicalCwd);
+	const encodedDirName =
+		homeRelative === "" || (!homeRelative.startsWith("..") && !path.isAbsolute(homeRelative))
+			? encodeRelativeSessionDirName("-", homeRelative)
+			: tempRelative === "" || (!tempRelative.startsWith("..") && !path.isAbsolute(tempRelative))
+				? encodeRelativeSessionDirName("-tmp", tempRelative)
+				: encodeLegacyAbsoluteSessionDirName(canonicalCwd);
+	return { encodedDirName, resolvedCwd };
+}
+
+/**
+ * Migrate old `--<home-encoded>-*--` session dirs to the new `-*` format.
+ * Runs once per sessions root on first access, best-effort.
+ */
+function migrateHomeSessionDirs(sessionsRoot: string): void {
+	if (migratedSessionRoots.has(sessionsRoot)) return;
+	migratedSessionRoots.add(sessionsRoot);
+
+	const home = os.homedir();
+	const homeEncoded = home.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-");
+	const oldPrefix = `--${homeEncoded}-`;
+	const oldExact = `--${homeEncoded}--`;
+
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(sessionsRoot);
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		let remainder: string;
+		if (entry === oldExact) {
+			remainder = "";
+		} else if (entry.startsWith(oldPrefix) && entry.endsWith("--")) {
+			remainder = entry.slice(oldPrefix.length, -2);
+		} else {
+			continue;
+		}
+
+		const newName = remainder ? `-${remainder}` : "-";
+		const oldPath = path.join(sessionsRoot, entry);
+		const newPath = path.join(sessionsRoot, newName);
+
+		try {
+			migrateSessionDirPath(oldPath, newPath);
+		} catch {
+			// Best effort
+		}
+	}
+}
+
+function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string, sessionsRoot: string): void {
+	const legacyDir = path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(cwd));
+	if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) return;
+
+	try {
+		migrateSessionDirPath(legacyDir, sessionDir);
+	} catch {
+		// Best effort
+	}
+}
+
+export function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined {
+	const currentDirName = path.basename(sessionDir);
+	const { encodedDirName } = getDefaultSessionDirName(cwd);
+	if (currentDirName !== encodedDirName && currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)) {
+		return undefined;
+	}
+	return path.dirname(sessionDir);
+}
+
+/**
+ * Compute the default session directory for a cwd.
+ * Classifies cwd by canonical location so symlink/alias paths resolve to the
+ * same home-relative or temp-root directory names as their real targets.
+ */
+export function computeDefaultSessionDir(
+	cwd: string,
+	storage: SessionStorage,
+	sessionsRoot: string = getSessionsDir(),
+): string {
+	const { encodedDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
+	migrateHomeSessionDirs(sessionsRoot);
+	const sessionDir = path.join(sessionsRoot, encodedDirName);
+	migrateLegacyAbsoluteSessionDir(resolvedCwd, sessionDir, sessionsRoot);
+	storage.ensureDirSync(sessionDir);
+	return sessionDir;
+}
+
+// =============================================================================
+// Terminal breadcrumbs: maps terminal (TTY) -> last session file for --continue
+// =============================================================================
+
+/**
+ * Write a breadcrumb linking the current terminal to a session file.
+ * The breadcrumb contains the cwd and session path so --continue can
+ * find "this terminal's last session" even when running concurrent instances.
+ */
+export function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void {
+	const terminalId = getTerminalId();
+	if (!terminalId) return;
+
+	const breadcrumbDir = getTerminalSessionsDir();
+	const breadcrumbFile = path.join(breadcrumbDir, terminalId);
+	const content = `${cwd}\n${sessionFile}\n`;
+	// Best-effort — don't break session creation if breadcrumb fails
+	Bun.write(breadcrumbFile, content).catch(() => {});
+}
+
+export interface TerminalBreadcrumb {
+	cwd: string;
+	sessionFile: string;
+}
+
+/**
+ * Read the raw terminal breadcrumb for the current terminal.
+ * Returns the recorded cwd + session file (verified to exist) regardless of
+ * whether the recorded cwd still matches the current one. Callers decide how
+ * to interpret a cwd mismatch (e.g. a moved/renamed worktree).
+ */
+export async function readTerminalBreadcrumbEntry(): Promise<TerminalBreadcrumb | null> {
+	const terminalId = getTerminalId();
+	if (!terminalId) return null;
+
+	try {
+		const breadcrumbFile = path.join(getTerminalSessionsDir(), terminalId);
+		const content = await Bun.file(breadcrumbFile).text();
+		const lines = content.trim().split("\n");
+		if (lines.length < 2) return null;
+
+		const breadcrumbCwd = lines[0];
+		const sessionFile = lines[1];
+
+		// Verify the session file still exists
+		const stat = fs.statSync(sessionFile, { throwIfNoEntry: false });
+		if (stat?.isFile()) return { cwd: breadcrumbCwd, sessionFile };
+	} catch (err) {
+		if (!isEnoent(err)) logger.debug("Terminal breadcrumb read failed", { err });
+		// Breadcrumb doesn't exist or is corrupt — fall through
+	}
+	return null;
+}

package/src/session/session-persistence.ts

@@ -0,0 +1,131 @@
+import {
+	type BlobStore,
+	externalizeImageDataSync,
+	externalizeImageDataUrlSync,
+	isBlobRef,
+	isImageDataUrl,
+} from "./blob-store";
+import type { FileEntry } from "./session-entries";
+
+const MAX_PERSIST_CHARS = 500_000;
+const TRUNCATION_NOTICE = "\n\n[Session persistence truncated large content]";
+/** Minimum base64 length to externalize to blob store (skip tiny inline images) */
+const BLOB_EXTERNALIZE_THRESHOLD = 1024;
+const TEXT_CONTENT_KEY = "content";
+
+function truncateString(value: string, maxLength: number): string {
+	if (value.length <= maxLength) return value;
+	let truncated = value.slice(0, maxLength);
+	if (truncated.length > 0) {
+		const last = truncated.charCodeAt(truncated.length - 1);
+		if (last >= 0xd800 && last <= 0xdbff) {
+			truncated = truncated.slice(0, -1);
+		}
+	}
+	return truncated;
+}
+
+export function isImageBlock(value: unknown): value is { type: "image"; data: string; mimeType?: string } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"type" in value &&
+		(value as { type?: string }).type === "image" &&
+		"data" in value &&
+		typeof (value as { data?: string }).data === "string"
+	);
+}
+
+/**
+ * Recursively truncate large strings in an object for session persistence.
+ * - Truncates any oversized string fields (key-agnostic)
+ * - Replaces oversized image blocks with text notices
+ * - Updates lineCount when content is truncated
+ * - Returns original object if no changes needed (structural sharing)
+ *
+ * Runs in one synchronous tick so an OOM/SIGKILL landing right after a persist
+ * call returns cannot lose the entry. Image externalization happens via the
+ * synchronous blob-store path (`fs.writeFileSync`), so blob bytes are in the
+ * kernel page cache before the JSONL line referencing them is written.
+ */
+function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?: string): unknown {
+	if (obj === null || obj === undefined) return obj;
+
+	if (typeof obj === "string") {
+		if (key === "image_url" && isImageDataUrl(obj)) {
+			return externalizeImageDataUrlSync(blobStore, obj);
+		}
+		if (obj.length > MAX_PERSIST_CHARS) {
+			// Cryptographic signatures must be preserved exactly or cleared entirely — never truncated.
+			// Truncation would produce an invalid signature that the API rejects.
+			if (key === "thinkingSignature" || key === "thoughtSignature" || key === "textSignature") {
+				return "";
+			}
+			const limit = Math.max(0, MAX_PERSIST_CHARS - TRUNCATION_NOTICE.length);
+			return `${truncateString(obj, limit)}${TRUNCATION_NOTICE}`;
+		}
+		return obj;
+	}
+
+	if (Array.isArray(obj)) {
+		let changed = false;
+		const result: unknown[] = new Array(obj.length);
+		for (let i = 0; i < obj.length; i++) {
+			const item = obj[i];
+			if (
+				key === TEXT_CONTENT_KEY &&
+				isImageBlock(item) &&
+				!isBlobRef(item.data) &&
+				item.data.length >= BLOB_EXTERNALIZE_THRESHOLD
+			) {
+				changed = true;
+				result[i] = { ...item, data: externalizeImageDataSync(blobStore, item.data, item.mimeType) };
+				continue;
+			}
+			const newItem = truncateForPersistence(item, blobStore, key);
+			if (newItem !== item) changed = true;
+			result[i] = newItem;
+		}
+		return changed ? result : obj;
+	}
+
+	if (typeof obj === "object") {
+		let changed = false;
+		const entries: Array<readonly [string, unknown]> = [];
+		for (const [childKey, value] of Object.entries(obj)) {
+			// Strip transient/redundant properties that shouldn't be persisted.
+			// - partialJson: streaming accumulator for tool call JSON parsing
+			// - jsonlEvents: raw subprocess streaming events (already saved to artifact files)
+			if (childKey === "partialJson" || childKey === "jsonlEvents") {
+				changed = true;
+				continue;
+			}
+			const newValue = truncateForPersistence(value, blobStore, childKey);
+			if (newValue !== value) changed = true;
+			entries.push([childKey, newValue]);
+		}
+		if (!changed) return obj;
+
+		const contentEntry = entries.find(([childKey]) => childKey === "content");
+		const lineCountEntry = entries.find(([childKey]) => childKey === "lineCount");
+		if (
+			contentEntry &&
+			typeof contentEntry[1] === "string" &&
+			lineCountEntry &&
+			typeof lineCountEntry[1] === "number"
+		) {
+			const content = contentEntry[1];
+			const updatedEntries = entries.map(([childKey, value]) =>
+				childKey === "lineCount" ? ([childKey, content.split("\n").length] as const) : ([childKey, value] as const),
+			);
+			return Object.fromEntries(updatedEntries);
+		}
+		return Object.fromEntries(entries);
+	}
+
+	return obj;
+}
+
+export function prepareEntryForPersistence(entry: FileEntry, blobStore: BlobStore): FileEntry {
+	return truncateForPersistence(entry, blobStore) as FileEntry;
+}

package/src/session/session-storage.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent, peekFileEnds, toError } from "@oh-my-pi/pi-utils";
+import { hasFsCode, isEnoent, logger, peekFileEnds, Snowflake, toError } from "@oh-my-pi/pi-utils";
 
 const utf8Decoder = new TextDecoder("utf-8");
 
@@ -12,22 +12,17 @@ export interface SessionStorageStat {
 }
 
 export interface SessionStorageWriter {
-	writeLine(line: string): Promise<void>;
 	/**
-	 * Synchronously append a single line. Returns once the bytes are handed to the kernel
-	 * (page cache), so the data survives a non-graceful process death (OOM, SIGKILL, etc.)
-	 * even though it has not yet been fsynced to the underlying disk.
+	 * Append one newline-terminated line. File and memory storage perform the
+	 * write synchronously in-body; indexed backends queue in call order.
 	 *
-	 * `line` MUST already include the trailing newline. Throws synchronously on I/O error.
+	 * `line` MUST include the trailing newline.
 	 */
-	writeLineSync(line: string): void;
+	append(line: string): Promise<void>;
+	/** Resolve once all queued appends complete. No fsync. */
 	flush(): Promise<void>;
-	fsync(): Promise<void>;
-	/**
-	 * Synchronously fsync the underlying file descriptor. Returns once the data
-	 * is on the physical disk. Throws synchronously on I/O error.
-	 */
-	fsyncSync(): void;
+	/** False once close() has begun/finished. */
+	isOpen(): boolean;
 	close(): Promise<void>;
 	getError(): Error | undefined;
 }
@@ -44,6 +39,7 @@ export interface SessionStorage {
 	/** Read the requested UTF-8 byte windows from the head and tail of the file. */
 	readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
 	writeText(path: string, content: string): Promise<void>;
+	writeTextAtomic(path: string, content: string): Promise<void>;
 	rename(path: string, nextPath: string): Promise<void>;
 	unlink(path: string): Promise<void>;
 	deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
@@ -86,7 +82,7 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 		return error;
 	}
 
-	writeLineSync(line: string): void {
+	async append(line: string): Promise<void> {
 		if (this.#closed) throw new Error("Writer closed");
 		if (this.#error) throw this.#error;
 		try {
@@ -104,33 +100,12 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 		}
 	}
 
-	async writeLine(line: string): Promise<void> {
-		this.writeLineSync(line);
-	}
-
 	async flush(): Promise<void> {
 		if (this.#error) throw this.#error;
-		// OS buffers are flushed on fsync, nothing to do here
 	}
 
-	async fsync(): Promise<void> {
-		if (this.#closed) throw new Error("Writer closed");
-		if (this.#error) throw this.#error;
-		try {
-			fs.fsyncSync(this.#fd);
-		} catch (err) {
-			throw this.#recordError(err);
-		}
-	}
-
-	fsyncSync(): void {
-		if (this.#closed) throw new Error("Writer closed");
-		if (this.#error) throw this.#error;
-		try {
-			fs.fsyncSync(this.#fd);
-		} catch (err) {
-			throw this.#recordError(err);
-		}
+	isOpen(): boolean {
+		return !this.#closed;
 	}
 
 	async close(): Promise<void> {
@@ -204,6 +179,77 @@ export class FileSessionStorage implements SessionStorage {
 		await Bun.write(path, content, { createPath: true });
 	}
 
+	async writeTextAtomic(fpath: string, content: string): Promise<void> {
+		const dir = path.resolve(fpath, "..");
+		const tempPath = path.join(dir, `.${path.basename(fpath)}.${Snowflake.next()}.tmp`);
+		await fs.promises.mkdir(dir, { recursive: true });
+		try {
+			await fs.promises.writeFile(tempPath, content);
+			try {
+				await this.rename(tempPath, fpath);
+				return;
+			} catch (err) {
+				if (!hasFsCode(err, "EPERM")) throw toError(err);
+				await this.#replaceSessionFileAfterEperm(tempPath, fpath, err);
+				return;
+			}
+		} catch (err) {
+			try {
+				await this.unlink(tempPath);
+			} catch (cleanupErr) {
+				if (!isEnoent(cleanupErr)) {
+					logger.warn("Failed to remove session rewrite temp file", {
+						sessionFile: fpath,
+						tempPath,
+						error: toError(cleanupErr).message,
+					});
+				}
+			}
+			throw toError(err);
+		}
+	}
+
+	async #replaceSessionFileAfterEperm(tempPath: string, targetPath: string, renameError: unknown): Promise<void> {
+		const dir = path.resolve(targetPath, "..");
+		const backupPath = path.join(dir, `${path.basename(targetPath)}.${Snowflake.next()}.bak`);
+		try {
+			await this.rename(targetPath, backupPath);
+		} catch (moveAsideError) {
+			if (isEnoent(moveAsideError)) {
+				await this.rename(tempPath, targetPath);
+				return;
+			}
+			throw toError(renameError);
+		}
+		try {
+			await this.rename(tempPath, targetPath);
+		} catch (replaceError) {
+			try {
+				await this.rename(backupPath, targetPath);
+			} catch (rollbackErr) {
+				const rollbackError = toError(rollbackErr);
+				throw new Error(
+					`Failed to replace session file after EPERM (original: ${toError(renameError).message}; retry: ${
+						toError(replaceError).message
+					}; rollback: ${rollbackError.message})`,
+					{ cause: toError(renameError) },
+				);
+			}
+			throw toError(replaceError);
+		}
+		try {
+			await this.unlink(backupPath);
+		} catch (err) {
+			if (!isEnoent(err)) {
+				logger.warn("Failed to remove session rewrite backup", {
+					sessionFile: targetPath,
+					backupPath,
+					error: toError(err).message,
+				});
+			}
+		}
+	}
+
 	async rename(path: string, nextPath: string): Promise<void> {
 		try {
 			await fs.promises.rename(path, nextPath);
@@ -282,7 +328,7 @@ class MemorySessionStorageWriter implements SessionStorageWriter {
 		return error;
 	}
 
-	writeLineSync(line: string): void {
+	async append(line: string): Promise<void> {
 		if (this.#closed) throw new Error("Writer closed");
 		if (this.#error) throw this.#error;
 		try {
@@ -293,22 +339,12 @@ class MemorySessionStorageWriter implements SessionStorageWriter {
 		}
 	}
 
-	async writeLine(line: string): Promise<void> {
-		this.writeLineSync(line);
-	}
-
 	async flush(): Promise<void> {
 		if (this.#error) throw this.#error;
 	}
 
-	async fsync(): Promise<void> {
-		// No-op for in-memory storage
-		if (this.#error) throw this.#error;
-	}
-
-	fsyncSync(): void {
-		// No-op for in-memory storage
-		if (this.#error) throw this.#error;
+	isOpen(): boolean {
+		return !this.#closed;
 	}
 
 	async close(): Promise<void> {
@@ -527,6 +563,11 @@ export class MemorySessionStorage implements SessionStorage {
 		return Promise.resolve();
 	}
 
+	writeTextAtomic(path: string, content: string): Promise<void> {
+		this.writeTextSync(path, content);
+		return Promise.resolve();
+	}
+
 	rename(path: string, nextPath: string): Promise<void> {
 		const entry = this.#files.get(path);
 		if (!entry) return Promise.reject(new Error(`File not found: ${path}`));

package/src/session/snapcompact-inline.ts

@@ -32,6 +32,17 @@ export interface SnapcompactInlineOptions {
 	shape?: snapcompact.ShapeVariantName | "auto";
 }
 
+/**
+ * Reports the per-tool-result tokens kept off the wire when a swap is applied.
+ * `savedTokens` is `textTokens - frames * shape.frameTokenEstimate` for each
+ * imaged tool result (always > 0; the savings gate guarantees it). Wired to the
+ * append-only savings journal; never throws into the request path.
+ */
+export type SnapcompactSavingsSink = (
+	savings: ReadonlyArray<{ toolCallId: string; savedTokens: number }>,
+	model: Model,
+) => void;
+
 // Per-provider image-count budgets live in @oh-my-pi/snapcompact
 // (`providerImageBudget`): snapcompact frames are 1568px (<2000px) so
 // dimension/size limits never bind; only COUNT does. Once the budget is
@@ -398,7 +409,10 @@ export class SnapcompactInlineTransformer {
 	#toolCache = new Map<string, FrameCacheEntry>();
 	#systemCache?: FrameCacheEntry;
 
-	constructor(private readonly options: SnapcompactInlineOptions) {}
+	constructor(
+		private readonly options: SnapcompactInlineOptions,
+		private readonly onToolResultSavings?: SnapcompactSavingsSink,
+	) {}
 
 	transform(context: Context, model: Model): Context {
 		// Vision gate: providers silently DROP images on text-only models —
@@ -464,13 +478,19 @@ export class SnapcompactInlineTransformer {
 		});
 
 		let changed = false;
+		const savings: Array<{ toolCallId: string; savedTokens: number }> = [];
 		for (const swap of plan.toolResults) {
 			const target = targets.get(swap.id);
 			if (!target) continue;
 			const frames = this.#framesFor(this.#toolCache, swap.id, target.text, shape);
 			messages[target.index] = { ...target.message, content: [{ type: "text", text: toolResultNote }, ...frames] };
 			changed = true;
+			savings.push({
+				toolCallId: swap.id,
+				savedTokens: Math.max(0, swap.textTokens - swap.frames * shape.frameTokenEstimate),
+			});
 		}
+		if (savings.length > 0) this.onToolResultSavings?.(savings, model);
 		if (this.options.renderToolResults) {
 			// Drop cache entries for tool calls no longer in the context
 			// (compacted away) so the cache stays bounded by live history.