pi-agent-browser-native 0.2.33 → 0.2.35

package/extensions/agent-browser/lib/session-page-state.ts

@@ -6,6 +6,7 @@
  * Invariants/Assumptions: One tool-call update token must govern all page-state observations from that invocation; stale overlapping updates must not overwrite newer state.
  */
 
+import { isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 
 export interface SessionTabTarget {
@@ -20,6 +21,7 @@ interface OrderedSessionTabTarget {
 
 export interface SessionRefSnapshot {
 	refIds: string[];
+	refs?: Record<string, { name: string; role: string }>;
 	target?: SessionTabTarget;
 }
 
@@ -132,12 +134,6 @@ function extractBatchResultCommand(item: Record<string, unknown>): string[] {
 	return Array.isArray(item.command) ? item.command.filter((token): token is string => typeof token === "string") : [];
 }
 
-const READ_ONLY_DIAGNOSTIC_SESSION_TARGET_COMMANDS = new Set(["console", "cookies", "errors", "network", "storage"]);
-
-function isReadOnlyDiagnosticSessionTargetCommand(command: string | undefined, _subcommand: string | undefined): boolean {
-	return command !== undefined && READ_ONLY_DIAGNOSTIC_SESSION_TARGET_COMMANDS.has(command);
-}
-
 export function extractSessionTabTargetFromCommandData(commandTokens: string[], data: unknown): SessionTabTarget | undefined {
 	const [command, subcommand] = commandTokens;
 	return isReadOnlyDiagnosticSessionTargetCommand(command, subcommand) ? undefined : extractSessionTabTargetFromData(data);
@@ -186,7 +182,7 @@ export function deriveSessionTabTarget(options: {
 	previousTarget?: SessionTabTarget;
 	subcommand?: string;
 }): SessionTabTarget | undefined {
-	if (options.command === "close") {
+	if (isCloseCommand(options.command)) {
 		return undefined;
 	}
 	const commandDataTarget = isReadOnlyDiagnosticSessionTargetCommand(options.command, options.subcommand)
@@ -234,10 +230,21 @@ function getRestoredSessionTabTarget(details: Record<string, unknown>, command:
 	return storedTarget;
 }
 
+function extractRefSnapshotRefs(data: unknown): Record<string, { name: string; role: string }> | undefined {
+	if (!isRecord(data) || !isRecord(data.refs)) return undefined;
+	const refs = Object.fromEntries(Object.entries(data.refs).flatMap(([refId, entry]) => {
+		if (!/^e\d+$/.test(refId) || !isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string") return [];
+		return [[refId, { name: entry.name, role: entry.role }] as const];
+	}));
+	return Object.keys(refs).length > 0 ? refs : undefined;
+}
+
 export function extractRefSnapshotFromData(data: unknown): SessionRefSnapshot | undefined {
 	if (!isRecord(data)) return undefined;
+	const refs = extractRefSnapshotRefs(data);
 	return {
 		refIds: isRecord(data.refs) ? Object.keys(data.refs).filter((refId) => /^e\d+$/.test(refId)) : [],
+		...(refs ? { refs } : {}),
 		target: extractSessionTabTargetFromData(data),
 	};
 }
@@ -295,14 +302,24 @@ function getRestoredRefSnapshotInvalidation(details: Record<string, unknown>, co
 }
 
 function getRestoredRefSnapshot(details: Record<string, unknown>): SessionRefSnapshot | undefined {
-	if (!isRecord(details.refSnapshot) || !Array.isArray(details.refSnapshot.refIds)) return undefined;
-	const refIds = details.refSnapshot.refIds.filter((refId): refId is string => typeof refId === "string" && /^e\d+$/.test(refId));
+	const refSnapshot = isRecord(details.refSnapshot) ? details.refSnapshot : undefined;
+	if (!refSnapshot || !Array.isArray(refSnapshot.refIds)) return undefined;
+	const refIds = refSnapshot.refIds.filter((refId): refId is string => typeof refId === "string" && /^e\d+$/.test(refId));
+	const refRecord = isRecord(refSnapshot.refs) ? refSnapshot.refs : undefined;
+	const refEntries = refRecord
+		? Object.fromEntries(refIds.flatMap((refId) => {
+			const entry = refRecord[refId];
+			if (!isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string") return [];
+			return [[refId, { name: entry.name, role: entry.role }] as const];
+		}))
+		: undefined;
 	return {
 		refIds,
-		target: isRecord(details.refSnapshot.target)
+		...(refEntries && Object.keys(refEntries).length > 0 ? { refs: refEntries } : {}),
+		target: isRecord(refSnapshot.target)
 			? normalizeSessionTabTarget({
-				title: typeof details.refSnapshot.target.title === "string" ? details.refSnapshot.target.title : undefined,
-				url: typeof details.refSnapshot.target.url === "string" ? details.refSnapshot.target.url : undefined,
+				title: typeof refSnapshot.target.title === "string" ? refSnapshot.target.title : undefined,
+				url: typeof refSnapshot.target.url === "string" ? refSnapshot.target.url : undefined,
 			  })
 			: undefined,
 	};
@@ -340,7 +357,7 @@ function shouldApplyRefStateUpdate(options: {
 }
 
 function stripRefSnapshotOrder(snapshot: OrderedSessionRefSnapshot | SessionRefSnapshot | undefined): SessionRefSnapshot | undefined {
-	return snapshot ? { refIds: snapshot.refIds, target: snapshot.target } : undefined;
+	return snapshot ? { refIds: snapshot.refIds, ...(snapshot.refs ? { refs: snapshot.refs } : {}), target: snapshot.target } : undefined;
 }
 
 function stripRefSnapshotInvalidationOrder(invalidation: OrderedSessionRefSnapshotInvalidation | SessionRefSnapshotInvalidation | undefined): SessionRefSnapshotInvalidation | undefined {
@@ -367,7 +384,7 @@ export class SessionPageState {
 			if (!sessionName) continue;
 			const command = typeof details.command === "string" ? details.command : undefined;
 			const subcommand = typeof details.subcommand === "string" ? details.subcommand : undefined;
-			if (command === "close" && message.isError !== true) {
+			if (isCloseCommand(command) && message.isError !== true) {
 				restoredOrder += 1;
 				state.clearSession(sessionName);
 				continue;

package/extensions/agent-browser/lib/temp.ts

@@ -1,6 +1,6 @@
 /**
  * Purpose: Create private temporary and persisted spill files for the pi-agent-browser extension without leaking artifacts broadly on disk.
- * Responsibilities: Maintain a process-private temp root, stamp explicit ownership markers, enforce an aggregate temp-artifact disk budget, create securely permissioned temp files, create session-scoped persisted spill files for resumable sessions, prune explicitly owned stale temp roots from prior runs, and best-effort clean all owned roots on process exit.
+ * Responsibilities: Maintain a process-private temp root, stamp explicit ownership/protected-child markers, enforce an aggregate temp-artifact disk budget, create securely permissioned temp files, create session-scoped persisted spill files for resumable sessions, prune explicitly owned stale temp roots from prior runs without deleting protected children, and best-effort clean all owned roots on process exit.
  * Scope: Artifact lifecycle helpers only; callers decide what data to write and when to delete or retain long-lived references.
  * Usage: Imported by result/process helpers when they need secure spill files instead of world-readable shared tmp paths.
  * Invariants/Assumptions: Temp artifacts live under the OS temp directory, each active run uses a dedicated 0700 directory, files are created with exclusive 0600 permissions, session-scoped persisted artifacts stay under the pi session directory, and stale pruning only touches roots with an explicit pi-agent-browser ownership marker.
@@ -8,10 +8,10 @@
 
 import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { rmSync } from "node:fs";
+import { existsSync, readdirSync, rmSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 
 import { isRecord, parsePositiveInteger } from "./parsing.js";
@@ -53,6 +53,7 @@ interface TempRootOwnershipRecord {
 	ownerPid?: number;
 	ownerProcessStartIdentity?: string;
 	ownerUid?: number;
+	protectedChildNames?: readonly string[];
 	version: number;
 }
 
@@ -69,6 +70,7 @@ let sessionTempRootPromise: Promise<string> | undefined;
 let exitCleanupRegistered = false;
 let tempMutationQueue = Promise.resolve();
 const ownedTempRoots = new Set<string>();
+const protectedTempChildren = new Set<string>();
 
 function getCurrentProcessUid(): number | undefined {
 	return typeof process.getuid === "function" ? process.getuid() : undefined;
@@ -78,6 +80,13 @@ function isPositiveFiniteNumber(value: unknown): value is number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
 
+function isProtectedTempChildName(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	if (value === "" || value === "." || value === ".." || value === TEMP_ROOT_MARKER_FILE_NAME) return false;
+	if (value.includes("/") || value.includes("\\")) return false;
+	return basename(value) === value;
+}
+
 function isTempRootOwnershipRecord(value: unknown): value is TempRootOwnershipRecord {
 	if (!isRecord(value)) return false;
 	if (value.kind !== TEMP_ROOT_MARKER_KIND || value.version !== TEMP_ROOT_MARKER_VERSION) return false;
@@ -92,6 +101,10 @@ function isTempRootOwnershipRecord(value: unknown): value is TempRootOwnershipRe
 	if (value.ownerUid !== undefined) {
 		if (typeof value.ownerUid !== "number" || !Number.isSafeInteger(value.ownerUid) || value.ownerUid < 0) return false;
 	}
+	if (value.protectedChildNames !== undefined) {
+		if (!Array.isArray(value.protectedChildNames)) return false;
+		if (!value.protectedChildNames.every(isProtectedTempChildName)) return false;
+	}
 	return true;
 }
 
@@ -137,6 +150,82 @@ async function readTempRootOwnershipMarker(tempRoot: string): Promise<TempRootOw
 	}
 }
 
+function getProtectedTempChildName(tempRoot: string, childPath: string): string | undefined {
+	const normalizedTempRoot = resolve(tempRoot);
+	const normalizedChildPath = resolve(childPath);
+	if (dirname(normalizedChildPath) !== normalizedTempRoot) return undefined;
+	const childName = basename(normalizedChildPath);
+	return isProtectedTempChildName(childName) ? childName : undefined;
+}
+
+function normalizeProtectedChildNames(names: Iterable<string>): string[] {
+	return [...new Set([...names].filter(isProtectedTempChildName))].sort();
+}
+
+function getPersistedProtectedChildPaths(tempRoot: string, ownershipMarker: TempRootOwnershipRecord | undefined): Set<string> {
+	const normalizedTempRoot = resolve(tempRoot);
+	return new Set((ownershipMarker?.protectedChildNames ?? []).map((childName) => resolve(join(normalizedTempRoot, childName))));
+}
+
+async function writeTempRootOwnershipMarkerRecord(
+	tempRoot: string,
+	markerRecord: TempRootOwnershipRecord,
+	options: { flag?: "wx" } = {},
+): Promise<string> {
+	const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
+	await writeFile(markerPath, JSON.stringify(markerRecord, null, 2), {
+		encoding: "utf8",
+		flag: options.flag,
+		mode: 0o600,
+	});
+	await chmod(markerPath, 0o600).catch(() => undefined);
+	return markerPath;
+}
+
+async function persistProtectedTempChildren(tempRoot: string, protectedChildren: ReadonlySet<string>): Promise<void> {
+	if (protectedChildren.size === 0) return;
+	const ownershipMarker = await readTempRootOwnershipMarker(tempRoot);
+	if (!ownershipMarker) return;
+	const childNames = normalizeProtectedChildNames([
+		...(ownershipMarker.protectedChildNames ?? []),
+		...[...protectedChildren]
+			.map((path) => getProtectedTempChildName(tempRoot, path))
+			.filter((childName): childName is string => childName !== undefined),
+	]);
+	if (childNames.length === 0) return;
+	await writeTempRootOwnershipMarkerRecord(tempRoot, {
+		...ownershipMarker,
+		leaseUpdatedAtMs: Date.now(),
+		protectedChildNames: childNames,
+	});
+}
+
+async function getExistingProtectedChildren(
+	tempRoot: string,
+	protectedChildren: ReadonlySet<string>,
+): Promise<Set<string>> {
+	const normalizedTempRoot = resolve(tempRoot);
+	const existingChildren = new Set<string>();
+	for (const path of protectedChildren) {
+		const normalizedPath = resolve(path);
+		if (dirname(normalizedPath) !== normalizedTempRoot) continue;
+		if (await stat(normalizedPath).then((stats) => stats.isDirectory(), () => false)) {
+			existingChildren.add(normalizedPath);
+		}
+	}
+	return existingChildren;
+}
+
+async function removeTempRootChildrenExcept(tempRoot: string, protectedChildren: ReadonlySet<string>): Promise<void> {
+	const entries = await readdir(tempRoot, { withFileTypes: true }).catch(() => []);
+	await Promise.all(entries.map(async (entry) => {
+		if (entry.name === TEMP_ROOT_MARKER_FILE_NAME) return;
+		const entryPath = join(tempRoot, entry.name);
+		if (protectedChildren.has(resolve(entryPath))) return;
+		await rm(entryPath, { force: true, recursive: true }).catch(() => undefined);
+	}));
+}
+
 async function getProcessStartIdentity(pid: number | undefined): Promise<string | undefined> {
 	if (pid === undefined) return undefined;
 	if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
@@ -155,7 +244,6 @@ export async function writeSecureTempRootOwnershipMarker(
 	tempRoot: string,
 	options: TempRootOwnershipMarkerOptions = {},
 ): Promise<string> {
-	const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
 	const createdAtMs = options.createdAtMs ?? Date.now();
 	const ownerPid = options.ownerPid ?? process.pid;
 	const markerRecord: TempRootOwnershipRecord = {
@@ -167,13 +255,10 @@ export async function writeSecureTempRootOwnershipMarker(
 		ownerUid: getCurrentProcessUid(),
 		version: TEMP_ROOT_MARKER_VERSION,
 	};
-	await writeFile(markerPath, JSON.stringify(markerRecord, null, 2), { encoding: "utf8", flag: "wx", mode: 0o600 });
-	await chmod(markerPath, 0o600).catch(() => undefined);
-	return markerPath;
+	return await writeTempRootOwnershipMarkerRecord(tempRoot, markerRecord, { flag: "wx" });
 }
 
 async function refreshSecureTempRootLease(tempRoot: string): Promise<void> {
-	const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
 	const ownershipMarker = await readTempRootOwnershipMarker(tempRoot);
 	if (!ownershipMarker) return;
 	if (ownershipMarker.ownerPid !== process.pid) return;
@@ -194,8 +279,7 @@ async function refreshSecureTempRootLease(tempRoot: string): Promise<void> {
 		ownerProcessStartIdentity: currentProcessStartIdentity ?? ownershipMarker.ownerProcessStartIdentity,
 		ownerUid: currentUid,
 	};
-	await writeFile(markerPath, JSON.stringify(refreshedMarker, null, 2), { encoding: "utf8", mode: 0o600 });
-	await chmod(markerPath, 0o600).catch(() => undefined);
+	await writeTempRootOwnershipMarkerRecord(tempRoot, refreshedMarker);
 }
 
 async function getMarkerOwnerLiveness(ownershipMarker: TempRootOwnershipRecord): Promise<ProcessLiveness> {
@@ -210,14 +294,10 @@ async function getMarkerOwnerLiveness(ownershipMarker: TempRootOwnershipRecord):
 	}
 
 	const currentProcessStartIdentity = await getProcessStartIdentity(pid);
-	if (
-		ownershipMarker.ownerProcessStartIdentity !== undefined &&
-		currentProcessStartIdentity !== undefined &&
-		ownershipMarker.ownerProcessStartIdentity === currentProcessStartIdentity
-	) {
-		return "alive";
+	if (ownershipMarker.ownerProcessStartIdentity === undefined || currentProcessStartIdentity === undefined) {
+		return "unknown";
 	}
-	return "dead";
+	return ownershipMarker.ownerProcessStartIdentity === currentProcessStartIdentity ? "alive" : "dead";
 }
 
 async function pruneStaleTempRoots(currentTempRoot: string | undefined): Promise<void> {
@@ -243,22 +323,52 @@ async function pruneStaleTempRoots(currentTempRoot: string | undefined): Promise
 				}
 				const staleTimestampMs = ownershipMarker.leaseUpdatedAtMs ?? ownershipMarker.createdAtMs;
 				if (staleTimestampMs >= cutoffTime) return;
-				if ((await getMarkerOwnerLiveness(ownershipMarker)) === "alive") return;
+				// Preserve roots when owner liveness cannot be proven; safe cleanup beats deleting another live process's files.
+				if ((await getMarkerOwnerLiveness(ownershipMarker)) !== "dead") return;
 
 				const stats = await stat(path).catch(() => undefined);
 				if (!stats?.isDirectory()) return;
+				const protectedChildren = await getExistingProtectedChildren(
+					path,
+					getPersistedProtectedChildPaths(path, ownershipMarker),
+				);
+				if (protectedChildren.size > 0) {
+					await removeTempRootChildrenExcept(path, protectedChildren);
+					return;
+				}
 				await rm(path, { force: true, recursive: true }).catch(() => undefined);
 			}),
 	);
 }
 
+function getProtectedChildrenForRoot(tempRoot: string): Set<string> {
+	const normalizedTempRoot = resolve(tempRoot);
+	return new Set(
+		[...protectedTempChildren].filter((path) => dirname(path) === normalizedTempRoot && existsSync(path)),
+	);
+}
+
+function removeTempRootChildrenExceptSync(tempRoot: string, protectedChildren: ReadonlySet<string>): void {
+	for (const entry of readdirSync(tempRoot, { withFileTypes: true })) {
+		if (entry.name === TEMP_ROOT_MARKER_FILE_NAME) continue;
+		const entryPath = join(tempRoot, entry.name);
+		if (protectedChildren.has(resolve(entryPath))) continue;
+		rmSync(entryPath, { force: true, recursive: true });
+	}
+}
+
 function registerExitCleanup(): void {
 	if (exitCleanupRegistered) return;
 	exitCleanupRegistered = true;
 	process.once("exit", () => {
 		for (const tempRoot of ownedTempRoots) {
 			try {
-				rmSync(tempRoot, { force: true, recursive: true });
+				const protectedChildren = getProtectedChildrenForRoot(tempRoot);
+				if (protectedChildren.size === 0) {
+					rmSync(tempRoot, { force: true, recursive: true });
+				} else {
+					removeTempRootChildrenExceptSync(tempRoot, protectedChildren);
+				}
 			} catch {
 				// Best-effort cleanup only.
 			}
@@ -284,13 +394,28 @@ async function assertSecureTempRootBudget(tempRoot: string, additionalBytes: num
 	}
 }
 
-export async function cleanupSecureTempArtifacts(): Promise<void> {
+export async function cleanupSecureTempArtifacts(options: { preservePaths?: readonly string[] } = {}): Promise<void> {
 	await enqueueTempMutation(async () => {
 		const tempRoot = await sessionTempRootPromise?.catch(() => undefined);
-		sessionTempRootPromise = undefined;
 		if (!tempRoot) return;
-		ownedTempRoots.delete(tempRoot);
-		await rm(tempRoot, { force: true, recursive: true }).catch(() => undefined);
+		const normalizedTempRoot = resolve(tempRoot);
+		for (const path of options.preservePaths ?? []) {
+			const childName = getProtectedTempChildName(normalizedTempRoot, path);
+			if (childName) protectedTempChildren.add(resolve(join(normalizedTempRoot, childName)));
+		}
+		const preservedChildren = await getExistingProtectedChildren(normalizedTempRoot, protectedTempChildren);
+		for (const path of protectedTempChildren) {
+			if (dirname(path) === normalizedTempRoot && !preservedChildren.has(path)) protectedTempChildren.delete(path);
+		}
+		if (preservedChildren.size === 0) {
+			sessionTempRootPromise = undefined;
+			ownedTempRoots.delete(tempRoot);
+			await rm(tempRoot, { force: true, recursive: true }).catch(() => undefined);
+			return;
+		}
+		await persistProtectedTempChildren(tempRoot, preservedChildren);
+		await removeTempRootChildrenExcept(tempRoot, preservedChildren);
+		await refreshSecureTempRootLease(tempRoot).catch(() => undefined);
 	});
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -56,9 +56,9 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.75.4",
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@earendil-works/pi-tui": "^0.75.4",
+    "@earendil-works/pi-ai": "^0.76.0",
+    "@earendil-works/pi-coding-agent": "^0.76.0",
+    "@earendil-works/pi-tui": "^0.76.0",
     "@types/node": "^25.6.1",
     "tsx": "^4.21.0",
     "typebox": "^1.1.38",