@code-yeongyu/senpi-codemode 2026.9.28 → 2026.9.29-3

package/src/tool/settled-image-spill.ts

@@ -0,0 +1,108 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import type { EvalToolDetails } from "./types.ts";
+
+export type SettledContentPart = AgentToolResult<EvalToolDetails>["content"][number];
+
+export interface SpilledImageRef {
+	readonly type: "spilled-image";
+	readonly path: string;
+	readonly mimeType: string;
+	readonly length: number;
+}
+
+export type RetainedContentPart = SettledContentPart | SpilledImageRef;
+
+export interface SettledImageSpillOptions {
+	readonly dir: string;
+	/** Upper bound on the spilled base64 bytes on disk; 0 keeps only the snapshot count cap. */
+	readonly byteBudget: number;
+}
+
+/**
+ * Keeps settled-cell image payloads on disk instead of the session heap (#2259). Each image is one raw
+ * base64 file; the oldest files go first beyond the byte budget (never the newest cell's), a snapshot's
+ * files go with it, and the whole directory goes on dispose.
+ */
+export class SettledImageSpill {
+	readonly #dir: string;
+	readonly #byteBudget: number;
+	readonly #files = new Map<string, { readonly cellId: string; readonly bytes: number }>();
+	#bytes = 0;
+	#sequence = 0;
+
+	constructor(options: SettledImageSpillOptions) {
+		this.#dir = options.dir;
+		this.#byteBudget = options.byteBudget;
+	}
+
+	get bytes(): number {
+		return this.#bytes;
+	}
+
+	spill(cellId: string, content: readonly SettledContentPart[]): readonly RetainedContentPart[] {
+		if (!content.some((part) => part.type === "image")) return content;
+		mkdirSync(this.#dir, { recursive: true });
+		const retained = content.map((part) => (part.type === "image" ? this.#write(cellId, part) : part));
+		this.#enforceBudget(cellId);
+		return retained;
+	}
+
+	hydrate(parts: readonly RetainedContentPart[]): SettledContentPart[] {
+		return parts.map((part) => (part.type === "spilled-image" ? readSpilledImage(part) : part));
+	}
+
+	release(parts: readonly RetainedContentPart[]): void {
+		for (const part of parts) if (part.type === "spilled-image") this.#remove(part.path);
+	}
+
+	clear(): void {
+		rmSync(this.#dir, { recursive: true, force: true });
+		this.#files.clear();
+		this.#bytes = 0;
+	}
+
+	#write(cellId: string, image: Extract<SettledContentPart, { type: "image" }>): RetainedContentPart {
+		this.#sequence += 1;
+		const path = join(this.#dir, `${cellId.replace(/[^a-zA-Z0-9_-]/gu, "_")}-${this.#sequence}.b64`);
+		try {
+			writeFileSync(path, image.data, "latin1");
+		} catch (error) {
+			// A full or read-only disk keeps this image inline, where the in-memory byte budget bounds it.
+			if (error instanceof Error && "code" in error) return image;
+			throw error;
+		}
+		this.#files.set(path, { cellId, bytes: image.data.length });
+		this.#bytes += image.data.length;
+		return { type: "spilled-image", path, mimeType: image.mimeType, length: image.data.length };
+	}
+
+	#enforceBudget(newestCellId: string): void {
+		if (this.#byteBudget <= 0) return;
+		for (const [path, file] of this.#files) {
+			if (this.#bytes <= this.#byteBudget) return;
+			if (file.cellId !== newestCellId) this.#remove(path);
+		}
+	}
+
+	#remove(path: string): void {
+		const file = this.#files.get(path);
+		if (file === undefined) return;
+		this.#files.delete(path);
+		this.#bytes -= file.bytes;
+		rmSync(path, { force: true });
+	}
+}
+
+function readSpilledImage(ref: SpilledImageRef): SettledContentPart {
+	try {
+		return { type: "image", mimeType: ref.mimeType, data: readFileSync(ref.path, "latin1") };
+	} catch (error) {
+		const reason = error instanceof Error && "code" in error ? String(error.code) : String(error);
+		return {
+			type: "text",
+			text: `[${ref.mimeType} image (${ref.length} base64 bytes) of this settled cell is no longer available: ${ref.path} (${reason})]`,
+		};
+	}
+}

package/src/tool/terminal-snapshot-store.ts

@@ -1,39 +1,111 @@
 import type { EvalDetachedCellSnapshot } from "./detached-cell-contract.ts";
+import type { RetainedContentPart, SettledContentPart, SettledImageSpill } from "./settled-image-spill.ts";
 
 export const TERMINAL_SNAPSHOT_CAP = 32;
 
-/** Bounded LRU of settled-cell snapshots; without it every settled cell pins its result and closures for the session lifetime (#1695). */
+export interface TerminalSnapshotStoreOptions {
+	readonly cap?: number;
+	/** Upper bound on the estimated in-memory bytes of all retained snapshots; 0 keeps only the count cap. */
+	readonly byteBudget?: number;
+	/** Moves image payloads to disk; without it images stay in memory under the byte budget. */
+	readonly spill?: SettledImageSpill;
+}
+
+interface StoredSnapshot {
+	/** Served by `list()`: every part except spilled images, so listing never reads the disk. */
+	readonly snapshot: EvalDetachedCellSnapshot;
+	readonly parts: readonly RetainedContentPart[];
+	readonly bytes: number;
+}
+
+/**
+ * Bounded LRU of settled-cell snapshots; without it every settled cell pins its result and closures for
+ * the session lifetime (#1695). Bounded by count and by estimated in-memory bytes, with image payloads
+ * spilled to disk and re-read on `get` (#2259); the newest snapshot is always kept.
+ */
 export class TerminalSnapshotStore {
-	readonly #snapshots = new Map<string, EvalDetachedCellSnapshot>();
+	readonly #snapshots = new Map<string, StoredSnapshot>();
 	readonly #cap: number;
+	readonly #byteBudget: number;
+	readonly #spill: SettledImageSpill | undefined;
+	#bytes = 0;
 
-	constructor(cap = TERMINAL_SNAPSHOT_CAP) {
-		this.#cap = cap;
+	constructor(options: TerminalSnapshotStoreOptions = {}) {
+		this.#cap = options.cap ?? TERMINAL_SNAPSHOT_CAP;
+		this.#byteBudget = options.byteBudget ?? 0;
+		this.#spill = options.spill;
+	}
+
+	get bytes(): number {
+		return this.#bytes;
 	}
 
 	remember(snapshot: EvalDetachedCellSnapshot): void {
-		this.#snapshots.delete(snapshot.cellId);
-		this.#snapshots.set(snapshot.cellId, snapshot);
-		while (this.#snapshots.size > this.#cap) {
+		this.delete(snapshot.cellId);
+		const content = snapshot.result.content;
+		const parts = this.#spill?.spill(snapshot.cellId, content) ?? content;
+		const inMemory = parts.filter((part): part is SettledContentPart => part.type !== "spilled-image");
+		const stored = inMemory.length === content.length ? snapshot : withContent(snapshot, inMemory);
+		const bytes = estimateSnapshotBytes(stored);
+		this.#snapshots.set(snapshot.cellId, { snapshot: stored, parts, bytes });
+		this.#bytes += bytes;
+		while (this.#snapshots.size > 1 && (this.#snapshots.size > this.#cap || this.#overBudget())) {
 			const oldest = this.#snapshots.keys().next();
 			if (oldest.done === true) break;
-			this.#snapshots.delete(oldest.value);
+			this.delete(oldest.value);
 		}
 	}
 
 	get(cellId: string): EvalDetachedCellSnapshot | undefined {
-		return this.#snapshots.get(cellId);
+		const entry = this.#snapshots.get(cellId);
+		if (
+			entry === undefined ||
+			this.#spill === undefined ||
+			entry.parts.length === entry.snapshot.result.content.length
+		)
+			return entry?.snapshot;
+		return withContent(entry.snapshot, this.#spill.hydrate(entry.parts));
 	}
 
 	delete(cellId: string): void {
+		const entry = this.#snapshots.get(cellId);
+		if (entry === undefined) return;
 		this.#snapshots.delete(cellId);
+		this.#bytes -= entry.bytes;
+		this.#spill?.release(entry.parts);
 	}
 
 	list(): readonly EvalDetachedCellSnapshot[] {
-		return [...this.#snapshots.values()];
+		return [...this.#snapshots.values()].map((entry) => entry.snapshot);
 	}
 
 	clear(): void {
 		this.#snapshots.clear();
+		this.#bytes = 0;
+		this.#spill?.clear();
+	}
+
+	#overBudget(): boolean {
+		return this.#byteBudget > 0 && this.#bytes > this.#byteBudget;
+	}
+}
+
+function withContent(
+	snapshot: EvalDetachedCellSnapshot,
+	content: readonly SettledContentPart[],
+): EvalDetachedCellSnapshot {
+	return { ...snapshot, result: { ...snapshot.result, content: [...content] } };
+}
+
+export function estimateSnapshotBytes(snapshot: EvalDetachedCellSnapshot): number {
+	let bytes = snapshot.outputTail.length * 2;
+	for (const part of snapshot.result.content) {
+		bytes += part.type === "text" ? part.text.length * 2 : part.data.length;
+	}
+	for (const cell of snapshot.result.details.cells ?? []) {
+		bytes += (cell.output.length + cell.code.length) * 2;
 	}
+	const jsonOutputs = snapshot.result.details.jsonOutputs;
+	if (jsonOutputs !== undefined && jsonOutputs.length > 0) bytes += JSON.stringify(jsonOutputs).length;
+	return bytes;
 }

package/src/tool/types.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult, AgentToolUpdateCallback, KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { type TSchema, type TUnsafe, Type } from "typebox";
+import type { KernelMemoryReport } from "../bridge/memory-protocol.ts";
 import type { HostToKernelMessage, KernelToHostMessage } from "../bridge/protocol.ts";
 import {
 	DEFAULT_FOREGROUND_WINDOW_SECONDS,
@@ -166,6 +167,11 @@ export interface EvalKernel {
 
 export interface EvalKernelManager {
 	getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel>;
+	/**
+	 * Drops the per-cell listener `getKernel` registered for `language` once that cell settled.
+	 * Identity-checked, so releasing a superseded listener never unbinds a newer cell's listener.
+	 */
+	releaseKernelListener?(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): void;
 }
 
 export type ExecuteTool = (
@@ -257,4 +263,8 @@ export interface EvalToolDetails {
 	readonly jsonOutputs?: readonly unknown[];
 	readonly notice?: string;
 	readonly meta?: TruncationMeta;
+	/** Kernel memory after the cell; its notice text is delivered as its own content part. */
+	readonly memory?: EvalMemoryDetails;
 }
+
+export type EvalMemoryDetails = Omit<KernelMemoryReport, "notice">;