pi-agent-browser-native 0.1.5 → 0.2.0

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

@@ -1,6 +1,6 @@
 /**
  * Purpose: Build safe, deterministic agent-browser invocations for the pi-agent-browser extension.
- * Responsibilities: Validate raw tool arguments, derive implicit session names from the pi session identity, detect explicit session usage, and build the effective CLI argument list passed to the upstream agent-browser binary.
+ * Responsibilities: Validate raw tool arguments, derive implicit session names from the pi session identity, resolve implicit-session timeout/state helpers, detect explicit session usage, 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 implicit `--session` when appropriate.
@@ -11,13 +11,11 @@ import { basename } from "node:path";
 
 const STARTUP_SCOPED_FLAGS = ["--cdp", "--profile", "--session-name"] as const;
 const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
-const INSPECTION_ALLOW_PATTERNS = [
-	/\bagent[_ -]?browser\s+--(?:help|version)\b/i,
-	/\bagent[_ -]?browser\b.*\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b/i,
-	/\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b.*\bagent[_ -]?browser\b/i,
-	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
-	/\bwhy\s+(?:isn't|is not|doesn't|does not)\b.*\b(?:agent[_ -]?browser|agent_browser)\b/i,
-];
+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";
+const IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS";
+const DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 5_000;
 const LEGACY_BASH_ALLOW_PATTERNS = [
 	/\b(?:bash-oriented workflow|bash workflow)\b/i,
 	/\b(?:use|via|through|with)\s+bash\b/i,
@@ -50,13 +48,6 @@ const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--port",
 ]);
 const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
-const IMAGE_EXTENSION_TO_MIME_TYPE: Record<string, string> = {
-	".gif": "image/gif",
-	".jpeg": "image/jpeg",
-	".jpg": "image/jpeg",
-	".png": "image/png",
-	".webp": "image/webp",
-};
 const MAX_PROJECT_SLUG_LENGTH = 24;
 
 export interface CommandInfo {
@@ -64,9 +55,19 @@ export interface CommandInfo {
 	subcommand?: string;
 }
 
+export type SessionMode = "auto" | "fresh";
+
+export interface SessionRecoveryHint {
+	exampleArgs: string[];
+	exampleParams: { args: string[]; sessionMode: "fresh" };
+	reason: string;
+	recommendedSessionMode: "fresh";
+}
+
 export interface ExecutionPlan {
 	commandInfo: CommandInfo;
 	effectiveArgs: string[];
+	recoveryHint?: SessionRecoveryHint;
 	sessionName?: string;
 	startupScopedFlags: string[];
 	usedImplicitSession: boolean;
@@ -74,7 +75,6 @@ export interface ExecutionPlan {
 }
 
 export interface PromptPolicy {
-	allowAgentBrowserInspection: boolean;
 	allowLegacyAgentBrowserBash: boolean;
 }
 
@@ -82,6 +82,44 @@ export function hasUsableBraveApiKey(apiKey: string | null | undefined = process
 	return typeof apiKey === "string" && apiKey.trim().length > 0;
 }
 
+function parseTimeoutMs(rawValue: string | undefined, minimumValue: number): number | undefined {
+	if (typeof rawValue !== "string") return undefined;
+	const normalizedValue = rawValue.trim();
+	if (!/^\d+$/.test(normalizedValue)) return undefined;
+	const parsedValue = Number(normalizedValue);
+	if (!Number.isSafeInteger(parsedValue) || parsedValue < minimumValue) {
+		return undefined;
+	}
+	return parsedValue;
+}
+
+export function getImplicitSessionIdleTimeoutMs(env: NodeJS.ProcessEnv = process.env): string {
+	return String(
+		parseTimeoutMs(env[IMPLICIT_SESSION_IDLE_TIMEOUT_ENV], 0) ??
+			parseTimeoutMs(env[AGENT_BROWSER_IDLE_TIMEOUT_ENV], 0) ??
+			DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS,
+	);
+}
+
+export function getImplicitSessionCloseTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+	return parseTimeoutMs(env[IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV], 0) ?? DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS;
+}
+
+export function resolveImplicitSessionActiveState(options: {
+	command?: string;
+	priorActive: boolean;
+	succeeded: boolean;
+	usedImplicitSession: boolean;
+}): boolean {
+	const { command, priorActive, succeeded, usedImplicitSession } = options;
+	if (!usedImplicitSession) return priorActive;
+	if (command === "close") {
+		return succeeded ? false : priorActive;
+	}
+	if (!command) return priorActive;
+	return priorActive || succeeded;
+}
+
 export function createEphemeralSessionSeed(): string {
 	return randomUUID();
 }
@@ -141,7 +179,6 @@ export function getStartupScopedFlags(args: string[]): string[] {
 
 export function buildPromptPolicy(prompt: string): PromptPolicy {
 	return {
-		allowAgentBrowserInspection: INSPECTION_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
 		allowLegacyAgentBrowserBash: LEGACY_BASH_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
 	};
 }
@@ -176,21 +213,29 @@ export function getLatestUserPrompt(branch: unknown[]): string {
 
 export function buildExecutionPlan(
 	args: string[],
-	options: { implicitSessionActive: boolean; implicitSessionName: string; useActiveSession: boolean },
+	options: { implicitSessionActive: boolean; implicitSessionName: string; sessionMode: SessionMode },
 ): ExecutionPlan {
 	const commandInfo = parseCommandInfo(args);
 	const explicitSessionName = extractExplicitSessionName(args);
 	const startupScopedFlags = getStartupScopedFlags(args);
 	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
+	let recoveryHint: SessionRecoveryHint | undefined;
 	let sessionName = explicitSessionName;
 	let usedImplicitSession = false;
 	let validationError: string | undefined;
 
-	if (!explicitSessionName && options.useActiveSession) {
+	if (!explicitSessionName && options.sessionMode === "auto") {
 		if (options.implicitSessionActive && startupScopedFlags.length > 0) {
+			recoveryHint = {
+				exampleArgs: args,
+				exampleParams: { args, sessionMode: "fresh" },
+				reason:
+					"Startup-scoped flags like --profile, --session-name, and --cdp need a fresh upstream launch once the implicit session is already active.",
+				recommendedSessionMode: "fresh",
+			};
 			validationError = [
 				`The current implicit agent-browser session is already running, so startup-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
-				"Reuse the existing implicit session without those flags, or start a fresh upstream session explicitly with `--session ...` (or `useActiveSession: false`) for a new launch.",
+				"Retry this call with `sessionMode: \"fresh\"` to force a fresh upstream launch, or pass an explicit `--session ...` if you want to name the new session yourself.",
 			].join(" ");
 		} else {
 			effectiveArgs.push("--session", options.implicitSessionName);
@@ -204,6 +249,7 @@ export function buildExecutionPlan(
 	return {
 		commandInfo,
 		effectiveArgs,
+		recoveryHint,
 		sessionName,
 		startupScopedFlags,
 		usedImplicitSession,
@@ -235,7 +281,3 @@ export function parseCommandInfo(args: string[]): CommandInfo {
 	return { command: commands[0], subcommand: commands[1] };
 }
 
-export function getImageMimeType(filePath: string): string | undefined {
-	const extension = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
-	return IMAGE_EXTENSION_TO_MIME_TYPE[extension];
-}

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

@@ -1,26 +1,115 @@
 /**
  * Purpose: Create private temporary files for the pi-agent-browser extension without leaking artifacts broadly on disk.
- * Responsibilities: Maintain a process-private temp root, prune stale temp roots from prior runs, create securely permissioned temp files, and best-effort clean the current run's temp root on process exit.
+ * 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.
  * 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, the active run uses a dedicated 0700 directory, and files are created with exclusive 0600 permissions.
+ * 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.
  */
 
 import { randomBytes } from "node:crypto";
