pi-agent-browser-native 0.2.1 → 0.2.3

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

@@ -1,15 +1,17 @@
 /**
- * Purpose: Build safe, deterministic agent-browser invocations for the pi-agent-browser extension.
- * Responsibilities: Validate raw tool arguments, derive extension-managed session names from the pi session identity, resolve managed-session timeout/state helpers, detect explicit session usage, and build the effective CLI argument list passed to the upstream agent-browser binary.
+ * Purpose: Build safe, deterministic agent-browser invocations and persisted session state for the pi-agent-browser extension.
+ * Responsibilities: Validate raw tool arguments, derive extension-managed session names from the pi session identity, restore managed-session state from persisted tool details, redact sensitive invocation text, classify browser-oriented prompts, and build the effective CLI argument list passed to the upstream agent-browser binary.
  * Scope: Pure runtime-planning helpers only; no subprocess execution or filesystem access lives here.
  * Usage: Imported by the extension entrypoint and unit tests before spawning the upstream CLI.
- * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, and only injects `--json` plus an extension-managed `--session` when appropriate.
+ * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, keeps plain-text inspection stateless, and only injects `--json` plus an extension-managed `--session` when appropriate.
  */
 
 import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 
 const STARTUP_SCOPED_FLAGS = ["--cdp", "--profile", "--session-name"] as const;
+const OPEN_COMMANDS = new Set(["goto", "navigate", "open"]);
+const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.openai.com", "chatgpt.com"]);
 const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
 const IMPLICIT_SESSION_IDLE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_IDLE_TIMEOUT_MS";
@@ -23,6 +25,17 @@ const LEGACY_BASH_ALLOW_PATTERNS = [
 	/\bagent-browser\s+--(?:help|version)\b/i,
 	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
 ];
+const BROWSER_PROMPT_PATTERNS = [
+	/\b(?:agent[_ -]?browser|browser automation|eval\s+--stdin|screenshot|snapshot|tab\s+list)\b/i,
+	/\bbrowser\b.*\b(?:automation|click|fill|navigate|open|page|screenshot|site|snapshot|tab|url|visit|web(?:site| page)?)\b/i,
+	/\b(?:browse|click|fill|login|navigate|open|visit)\b.*\b(?:https?:\/\/\S+|page|site|tab|url|web(?:site| page)?)\b/i,
+];
+const INSPECTION_FLAGS = new Set(["--help", "-h", "--version", "-V"]);
+const SENSITIVE_VALUE_FLAGS = new Set(["--headers", "--proxy"]);
+const SENSITIVE_QUERY_PARAM_PATTERN =
+	/^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|secret|session(?:_|-)?id|sig(?:nature)?|token)$/i;
+const SENSITIVE_FIELD_NAME_PATTERN =
+	/^(?:access(?:_|-)?token|api(?:_|-)?key|auth(?:orization)?|bearer|client(?:_|-)?secret|cookie|id(?:_|-)?token|pass(?:word)?|proxy(?:_|-)?authorization|refresh(?:_|-)?token|secret|session(?:_|-)?id|set(?:_|-)?cookie|sig(?:nature)?|token|x(?:_|-)?api(?:_|-)?key)$/i;
 
 const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--session",
@@ -46,7 +59,21 @@ const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--color-scheme",
 	"--device",
 	"--port",
+	"--args",
+	"--user-agent",
+	"--allowed-domains",
+	"--action-policy",
+	"--confirm-actions",
+	"--max-output",
+	"--model",
 ]);
+const DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM: Partial<Record<NodeJS.Platform, string>> = {
+	darwin: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+	linux: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+	win32: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+};
+const FALLBACK_HEADLESS_COMPAT_USER_AGENT =
+	"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
 const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
 const MAX_PROJECT_SLUG_LENGTH = 24;
 const SESSION_NAME_CWD_HASH_LENGTH = 8;
@@ -73,11 +100,24 @@ export interface InvalidValueFlagDetails {
 	receivedToken?: string;
 }
 
