@saifymatteo/pi-session-retention 0.1.5 → 0.1.6

package/src/search-cache.ts

@@ -0,0 +1,188 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, rename, unlink } from "node:fs/promises";
+import type { BigIntStats } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { finished } from "node:stream/promises";
+import { regular, safePath, type TrashBatch } from "./core.ts";
+import { safeDirectory } from "./safety.ts";
+
+export type TrashSearchText = { search: string; title: string; cwd?: string };
+const VERSION = 1;
+const CACHE_BYTES = 8 * 1024 * 1024;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const cleanText = (text: string) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim();
+const absent = (error: unknown) => (error as NodeJS.ErrnoException).code === "ENOENT";
+export const stamp = (s: BigIntStats) => {
+	const values = [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs];
+	if (values.some(value => typeof value !== "bigint")) throw new Error("Cannot verify Trash file identity or timestamp precision");
+	return values.map(String).join(":");
+};
+const changed = () => new Error("Trash files changed while reading search metadata");
+
+// regular checks every ancestor without creating anything. Use nanoseconds for
+// the fingerprint, including ctime so restoring mtime cannot hide an edit.
+export async function fileStamp(path: string): Promise<string> {
+	await regular(path);
+	const s = await lstat(path, { bigint: true });
+	if (!s.isFile() || s.isSymbolicLink()) throw new Error(`Unsafe Trash file: ${path}`);
+	return stamp(s);
+}
+
+export class TrashSearchCache {
+	private readonly root: string;
+	private readonly directory: string;
+	constructor(trashRoot: string) {
+		this.root = resolve(trashRoot);
+		this.directory = join(this.root, ".search-cache");
+	}
+
+	async read(batch: TrashBatch, signal: AbortSignal): Promise<TrashSearchText> {
+		signal.throwIfAborted();
+		// Snapshot caller-owned metadata before yielding. No cache-provided path is
+		// ever used to open a transcript, even when the cache is otherwise valid.
+		const manifest = structuredClone(batch.manifest), missing = [...batch.missing];
+		if (!manifest || manifest.version !== 1 || !uuid.test(manifest.id) || typeof manifest.ready !== "boolean" ||
+			!Number.isFinite(manifest.trashedAt) || manifest.trashedAt < 0 || !Array.isArray(manifest.files) || !manifest.files.length ||
+			missing.some(item => typeof item !== "string")) throw new Error("Invalid Trash manifest");
+		for (const [i, file] of manifest.files.entries()) {
+			if (!file || file.stored !== `${i}.jsonl` || typeof file.original !== "string" ||
+				!file.original.endsWith(".jsonl") || file.original.includes("\\") ||
+				file.original.split("/").some(part => !part || part === "." || part === ".." || part.includes(":"))) throw new Error("Invalid Trash path");
+		}
+		const missingFiles = new Set(missing);
+		const paths = manifest.files.map(file => join(this.root, manifest.id, file.stored));
+		const snapshot = async () => {
+			const stamps: (string | null)[] = [];
+			for (const [i, path] of paths.entries()) {
+				signal.throwIfAborted();
+				let value: string | null;
+				try { value = await fileStamp(path); } catch (error) { if (!absent(error)) throw error; value = null; }
+				if ((value === null) !== missingFiles.has(manifest.files[i].stored)) throw changed();
+				stamps.push(value);
+			}
+			return stamps;
+		};
+		const before = await snapshot();
+		const fingerprint = createHash("sha256").update(JSON.stringify({ manifest, missing, stamps: before })).digest("hex");
+		const verify = async () => {
+			if (JSON.stringify(await snapshot()) !== JSON.stringify(before)) throw changed();
+			signal.throwIfAborted();
+		};
+		const cached = await this.cached(manifest.id, fingerprint);
+		if (cached) { await verify(); return cached; }
+
+		const values = [manifest.id, ...manifest.files.map(file => file.original)], labels: string[] = [];
+		let cwd: string | undefined;
+		for (const [i, path] of paths.entries()) {
+			signal.throwIfAborted();
+			if (before[i] === null) continue;
+			if (await fileStamp(path) !== before[i]) throw changed();
+			const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+			try {
+				if (stamp(await handle.stat({ bigint: true })) !== before[i]) throw changed();
+				signal.throwIfAborted();
+				const stream = handle.createReadStream({ autoClose: false, signal });
+				// Attach the drain/error observer before abort can destroy the stream.
+				let streamError: unknown;
+				const drained = finished(stream).catch(error => { streamError = error; });
+				const lines = createInterface({ input: stream, crlfDelay: Infinity });
+				let name = "", firstPrompt: string | undefined, fileCwd: string | undefined;
+				try {
+					for await (const line of lines) {
+						signal.throwIfAborted();
+						let entry;
+						try { entry = JSON.parse(line); } catch { continue; }
+						if (!entry || typeof entry !== "object") continue;
+						if (entry.type === "session") { values.push(entry.id ?? "", entry.cwd ?? ""); if (fileCwd === undefined && typeof entry.cwd === "string") fileCwd = entry.cwd; }
+						if (entry.type === "session_info" && typeof entry.name === "string") name = entry.name;
+						if (firstPrompt === undefined && entry.type === "message" && entry.message?.role === "user") {
+							const content = entry.message.content;
+							firstPrompt = typeof content === "string" ? content : Array.isArray(content) ? content.filter((part: any) => part?.type === "text" && typeof part.text === "string").map((part: any) => part.text).join(" ") : "";
+						}
+					}
+					signal.throwIfAborted();
+					if (stamp(await handle.stat({ bigint: true })) !== before[i] || await fileStamp(path) !== before[i]) throw changed();
+				} finally { lines.close(); stream.destroy(); await drained; }
+				signal.throwIfAborted();
+				if (streamError) throw streamError;
+				values.push(name, firstPrompt ?? "");
+				if (cwd === undefined && fileCwd !== undefined) cwd = fileCwd;
+				labels.push(name || firstPrompt || manifest.files[i].original);
+			} finally { await handle.close(); }
+		}
+		await verify();
+		const text: TrashSearchText = { search: cleanText(values.join(" ")), title: cleanText(labels.join(" / ")) };
+		if (cwd !== undefined) text.cwd = cleanText(cwd) || undefined;
+		await this.save(manifest.id, fingerprint, text, signal, verify);
+		await verify();
+		return text;
+	}
+
+	private async cached(id: string, fingerprint: string): Promise<TrashSearchText | undefined> {
+		try {
+			const path = join(this.directory, `${id}.json`), before = await fileStamp(path);
+			const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+			try {
+				const info = await handle.stat({ bigint: true });
+				if (!info.isFile() || info.size > BigInt(CACHE_BYTES) || stamp(info) !== before) return;
+				const buffer = Buffer.alloc(Number(info.size) + 1);
+				let size = 0;
+				while (size < buffer.length) {
+					const { bytesRead } = await handle.read(buffer, size, buffer.length - size, size);
+					if (!bytesRead) break;
+					size += bytesRead;
+				}
+				if (size !== Number(info.size) || stamp(await handle.stat({ bigint: true })) !== before || await fileStamp(path) !== before) return;
+				const value = JSON.parse(buffer.subarray(0, size).toString("utf8"));
+				if (value?.version !== VERSION || value.fingerprint !== fingerprint || typeof value.search !== "string" || typeof value.title !== "string" ||
+					cleanText(value.search) !== value.search || cleanText(value.title) !== value.title ||
+					(value.cwd !== undefined && (typeof value.cwd !== "string" || cleanText(value.cwd) !== value.cwd))) return;
+				const text: TrashSearchText = { search: value.search, title: value.title };
+				if (typeof value.cwd === "string") text.cwd = value.cwd;
+				return text;
+			} finally { await handle.close(); }
+		} catch { return; } // Advisory only: unsafe, corrupt and unreadable entries are misses.
+	}
+
+	private async save(id: string, fingerprint: string, text: TrashSearchText, signal: AbortSignal, verify: () => Promise<void>) {
+		const data = JSON.stringify({ version: VERSION, fingerprint, ...text });
+		if (Buffer.byteLength(data) > CACHE_BYTES) return; // Never truncate display/search results.
+		const path = join(this.directory, `${id}.json`), temp = join(this.directory, `${id}.${randomUUID()}.tmp`);
+		let created = false;
+		try {
+			signal.throwIfAborted();
+			await safeDirectory(this.directory);
+			try { await regular(path); } catch (error) { if (!absent(error)) return; }
+			const handle = await open(temp, "wx", 0o600);
+			created = true;
+			try { await handle.writeFile(data); await handle.sync(); } finally { await handle.close(); }
+			await verify();
+			await regular(temp);
+			try { await regular(path); } catch (error) { if (!absent(error)) return; }
+			signal.throwIfAborted();
+			await rename(temp, path);
+		} catch { /* A read-only cache must not prevent fresh metadata display. */ }
+		finally { if (created) { try { await regular(temp); await unlink(temp); } catch {} } }
+	}
+
+	async remove(ids: readonly string[]): Promise<void> {
+		const selected = new Set(ids.filter(id => uuid.test(id)));
+		if (!selected.size) return;
+		let names: string[];
+		try { await safePath(this.directory); names = await readdir(this.directory); }
+		catch (error) { if (absent(error)) return; throw error; }
+		let failure: unknown;
+		for (const name of names) {
+			const match = name.match(/^([0-9a-f-]{36})(?:\.json|\.([0-9a-f-]{36})\.tmp)$/);
+			if (!match || !selected.has(match[1]) || (match[2] && !uuid.test(match[2]))) continue;
+			const path = join(this.directory, name);
+			try { await regular(path); await unlink(path); }
+			catch (error) { if (!absent(error)) failure ??= error; }
+		}
+		// The adapter reports erasure failures after the completed session operation.
+		// Include abandoned atomic-write files, which can also contain prompt text.
+		if (failure) throw failure;
+	}
+}