-import { chmod, mkdtemp, open, readdir, rm, stat } from "node:fs/promises";
 import { rmSync } from "node:fs";
+import { chmod, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 const TEMP_ROOT_PREFIX = "pi-agent-browser-";
+const TEMP_ROOT_MARKER_FILE_NAME = ".pi-agent-browser-owner.json";
+const TEMP_ROOT_MARKER_KIND = "pi-agent-browser-temp-root";
+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;
+
+interface TempRootOwnershipRecord {
+	createdAtMs: number;
+	kind: string;
+	ownerUid?: number;
+	version: number;
+}
 
 let sessionTempRootPromise: Promise<string> | undefined;
 let exitCleanupRegistered = false;
+let tempMutationQueue = Promise.resolve();
+const ownedTempRoots = new Set<string>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function getCurrentProcessUid(): number | undefined {
+	return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+
+function parsePositiveInteger(rawValue: string | undefined): number | undefined {
+	if (typeof rawValue !== "string") return undefined;
+	const normalizedValue = rawValue.trim();
+	if (!/^\d+$/.test(normalizedValue)) return undefined;
+	const parsedValue = Number(normalizedValue);
+	if (!Number.isSafeInteger(parsedValue) || parsedValue <= 0) return undefined;
+	return parsedValue;
+}
+
+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;
+	if (typeof value.createdAtMs !== "number" || !Number.isFinite(value.createdAtMs) || value.createdAtMs <= 0) return false;
+	return value.ownerUid === undefined || typeof value.ownerUid === "number";
+}
+
+function getTempArtifactByteLength(content: string | Uint8Array): number {
+	return typeof content === "string" ? Buffer.byteLength(content) : content.byteLength;
+}
+
+function enqueueTempMutation<T>(task: () => Promise<T>): Promise<T> {
+	const nextTask = tempMutationQueue.then(task, task);
+	tempMutationQueue = nextTask.then(
+		() => undefined,
+		() => undefined,
+	);
+	return nextTask;
+}
+
+async function getTempRootArtifactBytes(tempRoot: string): Promise<number> {
+	const entries = await readdir(tempRoot, { withFileTypes: true }).catch(() => []);
+	let totalBytes = 0;
+	for (const entry of entries) {
+		if (!entry.isFile() || entry.name === TEMP_ROOT_MARKER_FILE_NAME) continue;
+		const path = join(tempRoot, entry.name);
+		const stats = await stat(path).catch(() => undefined);
+		if (stats?.isFile()) {
+			totalBytes += stats.size;
+		}
+	}
+	return totalBytes;
+}
+
+async function readTempRootOwnershipMarker(tempRoot: string): Promise<TempRootOwnershipRecord | undefined> {
+	try {
+		const markerText = await readFile(join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME), "utf8");
+		const parsed = JSON.parse(markerText) as unknown;
+		return isTempRootOwnershipRecord(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function writeSecureTempRootOwnershipMarker(tempRoot: string, createdAtMs = Date.now()): Promise<string> {
+	const markerPath = join(tempRoot, TEMP_ROOT_MARKER_FILE_NAME);
+	const markerRecord: TempRootOwnershipRecord = {
+		createdAtMs,
+		kind: TEMP_ROOT_MARKER_KIND,
+		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;
+}
 
 async function pruneStaleTempRoots(currentTempRoot: string | undefined): Promise<void> {
 	const entries = await readdir(tmpdir(), { withFileTypes: true }).catch(() => []);
 	const cutoffTime = Date.now() - STALE_TEMP_ROOT_MAX_AGE_MS;
+	const currentUid = getCurrentProcessUid();
 
 	await Promise.all(
 		entries
@@ -28,30 +117,60 @@ async function pruneStaleTempRoots(currentTempRoot: string | undefined): Promise
 			.map(async (entry) => {
 				const path = join(tmpdir(), entry.name);
 				if (path === currentTempRoot) return;
+
+				const ownershipMarker = await readTempRootOwnershipMarker(path);
+				if (!ownershipMarker) return;
+				if (
+					currentUid !== undefined &&
+					ownershipMarker.ownerUid !== undefined &&
+					ownershipMarker.ownerUid !== currentUid
+				) {
+					return;
+				}
+
 				const stats = await stat(path).catch(() => undefined);
-				if (!stats || stats.mtimeMs >= cutoffTime) return;
+				if (!stats?.isDirectory() || stats.mtimeMs >= cutoffTime) return;
 				await rm(path, { force: true, recursive: true }).catch(() => undefined);
 			}),
 	);
 }
 
-function registerExitCleanup(tempRoot: string): void {
+function registerExitCleanup(): void {
 	if (exitCleanupRegistered) return;
 	exitCleanupRegistered = true;
 	process.once("exit", () => {
-		try {
-			rmSync(tempRoot, { force: true, recursive: true });
-		} catch {
-			// Best-effort cleanup only.
+		for (const tempRoot of ownedTempRoots) {
+			try {
+				rmSync(tempRoot, { force: true, recursive: true });
+			} catch {
+				// Best-effort cleanup only.
+			}
 		}
 	});
 }
 
+export function getSecureTempRootMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+	return parsePositiveInteger(env[TEMP_ROOT_MAX_BYTES_ENV]) ?? DEFAULT_TEMP_ROOT_MAX_BYTES;
+}
+
+async function assertSecureTempRootBudget(tempRoot: string, additionalBytes: number): Promise<void> {
+	if (additionalBytes <= 0) return;
+	const currentBytes = await getTempRootArtifactBytes(tempRoot);
+	const maxBytes = getSecureTempRootMaxBytes();
+	const nextBytes = currentBytes + additionalBytes;
+	if (nextBytes > maxBytes) {
+		throw new Error(`pi-agent-browser temp spill budget exceeded (${nextBytes} bytes > ${maxBytes} byte limit).`);
+	}
+}
+
 export async function cleanupSecureTempArtifacts(): Promise<void> {
-	const tempRoot = await sessionTempRootPromise?.catch(() => undefined);
-	sessionTempRootPromise = undefined;
-	if (!tempRoot) return;
-	await rm(tempRoot, { force: true, recursive: true }).catch(() => undefined);
+	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);
+	});
 }
 
 async function getSessionTempRoot(): Promise<string> {
@@ -60,7 +179,9 @@ async function getSessionTempRoot(): Promise<string> {
 			await pruneStaleTempRoots(undefined);
 			const tempRoot = await mkdtemp(join(tmpdir(), TEMP_ROOT_PREFIX));
 			await chmod(tempRoot, 0o700).catch(() => undefined);
-			registerExitCleanup(tempRoot);
+			await writeSecureTempRootOwnershipMarker(tempRoot);
+			ownedTempRoots.add(tempRoot);
+			registerExitCleanup();
 			return tempRoot;
 		})();
 	}
@@ -77,6 +198,18 @@ export async function openSecureTempFile(prefix: string, suffix: string): Promis
 	return { fileHandle, path };
 }
 