+export interface CompatibilityWorkaround {
+	id: "chatgpt-headless-user-agent";
+	reason: string;
+}
+
+export interface OpenResultTabCorrection {
+	selectedIndex: number;
+	targetTitle?: string;
+	targetUrl: string;
+}
+
 export interface ExecutionPlan {
 	commandInfo: CommandInfo;
+	compatibilityWorkaround?: CompatibilityWorkaround;
 	effectiveArgs: string[];
 	invalidValueFlag?: InvalidValueFlagDetails;
 	managedSessionName?: string;
+	plainTextInspection: boolean;
 	recoveryHint?: SessionRecoveryHint;
 	sessionName?: string;
 	startupScopedFlags: string[];
@@ -91,10 +131,146 @@ export interface ManagedSessionState {
 	sessionName: string;
 }
 
+export interface RestoredManagedSessionState extends ManagedSessionState {
+	freshSessionOrdinal: number;
+}
+
 export interface PromptPolicy {
 	allowLegacyAgentBrowserBash: boolean;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function shouldRedactQueryParam(name: string): boolean {
+	return SENSITIVE_QUERY_PARAM_PATTERN.test(name);
+}
+
+function redactUrlToken(token: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(token);
+	} catch {
+		return token;
+	}
+
+	if (!["http:", "https:", "ws:", "wss:"].includes(parsed.protocol)) {
+		return token;
+	}
+
+	if (parsed.username.length > 0) {
+		parsed.username = "[REDACTED]";
+	}
+	if (parsed.password.length > 0) {
+		parsed.password = "[REDACTED]";
+	}
+
+	for (const [name] of parsed.searchParams) {
+		if (shouldRedactQueryParam(name)) {
+			parsed.searchParams.set(name, "[REDACTED]");
+		}
+	}
+
+	const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
+	if (hashText.includes("=")) {
+		const hashParams = new URLSearchParams(hashText);
+		let mutated = false;
+		for (const [name] of hashParams) {
+			if (shouldRedactQueryParam(name)) {
+				hashParams.set(name, "[REDACTED]");
+				mutated = true;
+			}
+		}
+		if (mutated) {
+			parsed.hash = `#${hashParams.toString()}`;
+		}
+	}
+
+	return parsed.toString();
+}
+
+function redactLooseUrlMatches(text: string): string {
+	return text.replace(/\b(?:https?|wss?):\/\/[^\s"'`<>\])]+/g, (match) => redactUrlToken(match));
+}
+
+export function redactSensitiveText(text: string): string {
+	return redactLooseUrlMatches(text)
+		.replace(/\b(Bearer)\s+[^\s",]+/gi, "$1 [REDACTED]")
+		.replace(/\b(Basic)\s+[^\s",]+/gi, "$1 [REDACTED]");
+}
+
+export function redactSensitiveValue(value: unknown): unknown {
+	if (typeof value === "string") {
+		return redactSensitiveText(value);
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => redactSensitiveValue(item));
+	}
+	if (!isRecord(value)) {
+		return value;
+	}
+	return Object.fromEntries(
+		Object.entries(value).map(([key, entryValue]) => {
+			if (SENSITIVE_FIELD_NAME_PATTERN.test(key)) {
+				return [key, "[REDACTED]"];
+			}
+			return [key, redactSensitiveValue(entryValue)];
+		}),
+	);
+}
+
+function redactFlagValue(flag: string, value: string): string {
+	if (SENSITIVE_VALUE_FLAGS.has(flag)) {
+		return "[REDACTED]";
+	}
+	return redactUrlToken(value);
+}
+
+export function redactInvocationArgs(args: string[]): string[] {
+	const redacted: string[] = [];
+	let pendingValueFlag: string | undefined;
+
+	for (const token of args) {
+		if (pendingValueFlag) {
+			redacted.push(redactFlagValue(pendingValueFlag, token));
+			pendingValueFlag = undefined;
+			continue;
+		}
+
+		const normalizedToken = token.split("=", 1)[0] ?? token;
+		if (SENSITIVE_VALUE_FLAGS.has(normalizedToken)) {
+			if (token.includes("=")) {
+				redacted.push(`${normalizedToken}=[REDACTED]`);
+			} else {
+				redacted.push(token);
+				pendingValueFlag = normalizedToken;
+			}
+			continue;
+		}
+
+		redacted.push(redactUrlToken(token));
+	}
+
+	return redacted;
+}
+
+export function shouldAppendBrowserSystemPrompt(prompt: string): boolean {
+	const normalizedPrompt = prompt.trim();
+	if (normalizedPrompt.length === 0) {
+		return false;
+	}
+	return BROWSER_PROMPT_PATTERNS.some((pattern) => pattern.test(normalizedPrompt));
+}
+
+export function isPlainTextInspectionArgs(args: string[]): boolean {
+	return args.some((token) => INSPECTION_FLAGS.has(token));
+}
+
 export function hasUsableBraveApiKey(apiKey: string | null | undefined = process.env[BRAVE_API_KEY_ENV]): boolean {
 	return typeof apiKey === "string" && apiKey.trim().length > 0;
 }
@@ -146,6 +322,74 @@ export function resolveManagedSessionState(options: {
 	};
 }
 
+function isRestorableManagedSessionName(sessionName: string, fallbackSessionName: string): boolean {
+	return sessionName === fallbackSessionName || sessionName.startsWith(`${fallbackSessionName}-fresh-`);
+}
+
+export function restoreManagedSessionStateFromBranch(
+	branch: unknown[],
+	fallbackSessionName: string,
+): RestoredManagedSessionState {
+	let restoredState: ManagedSessionState = {
+		active: false,
+		sessionName: fallbackSessionName,
+	};
+	let freshSessionOrdinal = 0;
+
+	for (const entry of branch) {
+		if (!isRecord(entry) || entry.type !== "message") {
+			continue;
+		}
+		const message = isRecord(entry.message) ? entry.message : undefined;
+		if (!message || message.toolName !== "agent_browser") {
+			continue;
+		}
+		const details = isRecord(message.details) ? message.details : undefined;
+		if (!details) {
+			continue;
+		}
+		const args = isStringArray(details.args) ? details.args : [];
+		if (isPlainTextInspectionArgs(args)) {
+			continue;
+		}
+
+		const explicitSessionName = extractExplicitSessionName(args);
+		const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+		const sessionMode = details.sessionMode === "fresh" || details.sessionMode === "auto" ? details.sessionMode : undefined;
+		const usedImplicitSession = details.usedImplicitSession === true;
+		const managedSessionName =
+			!explicitSessionName &&
+			sessionName &&
+			isRestorableManagedSessionName(sessionName, fallbackSessionName) &&
+			(usedImplicitSession || sessionMode === "fresh")
+				? sessionName
+				: undefined;
+		if (!managedSessionName) {
+			continue;
+		}
+
+		const messageIsError = typeof message.isError === "boolean" ? message.isError : undefined;
+		const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
+		const succeeded = messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
+		const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
+		restoredState = resolveManagedSessionState({
+			command,
+			managedSessionName,
+			priorActive: restoredState.active,
+			priorSessionName: restoredState.sessionName,
+			succeeded,
+		});
+		if (succeeded && sessionMode === "fresh") {
+			freshSessionOrdinal += 1;
+		}
+	}
+
+	return {
+		...restoredState,
+		freshSessionOrdinal,
+	};
+}
+
 export function createEphemeralSessionSeed(): string {
 	return randomUUID();
 }
@@ -251,6 +495,96 @@ function hasFlagToken(args: string[], flag: string): boolean {
 	return args.some((token) => token === flag || token.startsWith(`${flag}=`));
 }
 
+function getFlagValue(args: string[], flag: string): string | undefined {
+	for (const [index, token] of args.entries()) {
+		if (token === flag) {
+			return args[index + 1];
+		}
+		if (token.startsWith(`${flag}=`)) {
+			return token.slice(flag.length + 1);
+		}
+	}
+	return undefined;
+}
+
+function isBooleanFlagEnabled(args: string[], flag: string): boolean {
+	for (const [index, token] of args.entries()) {
+		if (token === flag) {
+			const nextToken = args[index + 1]?.trim().toLowerCase();
+			if (nextToken === "false") {
+				return false;
+			}
+			return true;
+		}
+		if (token.startsWith(`${flag}=`)) {
+			return token.slice(flag.length + 1).trim().toLowerCase() !== "false";
+		}
+	}
+	return false;
+}
+
+function normalizeComparableUrl(url: string): string | undefined {
+	const normalizedUrl = url.trim();
+	if (normalizedUrl.length === 0) {
+		return undefined;
+	}
+	try {
+		const parsedUrl = new URL(normalizedUrl);
+		parsedUrl.hash = "";
+		return parsedUrl.toString();
+	} catch {
+		return undefined;
+	}
+}
+
+function parseComparableNavigationUrl(url: string): URL | undefined {
+	try {
+		return new URL(url);
+	} catch {
+		try {
+			return new URL(`https://${url}`);
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+function getDefaultHeadlessCompatUserAgent(platform: NodeJS.Platform = process.platform): string {
+	return DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM[platform] ?? FALLBACK_HEADLESS_COMPAT_USER_AGENT;
+}
+
+function getCompatibilityWorkaround(args: string[], commandInfo: CommandInfo): CompatibilityWorkaround | undefined {
+	if (!commandInfo.command || !OPEN_COMMANDS.has(commandInfo.command) || !commandInfo.subcommand) {
+		return undefined;
+	}
+	if (hasFlagToken(args, "--user-agent")) {
+		return undefined;
+	}
+	if (isBooleanFlagEnabled(args, "--headed")) {
+		return undefined;
+	}
+	if (hasFlagToken(args, "--cdp") || hasFlagToken(args, "--provider") || hasFlagToken(args, "-p") || hasFlagToken(args, "--auto-connect")) {
+		return undefined;
+	}
+	const engine = getFlagValue(args, "--engine");
+	if (engine && engine !== "chrome") {
+		return undefined;
+	}
+	const parsedTargetUrl = parseComparableNavigationUrl(commandInfo.subcommand);
+	if (!parsedTargetUrl || !["http:", "https:"].includes(parsedTargetUrl.protocol)) {
+		return undefined;
+	}
+	const hostname = parsedTargetUrl.hostname.toLowerCase();
+	if (!OPENAI_HEADLESS_COMPAT_HOSTS.has(hostname)) {
+		return undefined;
+	}
+	return {
+		id: "chatgpt-headless-user-agent",
+		reason:
+			"OpenAI web properties currently challenge the default headless Chrome user agent; inject a normal Chrome user agent to preserve the default headless workflow without requiring headed mode or auto-connect.",
+	};
+}
+
 export function extractExplicitSessionName(args: string[]): string | undefined {
 	for (const [index, token] of args.entries()) {
 		if (token === "--session") {
@@ -310,24 +644,37 @@ export function buildExecutionPlan(
 		sessionMode: SessionMode;
 	},
 ): ExecutionPlan {
-	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
 	const invalidValueFlag = getInvalidValueFlagDetails(args);
+	const startupScopedFlags = getStartupScopedFlags(args);
+	const plainTextInspection = isPlainTextInspectionArgs(args);
+	const commandInfo = parseCommandInfo(args);
+	const effectiveArgs = plainTextInspection ? [...args] : args.includes("--json") ? [] : ["--json"];
 	if (invalidValueFlag) {
 		return {
 			commandInfo: {},
 			effectiveArgs,
 			invalidValueFlag,
+			plainTextInspection: false,
 			startupScopedFlags: [],
 			usedImplicitSession: false,
 			validationError: formatInvalidValueFlagError(invalidValueFlag),
 		};
 	}
 
-	const commandInfo = parseCommandInfo(args);
+	if (plainTextInspection) {
+		return {
+			commandInfo,
+			effectiveArgs,
+			plainTextInspection,
+			startupScopedFlags,
+			usedImplicitSession: false,
+		};
+	}
+
 	const explicitSessionName = extractExplicitSessionName(args);
-	const startupScopedFlags = getStartupScopedFlags(args);
 	const shouldCreateFreshManagedSession =
 		!explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && commandInfo.command !== "close";
+	const compatibilityWorkaround = getCompatibilityWorkaround(args, commandInfo);
 	let managedSessionName: string | undefined;
 	let recoveryHint: SessionRecoveryHint | undefined;
 	let sessionName = explicitSessionName;
@@ -359,12 +706,17 @@ export function buildExecutionPlan(
 		sessionName = options.freshSessionName;
 	}
 
+	if (compatibilityWorkaround) {
+		effectiveArgs.push("--user-agent", getDefaultHeadlessCompatUserAgent());
+	}
 	effectiveArgs.push(...args);
 
 	return {
 		commandInfo,
+		compatibilityWorkaround,
 		effectiveArgs,
 		managedSessionName,
+		plainTextInspection,
 		recoveryHint,
 		sessionName,
 		startupScopedFlags,
@@ -373,6 +725,48 @@ export function buildExecutionPlan(
 	};
 }
 
+export function chooseOpenResultTabCorrection(options: {
+	activeTabIndex?: number;
+	tabs: Array<{ active?: boolean; index?: number; title?: string; url?: string }>;
+	targetTitle?: string;
+	targetUrl?: string;
+}): OpenResultTabCorrection | undefined {
+	const normalizedTargetUrl =
+		typeof options.targetUrl === "string" ? normalizeComparableUrl(options.targetUrl) : undefined;
+	if (!normalizedTargetUrl) {
+		return undefined;
+	}
+
+	const tabsWithIndices = options.tabs.map((tab, index) => ({
+		...tab,
+		index: typeof tab.index === "number" ? tab.index : index,
+	}));
+	const activeTab =
+		tabsWithIndices.find((tab) => tab.active === true) ??
+		(typeof options.activeTabIndex === "number" ? tabsWithIndices.find((tab) => tab.index === options.activeTabIndex) : undefined);
+	if (activeTab && normalizeComparableUrl(activeTab.url ?? "") === normalizedTargetUrl) {
+		return undefined;
+	}
+
+	const matchingTabs = tabsWithIndices.filter((tab) => normalizeComparableUrl(tab.url ?? "") === normalizedTargetUrl);
+	if (matchingTabs.length === 0) {
+		return undefined;
+	}
+	const trimmedTargetTitle = typeof options.targetTitle === "string" ? options.targetTitle.trim() : "";
+	const titledMatch =
+		trimmedTargetTitle.length === 0
+			? undefined
+			: matchingTabs.find((tab) => typeof tab.title === "string" && tab.title.trim() === trimmedTargetTitle);
+	const selectedTab = titledMatch ?? matchingTabs[0];
+	return selectedTab.index === undefined
+		? undefined
+		: {
+			selectedIndex: selectedTab.index,
+			targetTitle: trimmedTargetTitle.length > 0 ? trimmedTargetTitle : undefined,
+			targetUrl: normalizedTargetUrl,
+		};
+}
+
 export function parseCommandInfo(args: string[]): CommandInfo {
 	const commands: string[] = [];
 
@@ -396,4 +790,3 @@ export function parseCommandInfo(args: string[]): CommandInfo {
 
 	return { command: commands[0], subcommand: commands[1] };
 }
-

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

@@ -1,14 +1,14 @@
 /**
- * Purpose: Create private temporary 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, prune explicitly owned stale temp roots from prior runs, and best-effort clean all owned roots on process exit.
- * Scope: Temporary artifact lifecycle only; callers decide what data to write and when to delete long-lived references.
+ * 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.
+ * 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, and stale pruning only touches roots with an explicit pi-agent-browser ownership marker.
+ * 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.
  */
 
 import { randomBytes } from "node:crypto";
 import { rmSync } from "node:fs";
-import { chmod, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+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";
 
@@ -19,6 +19,15 @@ const TEMP_ROOT_MARKER_VERSION = 1;
 const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const TEMP_ROOT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_TEMP_ROOT_MAX_BYTES";
 const DEFAULT_TEMP_ROOT_MAX_BYTES = 32 * 1_024 * 1_024;
+const SESSION_ARTIFACT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES";
+const DEFAULT_SESSION_ARTIFACT_MAX_BYTES = 32 * 1_024 * 1_024;
+const SESSION_ARTIFACTS_ROOT_DIR_NAME = ".pi-agent-browser-artifacts";
+
+export interface PersistentSessionArtifactStore {
+	protectedPaths?: readonly string[];
+	sessionDir: string;
+	sessionId: string;
+}
 
 interface TempRootOwnershipRecord {
 	createdAtMs: number;
@@ -69,18 +78,23 @@ function enqueueTempMutation<T>(task: () => Promise<T>): Promise<T> {
 	return nextTask;
 }
 
-async function getTempRootArtifactBytes(tempRoot: string): Promise<number> {
-	const entries = await readdir(tempRoot, { withFileTypes: true }).catch(() => []);
-	let totalBytes = 0;
+async function listArtifactFiles(directory: string, excludedNames: ReadonlySet<string> = new Set()): Promise<Array<{ mtimeMs: number; path: string; size: number }>> {
+	const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+	const files: Array<{ mtimeMs: number; path: string; size: number }> = [];
 	for (const entry of entries) {
-		if (!entry.isFile() || entry.name === TEMP_ROOT_MARKER_FILE_NAME) continue;
-		const path = join(tempRoot, entry.name);
+		if (!entry.isFile() || excludedNames.has(entry.name)) continue;
+		const path = join(directory, entry.name);
 		const stats = await stat(path).catch(() => undefined);
 		if (stats?.isFile()) {
-			totalBytes += stats.size;
+			files.push({ mtimeMs: stats.mtimeMs, path, size: stats.size });
 		}
 	}
-	return totalBytes;
+	return files;
+}
+
+async function getTempRootArtifactBytes(tempRoot: string): Promise<number> {
+	const files = await listArtifactFiles(tempRoot, new Set([TEMP_ROOT_MARKER_FILE_NAME]));
+	return files.reduce((totalBytes, file) => totalBytes + file.size, 0);
 }
 
 async function readTempRootOwnershipMarker(tempRoot: string): Promise<TempRootOwnershipRecord | undefined> {
@@ -153,6 +167,10 @@ export function getSecureTempRootMaxBytes(env: NodeJS.ProcessEnv = process.env):
 	return parsePositiveInteger(env[TEMP_ROOT_MAX_BYTES_ENV]) ?? DEFAULT_TEMP_ROOT_MAX_BYTES;
 }
 
+export function getPersistentSessionArtifactMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+	return parsePositiveInteger(env[SESSION_ARTIFACT_MAX_BYTES_ENV]) ?? DEFAULT_SESSION_ARTIFACT_MAX_BYTES;
+}
+
 async function assertSecureTempRootBudget(tempRoot: string, additionalBytes: number): Promise<void> {
 	if (additionalBytes <= 0) return;
 	const currentBytes = await getTempRootArtifactBytes(tempRoot);
@@ -173,6 +191,42 @@ export async function cleanupSecureTempArtifacts(): Promise<void> {
 	});
 }
 
+async function ensurePersistentSessionArtifactDir(store: PersistentSessionArtifactStore): Promise<string> {
+	const rootDir = join(store.sessionDir, SESSION_ARTIFACTS_ROOT_DIR_NAME);
+	const sessionDir = join(rootDir, store.sessionId);
+	await mkdir(rootDir, { recursive: true, mode: 0o700 });
+	await chmod(rootDir, 0o700).catch(() => undefined);
+	await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+	await chmod(sessionDir, 0o700).catch(() => undefined);
+	return sessionDir;
+}
+
+async function prunePersistentSessionArtifactsToBudget(
+	sessionArtifactDir: string,
+	additionalBytes: number,
+	protectedPaths: ReadonlySet<string>,
+): Promise<void> {
+	if (additionalBytes <= 0) return;
+	const maxBytes = getPersistentSessionArtifactMaxBytes();
+	let files = await listArtifactFiles(sessionArtifactDir);
+	let totalBytes = files.reduce((total, file) => total + file.size, 0);
+	if (totalBytes + additionalBytes <= maxBytes) {
+		return;
+	}
+	files = files.sort((left, right) => left.mtimeMs - right.mtimeMs || left.path.localeCompare(right.path));
+	for (const file of files) {
+		if (protectedPaths.has(file.path)) {
+			continue;
+		}
+		await rm(file.path, { force: true }).catch(() => undefined);
+		totalBytes -= file.size;
+		if (totalBytes + additionalBytes <= maxBytes) {
+			return;
+		}
+	}
+	throw new Error(`pi-agent-browser persisted spill budget exceeded (${totalBytes + additionalBytes} bytes > ${maxBytes} byte limit).`);
+}
+
 async function getSessionTempRoot(): Promise<string> {
 	if (!sessionTempRootPromise) {
 		sessionTempRootPromise = (async () => {
@@ -228,6 +282,34 @@ export async function writeSecureTempFile(options: {
 	return path;
 }
 
+export async function writePersistentSessionArtifactFile(options: {
+	content: string | Uint8Array;
+	prefix: string;
+	store: PersistentSessionArtifactStore;
+	suffix: string;
+}): Promise<string> {
+	const { content, prefix, store, suffix } = options;
+	return await enqueueTempMutation(async () => {
+		const artifactDir = await ensurePersistentSessionArtifactDir(store);
+		await prunePersistentSessionArtifactsToBudget(
+			artifactDir,
+			getTempArtifactByteLength(content),
+			new Set((store.protectedPaths ?? []).filter((path) => dirname(path) === artifactDir)),
+		);
+		const path = join(artifactDir, `${prefix}-${randomBytes(8).toString("hex")}${suffix}`);
+		const fileHandle = await open(path, "wx", 0o600);
+		try {
+			await fileHandle.writeFile(content);
+		} catch (error) {
+			await rm(path, { force: true }).catch(() => undefined);
+			throw error;
+		} finally {
+			await fileHandle.close().catch(() => undefined);
+		}
+		return path;
+	});
+}
+
 export async function getSecureTempDebugState(): Promise<{ currentTempRoot?: string; ownedTempRoots: string[] }> {
 	return {
 		currentTempRoot: await sessionTempRootPromise?.catch(() => undefined),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",