pi-agent-browser-native 0.2.2 → 0.2.4

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

@@ -7,7 +7,8 @@
  */
 
 import { spawn } from "node:child_process";
-import { env as processEnv } from "node:process";
+import { chmod, mkdir } from "node:fs/promises";
+import { env as processEnv, platform as processPlatform } from "node:process";
 
 import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
 
@@ -15,6 +16,8 @@ const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
 const MAX_BUFFERED_STDERR_CHARS = 32_000;
 const MAX_BUFFERED_STDOUT_TAIL_CHARS = 32_000;
 const PROCESS_STDOUT_SPILL_FILE_PREFIX = "process-stdout";
+const AGENT_BROWSER_SOCKET_DIR_ENV = "AGENT_BROWSER_SOCKET_DIR";
+const DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX = "/tmp/piab";
 const httpProxyEnvName = "http_proxy";
 const httpsProxyEnvName = "https_proxy";
 const allProxyEnvName = "all_proxy";
@@ -81,6 +84,26 @@ function appendTail(text: string, addition: string, maxChars: number): string {
 	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
 
+export function getAgentBrowserSocketDir(
+	platform: NodeJS.Platform = processPlatform,
+	uid: number | undefined = typeof process.getuid === "function" ? process.getuid() : undefined,
+): string | undefined {
+	if (platform === "win32") {
+		return undefined;
+	}
+	return `${DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX}${typeof uid === "number" ? `-${uid}` : ""}`;
+}
+
+async function ensureAgentBrowserSocketDir(socketDir: string): Promise<boolean> {
+	try {
+		await mkdir(socketDir, { recursive: true, mode: 0o700 });
+		await chmod(socketDir, 0o700).catch(() => undefined);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 export function buildAgentBrowserProcessEnv(
 	baseEnv: NodeJS.ProcessEnv = processEnv,
 	overrides: NodeJS.ProcessEnv | undefined = undefined,
@@ -117,6 +140,11 @@ export async function runAgentBrowserProcess(options: {
 	stdin?: string;
 }): Promise<ProcessRunResult> {
 	const { args, cwd, env, signal, stdin } = options;
+	let effectiveEnv = env;
+	const requestedSocketDir = env?.[AGENT_BROWSER_SOCKET_DIR_ENV] ?? getAgentBrowserSocketDir();
+	if (requestedSocketDir && (await ensureAgentBrowserSocketDir(requestedSocketDir))) {
+		effectiveEnv = { ...env, [AGENT_BROWSER_SOCKET_DIR_ENV]: requestedSocketDir };
+	}
 
 	return await new Promise<ProcessRunResult>((resolve) => {
 		let aborted = false;
@@ -191,7 +219,7 @@ export async function runAgentBrowserProcess(options: {
 
 		const child = spawn("agent-browser", args, {
 			cwd,
-			env: buildAgentBrowserProcessEnv(processEnv, env),
+			env: buildAgentBrowserProcessEnv(processEnv, effectiveEnv),
 			stdio: ["pipe", "pipe", "pipe"],
 		});
 

package/extensions/agent-browser/lib/results/presentation.ts

@@ -10,6 +10,7 @@ import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import { parseCommandInfo, type CommandInfo } from "../runtime.js";
+import { type PersistentSessionArtifactStore } from "../temp.js";
 import { buildSnapshotPresentation, formatRawSnapshotText, formatSnapshotSummary } from "./snapshot.js";
 import {
 	type AgentBrowserBatchResult,
@@ -106,6 +107,63 @@ function getScreenshotSummary(data: Record<string, unknown>): string | undefined
 	return typeof data.path === "string" ? `Saved image: ${data.path}` : undefined;
 }
 
+function getScalarExtractionResult(data: Record<string, unknown>): string | undefined {
+	const { result } = data;
+	if (typeof result === "string") {
+		return result.trim().length > 0 ? result : undefined;
+	}
+	if (typeof result === "number" || typeof result === "boolean") {
+		return String(result);
+	}
+	return undefined;
+}
+
+function getExtractionOrigin(data: Record<string, unknown>): string | undefined {
+	if (typeof data.origin === "string" && data.origin.trim().length > 0) {
+		return data.origin.trim();
+	}
+	if (typeof data.url === "string" && data.url.trim().length > 0) {
+		return data.url.trim();
+	}
+	return undefined;
+}
+
+function formatGetSummaryLabel(subcommand: string | undefined): string {
+	if (!subcommand) {
+		return "Get result";
+	}
+	if (subcommand.toLowerCase() === "url") {
+		return "URL";
+	}
+	return `${subcommand.slice(0, 1).toUpperCase()}${subcommand.slice(1)}`;
+}
+
+function formatExtractionSummary(commandInfo: CommandInfo, data: Record<string, unknown>): string | undefined {
+	const scalarResult = getScalarExtractionResult(data);
+	if (!scalarResult) {
+		return undefined;
+	}
+	if (commandInfo.command === "get") {
+		return `${formatGetSummaryLabel(commandInfo.subcommand)}: ${scalarResult.split("\n", 1)[0] ?? scalarResult}`;
+	}
+	if (commandInfo.command === "eval") {
+		return `Eval result: ${scalarResult.split("\n", 1)[0] ?? scalarResult}`;
+	}
+	return undefined;
+}
+
+function formatExtractionText(commandInfo: CommandInfo, data: Record<string, unknown>): string | undefined {
+	if (commandInfo.command !== "get" && commandInfo.command !== "eval") {
+		return undefined;
+	}
+	const scalarResult = getScalarExtractionResult(data);
+	if (!scalarResult) {
+		return undefined;
+	}
+	const origin = getExtractionOrigin(data);
+	return origin && origin !== scalarResult ? `${scalarResult}\n\nOrigin: ${origin}` : scalarResult;
+}
+
 function isNavigationObservableCommand(command: string | undefined): boolean {
 	return command !== undefined && NAVIGATION_SUMMARY_COMMANDS.has(command);
 }
@@ -207,8 +265,9 @@ async function buildBatchStepPresentation(options: {
 	cwd: string;
 	index: number;
 	item: AgentBrowserBatchResult;
+	persistentArtifactStore?: PersistentSessionArtifactStore;
 }): Promise<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> {
-	const { cwd, index, item } = options;
+	const { cwd, index, item, persistentArtifactStore } = options;
 	const command = isStringArray(item.command) ? item.command : undefined;
 	const commandText = formatBatchStepCommand(command, index);
 
@@ -236,6 +295,7 @@ async function buildBatchStepPresentation(options: {
 		commandInfo: parseCommandInfo(command ?? []),
 		cwd,
 		envelope: { data: item.result, success: true },
+		persistentArtifactStore,
 	});
 	const fullOutputPaths = getPresentationPaths({
 		primaryPath: presentation.fullOutputPath,
@@ -268,12 +328,28 @@ async function buildBatchStepPresentation(options: {
 async function buildBatchPresentation(options: {
 	cwd: string;
 	data: AgentBrowserBatchResult[];
+	persistentArtifactStore?: PersistentSessionArtifactStore;
 	summary: string;
 }): Promise<ToolPresentation> {
-	const { cwd, data, summary } = options;
+	const { cwd, data, persistentArtifactStore, summary } = options;
 	const steps: Array<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> = [];
+	const protectedPersistentPaths: string[] = [];
 	for (const [index, item] of data.entries()) {
-		steps.push(await buildBatchStepPresentation({ cwd, index, item }));
+		const step = await buildBatchStepPresentation({
+			cwd,
+			index,
+			item,
+			persistentArtifactStore: persistentArtifactStore
+				? { ...persistentArtifactStore, protectedPaths: protectedPersistentPaths }
+				: undefined,
+		});
+		steps.push(step);
+		protectedPersistentPaths.push(
+			...getPresentationPaths({
+				primaryPath: step.presentation.fullOutputPath,
+				secondaryPaths: step.presentation.fullOutputPaths,
+			}),
+		);
 	}
 
 	const batchFailure = getBatchFailureDetails(steps);
@@ -354,6 +430,10 @@ function formatSummary(commandInfo: CommandInfo, data: unknown): string {
 		if (commandInfo.command === "screenshot" && typeof data.path === "string") {
 			return `Screenshot saved: ${data.path}`;
 		}
+		const extractionSummary = formatExtractionSummary(commandInfo, data);
+		if (extractionSummary) {
+			return extractionSummary;
+		}
 		const pageSummary = getPageSummary(data);
 		if (pageSummary) {
 			return pageSummary.split("\n", 1)[0] ?? "agent-browser result";
@@ -404,6 +484,11 @@ function formatContentText(commandInfo: CommandInfo, data: unknown): string {
 		if (screenshotSummary) return screenshotSummary;
 	}
 
+	const extractionText = formatExtractionText(commandInfo, data);
+	if (extractionText) {
+		return extractionText;
+	}
+
 	const pageSummary = getPageSummary(data);
 	if (pageSummary) {
 		return pageSummary;
@@ -459,8 +544,9 @@ export async function buildToolPresentation(options: {
 	cwd: string;
 	envelope?: AgentBrowserEnvelope;
 	errorText?: string;
+	persistentArtifactStore?: PersistentSessionArtifactStore;
 }): Promise<ToolPresentation> {
-	const { commandInfo, cwd, envelope, errorText } = options;
+	const { commandInfo, cwd, envelope, errorText, persistentArtifactStore } = options;
 	if (errorText) {
 		return {
 			content: [{ type: "text", text: errorText }],
@@ -472,9 +558,9 @@ export async function buildToolPresentation(options: {
 	const summary = formatSummary(commandInfo, data);
 	const presentation =
 		commandInfo.command === "batch" && Array.isArray(data)
-			? await buildBatchPresentation({ cwd, data: data as AgentBrowserBatchResult[], summary })
+			? await buildBatchPresentation({ cwd, data: data as AgentBrowserBatchResult[], persistentArtifactStore, summary })
 			: commandInfo.command === "snapshot" && isRecord(data)
-				? await buildSnapshotPresentation(data)
+				? await buildSnapshotPresentation(data, persistentArtifactStore)
 				: {
 						content: [{ type: "text" as const, text: formatContentText(commandInfo, data) }],
 						data,

package/extensions/agent-browser/lib/results/snapshot.ts

@@ -6,7 +6,7 @@
  * Invariants/Assumptions: Snapshot compaction should stay helpful even if upstream snapshot text formatting shifts, so structured parsing is best-effort and always has a resilient raw-outline fallback.
  */
 
-import { writeSecureTempFile } from "../temp.js";
+import { type PersistentSessionArtifactStore, writePersistentSessionArtifactFile, writeSecureTempFile } from "../temp.js";
 import { type ToolPresentation, compareRefIds, countLines, isRecord, normalizeWhitespace, truncateText } from "./shared.js";
 
 const SNAPSHOT_INLINE_MAX_CHARS = 6_000;
@@ -463,12 +463,18 @@ function canUseStructuredSnapshotPreview(snapshotLines: SnapshotLine[], refEntri
 	);
 }
 
-async function writeSnapshotSpillFile(data: Record<string, unknown>): Promise<string> {
-	return await writeSecureTempFile({
+async function writeSnapshotSpillFile(
+	data: Record<string, unknown>,
+	persistentArtifactStore: PersistentSessionArtifactStore | undefined,
+): Promise<string> {
+	const options = {
 		content: JSON.stringify(data, null, 2),
 		prefix: SNAPSHOT_SPILL_FILE_PREFIX,
 		suffix: ".json",
-	});
+	};
+	return persistentArtifactStore
+		? await writePersistentSessionArtifactFile({ ...options, store: persistentArtifactStore })
+		: await writeSecureTempFile(options);
 }
 
 export function formatSnapshotSummary(data: Record<string, unknown>): string {
@@ -487,7 +493,10 @@ export function formatRawSnapshotText(data: Record<string, unknown>): string {
 	return `Origin: ${origin}\nRefs: ${refs}\n\n${snapshot}`;
 }
 
-export async function buildSnapshotPresentation(data: Record<string, unknown>): Promise<ToolPresentation> {
+export async function buildSnapshotPresentation(
+	data: Record<string, unknown>,
+	persistentArtifactStore: PersistentSessionArtifactStore | undefined = undefined,
+): Promise<ToolPresentation> {
 	const summary = formatSnapshotSummary(data);
 	const rawText = formatRawSnapshotText(data);
 	if (!shouldCompactSnapshot(rawText, data)) {
@@ -501,7 +510,7 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 	let fullOutputPath: string | undefined;
 	let spillErrorText: string | undefined;
 	try {
-		fullOutputPath = await writeSnapshotSpillFile(data);
+		fullOutputPath = await writeSnapshotSpillFile(data, persistentArtifactStore);
 	} catch (error) {
 		spillErrorText = error instanceof Error ? error.message : String(error);
 	}

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

@@ -10,6 +10,8 @@ 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";
@@ -57,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;
@@ -84,8 +100,20 @@ 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;
@@ -467,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") {
@@ -556,6 +674,7 @@ export function buildExecutionPlan(
 	const explicitSessionName = extractExplicitSessionName(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;
@@ -587,10 +706,14 @@ export function buildExecutionPlan(
 		sessionName = options.freshSessionName;
 	}
 
+	if (compatibilityWorkaround) {
+		effectiveArgs.push("--user-agent", getDefaultHeadlessCompatUserAgent());
+	}
 	effectiveArgs.push(...args);
 
 	return {
 		commandInfo,
+		compatibilityWorkaround,
 		effectiveArgs,
 		managedSessionName,
 		plainTextInspection,
@@ -602,9 +725,54 @@ 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[] = [];
+	const commandTokens = extractCommandTokens(args);
+	return { command: commandTokens[0], subcommand: commandTokens[1] };
+}
 
+export function extractCommandTokens(args: string[]): string[] {
 	for (let index = 0; index < args.length; index += 1) {
 		const token = args[index];
 		if (token.startsWith("--session=")) {
@@ -617,11 +785,7 @@ export function parseCommandInfo(args: string[]): CommandInfo {
 			}
 			continue;
 		}
-		commands.push(token);
-		if (commands.length === 2) {
-			break;
-		}
+		return args.slice(index);
 	}
-
-	return { command: commands[0], subcommand: commands[1] };
+	return [];
 }

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.2",
+  "version": "0.2.4",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",