+export async function writeSecureTempChunk(options: {
+	content: string | Uint8Array;
+	fileHandle: Awaited<ReturnType<typeof open>>;
+	path: string;
+}): Promise<void> {
+	const { content, fileHandle, path } = options;
+	await enqueueTempMutation(async () => {
+		await assertSecureTempRootBudget(dirname(path), getTempArtifactByteLength(content));
+		await fileHandle.writeFile(content);
+	});
+}
+
 export async function writeSecureTempFile(options: {
 	content: string | Uint8Array;
 	prefix: string;
@@ -85,9 +218,19 @@ export async function writeSecureTempFile(options: {
 	const { content, prefix, suffix } = options;
 	const { fileHandle, path } = await openSecureTempFile(prefix, suffix);
 	try {
-		await fileHandle.writeFile(content);
+		await writeSecureTempChunk({ content, fileHandle, path });
+	} catch (error) {
+		await rm(path, { force: true }).catch(() => undefined);
+		throw error;
 	} finally {
 		await fileHandle.close();
 	}
 	return path;
 }
+
+export async function getSecureTempDebugState(): Promise<{ currentTempRoot?: string; ownedTempRoots: string[] }> {
+	return {
+		currentTempRoot: await sessionTempRootPromise?.catch(() => undefined),
+		ownedTempRoots: [...ownedTempRoots].sort(),
+	};
+}

package/package.json

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