package/src/sessions.ts

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { otherPiProcesses, processSnapshot, withLock, RetentionBusyError, type ProcessInfo } from "./safety.ts";
+
+type RegistryOptions = { pid?: number; snapshot?: () => Promise<ProcessInfo[]>; clock?: () => number };
+/** All instances sharing an agent home cooperate through this registry, outside session stores. */
+export class SessionRegistry {
+	readonly directory: string;
+	private options: RegistryOptions;
+	private identity?: Promise<string>;
+	constructor(directory: string, options: RegistryOptions = {}) { this.directory = directory; this.options = options; }
+	private get pid() { return this.options.pid ?? process.pid; }
+	private async inventory() {
+		const items = await (this.options.snapshot ?? processSnapshot)();
+		// PID 0 is a valid OS pseudo-process (e.g. Windows System Idle Process), not an invalid inventory entry.
+		if (items.some(item => !Number.isInteger(item.pid) || item.pid < 0) || new Set(items.map(item => item.pid)).size !== items.length) throw new Error("Invalid process inventory; cleanup deferred.");
+		// Also verifies that the inventory includes this process.
+		const peers = otherPiProcesses(items, this.pid);
+		return [items.find(item => item.pid === this.pid)!, ...peers];
+	}
+	private started() {
+		return this.identity ??= this.inventory().then(items => {
+			const started = items[0].started;
+			if (typeof started !== "string" || !started) throw new Error("Cannot verify Pi process start time; cleanup deferred.");
+			return started;
+		}).catch(error => { this.identity = undefined; throw error; });
+	}
+	async register(paths: readonly string[], signal?: AbortSignal) {
+		if (paths.some(path => !isAbsolute(path))) throw new Error("Session registration requires absolute paths.");
+		const started = await this.started();
+		const publish = async () => {
+			const target = join(this.directory, `${this.pid}.json`);
+			try {
+				const info = await lstat(target);
+				if (!info.isFile() || info.isSymbolicLink()) throw new Error("Unsafe session registration.");
+			} catch (error: any) { if (error.code !== "ENOENT") throw error; }
+			const temp = join(this.directory, `${this.pid}-${randomUUID()}.tmp`);
+			const file = await open(temp, "wx", 0o600);
+			try {
+				await file.writeFile(JSON.stringify({ version: 1, pid: this.pid, started, paths: [...new Set(paths.map(path => resolve(path)))] }));
+				await file.sync();
+				await file.close();
+				await rename(temp, target);
+			} finally { await file.close(); await unlink(temp).catch(error => { if (error.code !== "ENOENT") throw error; }); }
+		};
+		for (;;) {
+			signal?.throwIfAborted();
+			try { return await withLock(this.directory, publish, ".registry.lock"); }
+			catch (error) {
+				// Startup retries contention in the background; session changes and explicit
+				// maintenance fail immediately instead of waiting behind an approval dialog.
+				if (!signal || !(error instanceof RetentionBusyError)) throw error;
+				await delay(100, undefined, { signal });
+			}
+		}
+	}
+	private async activePaths(): Promise<string[]> {
+		const paths: string[] = [];
+		for (const item of await this.inventory()) {
+			try {
+				if (typeof item.started !== "string" || !item.started) throw new Error("Missing process start time");
+				const path = join(this.directory, `${item.pid}.json`);
+				const before = await lstat(path);
+				if (!before.isFile() || before.isSymbolicLink() || before.size > 64 * 1024) throw new Error("Unsafe session registration");
+				const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+				try {
+					const info = await file.stat();
+					if (!info.isFile() || info.ino !== before.ino || info.dev !== before.dev || info.size > 64 * 1024) throw new Error("Changed session registration");
+					const record = JSON.parse(await file.readFile("utf8"));
+					if (record.version !== 1 || record.pid !== item.pid || record.started !== item.started || !Array.isArray(record.paths) || record.paths.some((p: unknown) => typeof p !== "string" || !isAbsolute(p))) throw new Error("Invalid or stale session registration");
+					paths.push(...record.paths);
+				} finally { await file.close(); }
+			} catch {
+				throw new Error(`Session maintenance deferred: Pi process ${item.pid} has no verifiable session registration. Reload/update that instance, or close it and retry /session-cleanup. Instances using another agent home must be closed.`);
+			}
+		}
+		return paths;
+	}
+	async maintain<T>(work: (activePaths: () => Promise<string[]>) => Promise<T>): Promise<T> {
+		return withLock(this.directory, async () => {
+			// The gate freezes registrations/switch intents throughout discovery and mutation.
+			// Cache successful OS inventories for at most one second to detect newcomers.
+			let checkedUntil = -Infinity;
+			let paths: string[] = [];
+			const clock = this.options.clock ?? (() => performance.now());
+			return work(async () => {
+				if (clock() >= checkedUntil) {
+					paths = await this.activePaths();
+					checkedUntil = clock() + 1000;
+				}
+				return paths;
+			});
+		}, ".registry.lock");
+	}
+}