pi-agent-browser-native 0.2.44 → 0.2.45

package/extensions/agent-browser/lib/bash-guard.ts

@@ -0,0 +1,205 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV = "PI_AGENT_BROWSER_ALLOW_DIRECT_BASH";
+const DIRECT_AGENT_BROWSER_EXECUTABLE_PATTERN = /^(?:[.~]|\.\.?|\/)?(?:[^\s;&|]+\/)?agent-browser$/;
+const HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN = /^\s*(?:command\s+-v|which|type\s+-P)\s+agent-browser\s*$/;
+const PACKAGE_NAME = "pi-agent-browser-native";
+
+type ShellQuoteState = "double" | "single" | undefined;
+
+function isShellAssignmentToken(token: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
+}
+
+function stripOuterQuotes(token: string): string {
+	if (token.length >= 2 && ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'")))) {
+		return token.slice(1, -1);
+	}
+	return token;
+}
+
+function segmentLaunchesAgentBrowser(tokens: string[]): boolean {
+	let index = 0;
+	while (index < tokens.length && isShellAssignmentToken(tokens[index])) {
+		index += 1;
+	}
+	if (index >= tokens.length) {
+		return false;
+	}
+
+	let executableToken = tokens[index];
+	if (executableToken === "env") {
+		index += 1;
+		while (index < tokens.length && isShellAssignmentToken(tokens[index])) {
+			index += 1;
+		}
+		executableToken = tokens[index] ?? "";
+	}
+	if (executableToken === "npx" || executableToken === "bunx") {
+		index += 1;
+		while (index < tokens.length && tokens[index].startsWith("-")) {
+			index += 1;
+		}
+		executableToken = tokens[index] ?? "";
+	}
+	if (executableToken === "pnpm" || executableToken === "yarn") {
+		index += 1;
+		if (tokens[index] !== "dlx") {
+			return false;
+		}
+		index += 1;
+		while (index < tokens.length && tokens[index].startsWith("-")) {
+			index += 1;
+		}
+		executableToken = tokens[index] ?? "";
+	}
+	return DIRECT_AGENT_BROWSER_EXECUTABLE_PATTERN.test(executableToken);
+}
+
+// Best-effort detection for common direct launches only. This is an ergonomics guard,
+// not a general-purpose bash parser or security boundary.
+export function looksLikeDirectAgentBrowserBash(command: string): boolean {
+	let currentToken = "";
+	let quoteState: ShellQuoteState;
+	let awaitingHeredocDelimiter: { stripTabs: boolean } | undefined;
+	let pendingHeredoc: { delimiter: string; stripTabs: boolean } | undefined;
+	let pendingHeredocLine = "";
+	let segmentTokens: string[] = [];
+
+	const acceptToken = (token: string) => {
+		if (token.length === 0) {
+			return;
+		}
+		if (awaitingHeredocDelimiter) {
+			pendingHeredoc = {
+				delimiter: stripOuterQuotes(token),
+				stripTabs: awaitingHeredocDelimiter.stripTabs,
+			};
+			awaitingHeredocDelimiter = undefined;
+			return;
+		}
+		segmentTokens.push(token);
+	};
+	const flushToken = () => {
+		acceptToken(currentToken);
+		currentToken = "";
+	};
+	const flushSegment = () => {
+		const launchesAgentBrowser = segmentLaunchesAgentBrowser(segmentTokens);
+		segmentTokens = [];
+		return launchesAgentBrowser;
+	};
+
+	for (let index = 0; index < command.length; index += 1) {
+		const char = command[index];
+		if (pendingHeredoc) {
+			if (char === "\n") {
+				const candidate = pendingHeredoc.stripTabs ? pendingHeredocLine.replace(/^\t+/, "") : pendingHeredocLine;
+				if (candidate === pendingHeredoc.delimiter) {
+					pendingHeredoc = undefined;
+				}
+				pendingHeredocLine = "";
+				continue;
+			}
+			pendingHeredocLine += char;
+			continue;
+		}
+
+		if (quoteState === "single") {
+			currentToken += char;
+			if (char === "'") {
+				quoteState = undefined;
+			}
+			continue;
+		}
+		if (quoteState === "double") {
+			currentToken += char;
+			if (char === "\\" && index + 1 < command.length) {
+				currentToken += command[index + 1];
+				index += 1;
+				continue;
+			}
+			if (char === '"') {
+				quoteState = undefined;
+			}
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			currentToken += char;
+			quoteState = char === "'" ? "single" : "double";
+			continue;
+		}
+		if (char === "\\" && index + 1 < command.length) {
+			currentToken += char;
+			currentToken += command[index + 1];
+			index += 1;
+			continue;
+		}
+		if (char === "\n") {
+			flushToken();
+			if (flushSegment()) {
+				return true;
+			}
+			continue;
+		}
+		if (/\s/.test(char)) {
+			flushToken();
+			continue;
+		}
+		const threeCharOperator = command.slice(index, index + 3);
+		if (threeCharOperator === "<<-") {
+			flushToken();
+			awaitingHeredocDelimiter = { stripTabs: true };
+			index += 2;
+			continue;
+		}
+		const twoCharOperator = command.slice(index, index + 2);
+		if (twoCharOperator === "<<") {
+			flushToken();
+			awaitingHeredocDelimiter = { stripTabs: false };
+			index += 1;
+			continue;
+		}
+		if (twoCharOperator === "&&" || twoCharOperator === "||") {
+			flushToken();
+			if (flushSegment()) {
+				return true;
+			}
+			index += 1;
+			continue;
+		}
+		if (char === "|" || char === ";" || char === "&") {
+			flushToken();
+			if (flushSegment()) {
+				return true;
+			}
+			continue;
+		}
+		currentToken += char;
+	}
+
+	flushToken();
+	return flushSegment();
+}
+
+export function isHarmlessAgentBrowserInspectionCommand(command: string): boolean {
+	return HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN.test(command);
+}
+
+function isTruthyEnvValue(value: string | undefined): boolean {
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+
+async function isPackageDevelopmentCwd(cwd: string): Promise<boolean> {
+	try {
+		const packageJson = JSON.parse(await readFile(join(cwd, "package.json"), "utf8")) as { name?: unknown };
+		return packageJson.name === PACKAGE_NAME;
+	} catch {
+		return false;
+	}
+}
+
+export async function isDirectAgentBrowserBashAllowed(cwd: string): Promise<boolean> {
+	return isTruthyEnvValue(process.env[DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV]) || await isPackageDevelopmentCwd(cwd);
+}

package/extensions/agent-browser/lib/electron/cdp.ts

@@ -0,0 +1,69 @@
+/**
+ * Purpose: Parse and fetch Chrome DevTools Protocol metadata for wrapper-owned Electron launches.
+ * Responsibilities: Normalize CDP version/target JSON and perform bounded localhost CDP JSON fetches.
+ * Scope: Tiny Electron CDP boundary helpers only; launch, status, cleanup, and target selection stay in their owning modules.
+ * Usage: Imported by Electron launch and cleanup paths when polling `/json/version` and `/json/list`.
+ * Invariants/Assumptions: Malformed or unavailable CDP endpoints return undefined/empty metadata rather than throwing, matching prior caller behavior.
+ */
+
+import { isRecord } from "../parsing.js";
+
+const ELECTRON_CDP_FETCH_TIMEOUT_MS = 1_000;
+
+export interface ElectronCdpVersion {
+	browser?: string;
+	protocolVersion?: string;
+	userAgent?: string;
+	v8Version?: string;
+	webKitVersion?: string;
+	webSocketDebuggerUrl?: string;
+}
+
+export interface ElectronCdpTarget {
+	id?: string;
+	title?: string;
+	type?: string;
+	url?: string;
+	webSocketDebuggerUrl?: string;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+export function parseCdpVersion(value: unknown): ElectronCdpVersion | undefined {
+	if (!isRecord(value)) return undefined;
+	return {
+		browser: asString(value.Browser) ?? asString(value.browser),
+		protocolVersion: asString(value["Protocol-Version"]) ?? asString(value.protocolVersion),
+		userAgent: asString(value["User-Agent"]) ?? asString(value.userAgent),
+		v8Version: asString(value["V8-Version"]) ?? asString(value.v8Version),
+		webKitVersion: asString(value["WebKit-Version"]) ?? asString(value.webKitVersion),
+		webSocketDebuggerUrl: asString(value.webSocketDebuggerUrl),
+	};
+}
+
+export function parseCdpTargets(value: unknown): ElectronCdpTarget[] {
+	if (!Array.isArray(value)) return [];
+	return value.filter(isRecord).map((target) => ({
+		id: asString(target.id),
+		title: asString(target.title),
+		type: asString(target.type),
+		url: asString(target.url),
+		webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
+	}));
+}
+
+export async function fetchCdpJson(url: string): Promise<unknown | undefined> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, { signal: controller.signal });
+		if (!response.ok) return undefined;
+		return await response.json() as unknown;
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timeout);
+	}
+}

package/extensions/agent-browser/lib/electron/cleanup.ts

@@ -7,13 +7,14 @@
  */
 
 import { execFile, type ChildProcess } from "node:child_process";
-import { access, rm } from "node:fs/promises";
+import { rm } from "node:fs/promises";
 import { promisify } from "node:util";
 
+import { fetchCdpJson, parseCdpTargets, parseCdpVersion } from "./cdp.js";
 import { ELECTRON_PROFILE_DIR_PREFIX, type ElectronCdpTarget, type ElectronCdpVersion, type ElectronLaunchRecord } from "./launch.js";
+import { pathExists } from "../fs-utils.js";
 import { getSecureTempChildDirectoryValidationError } from "../temp.js";
 
-const ELECTRON_STATUS_FETCH_TIMEOUT_MS = 1_000;
 const ELECTRON_CLEANUP_DEFAULT_TIMEOUT_MS = 5_000;
 const ELECTRON_CLEANUP_POLL_INTERVAL_MS = 100;
 const RESTORED_PROCESS_COMMAND_TIMEOUT_MS = 1_000;
@@ -50,51 +51,6 @@ function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
-function asString(value: unknown): string | undefined {
-	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
-}
-
-function parseCdpVersion(value: unknown): ElectronCdpVersion | undefined {
-	if (!isRecord(value)) return undefined;
-	return {
-		browser: asString(value.Browser) ?? asString(value.browser),
-		protocolVersion: asString(value["Protocol-Version"]) ?? asString(value.protocolVersion),
-		userAgent: asString(value["User-Agent"]) ?? asString(value.userAgent),
-		v8Version: asString(value["V8-Version"]) ?? asString(value.v8Version),
-		webKitVersion: asString(value["WebKit-Version"]) ?? asString(value.webKitVersion),
-		webSocketDebuggerUrl: asString(value.webSocketDebuggerUrl),
-	};
-}
-
-function parseCdpTargets(value: unknown): ElectronCdpTarget[] {
-	if (!Array.isArray(value)) return [];
-	return value.filter(isRecord).map((target) => ({
-		id: asString(target.id),
-		title: asString(target.title),
-		type: asString(target.type),
-		url: asString(target.url),
-		webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
-	}));
-}
-
-async function fetchJson(url: string): Promise<unknown | undefined> {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), ELECTRON_STATUS_FETCH_TIMEOUT_MS);
-	try {
-		const response = await fetch(url, { signal: controller.signal });
-		if (!response.ok) return undefined;
-		return await response.json() as unknown;
-	} catch {
-		return undefined;
-	} finally {
-		clearTimeout(timeout);
-	}
-}
-
 function isPidAlive(pid: number | undefined): boolean | undefined {
 	if (!pid || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
 	try {
@@ -106,19 +62,10 @@ function isPidAlive(pid: number | undefined): boolean | undefined {
 	}
 }
 
-async function pathExists(path: string): Promise<boolean> {
-	try {
-		await access(path);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 async function isPortAlive(port: number): Promise<{ targets: ElectronCdpTarget[]; version?: ElectronCdpVersion }> {
-	const version = parseCdpVersion(await fetchJson(`http://127.0.0.1:${port}/json/version`));
+	const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`));
 	if (!version) return { targets: [] };
-	const targets = parseCdpTargets(await fetchJson(`http://127.0.0.1:${port}/json/list`));
+	const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`));
 	return { targets, version };
 }
 

package/extensions/agent-browser/lib/electron/discovery.ts

@@ -11,6 +11,8 @@ import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 
+import { pathExists } from "../fs-utils.js";
+
 export const ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS = 50;
 export const ELECTRON_DISCOVERY_MAX_RESULTS = 200;
 
@@ -150,15 +152,6 @@ function resolveLocations(locations: ElectronDiscoveryScanLocations | undefined)
 	};
 }
 
-async function pathExists(path: string): Promise<boolean> {
-	try {
-		await access(path, fsConstants.F_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 async function isDirectory(path: string): Promise<boolean> {
 	try {
 		return (await stat(path)).isDirectory();

package/extensions/agent-browser/lib/electron/launch.ts

@@ -11,6 +11,13 @@ import { randomUUID } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";
 import { dirname } from "node:path";
 
+import {
+	fetchCdpJson,
+	parseCdpTargets,
+	parseCdpVersion,
+	type ElectronCdpTarget,
+	type ElectronCdpVersion,
+} from "./cdp.js";
 import {
 	discoverElectronApps,
 	inspectElectronAppPath,
@@ -19,6 +26,8 @@ import {
 } from "./discovery.js";
 import { createSecureTempDirectory } from "../temp.js";
 
+export type { ElectronCdpTarget, ElectronCdpVersion } from "./cdp.js";
+
 export const ELECTRON_LAUNCH_RECORD_VERSION = 1;
 export const ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS = 15_000;
 export const ELECTRON_LAUNCH_MAX_TIMEOUT_MS = 120_000;
@@ -27,7 +36,6 @@ const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
 export const ELECTRON_PROFILE_DIR_PREFIX = "electron-profile-";
 const ELECTRON_DEFAULT_APP_ARGS = ["--disable-extensions", "--no-first-run", "--no-default-browser-check"] as const;
 const ELECTRON_DEVTOOLS_POLL_INTERVAL_MS = 100;
-const ELECTRON_CDP_FETCH_TIMEOUT_MS = 1_000;
 
 export interface ElectronDevToolsActivePortRead {
 	error?: string;
@@ -59,23 +67,6 @@ export type ElectronLaunchFailureReason =
 	| "spawn-error"
 	| "timeout";
 
-export interface ElectronCdpVersion {
-	browser?: string;
-	protocolVersion?: string;
-	userAgent?: string;
-	v8Version?: string;
-	webKitVersion?: string;
-	webSocketDebuggerUrl?: string;
-}
-
-export interface ElectronCdpTarget {
-	id?: string;
-	title?: string;
-	type?: string;
-	url?: string;
-	webSocketDebuggerUrl?: string;
-}
-
 export interface ElectronLaunchRecord {
 	appName: string;
 	appPath?: string;
@@ -200,37 +191,6 @@ export async function resolveElectronLaunchTarget(options: ResolveElectronTarget
 	return undefined;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
-function asString(value: unknown): string | undefined {
-	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
-}
-
-function parseCdpVersion(value: unknown): ElectronCdpVersion | undefined {
-	if (!isRecord(value)) return undefined;
-	return {
-		browser: asString(value.Browser) ?? asString(value.browser),
-		protocolVersion: asString(value["Protocol-Version"]) ?? asString(value.protocolVersion),
-		userAgent: asString(value["User-Agent"]) ?? asString(value.userAgent),
-		v8Version: asString(value["V8-Version"]) ?? asString(value.v8Version),
-		webKitVersion: asString(value["WebKit-Version"]) ?? asString(value.webKitVersion),
-		webSocketDebuggerUrl: asString(value.webSocketDebuggerUrl),
-	};
-}
-
-function parseCdpTargets(value: unknown): ElectronCdpTarget[] {
-	if (!Array.isArray(value)) return [];
-	return value.filter(isRecord).map((target) => ({
-		id: asString(target.id),
-		title: asString(target.title),
-		type: asString(target.type),
-		url: asString(target.url),
-		webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
-	}));
-}
-
 function targetMatchesType(target: ElectronCdpTarget, targetType: "any" | "page" | "webview" | undefined): boolean {
 	return targetType === undefined || targetType === "any" || target.type === targetType;
 }
@@ -245,20 +205,6 @@ function selectElectronConnectArg(options: {
 	return targetWebSocket ?? options.version.webSocketDebuggerUrl ?? String(options.port);
 }
 
-async function fetchJson(url: string): Promise<unknown | undefined> {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
-	try {
-		const response = await fetch(url, { signal: controller.signal });
-		if (!response.ok) return undefined;
-		return await response.json() as unknown;
-	} catch {
-		return undefined;
-	} finally {
-		clearTimeout(timeout);
-	}
-}
-
 async function readDevToolsActivePort(userDataDir: string): Promise<ElectronDevToolsActivePortRead> {
 	const path = `${userDataDir}/${DEVTOOLS_ACTIVE_PORT_FILE}`;
 	try {
@@ -304,9 +250,9 @@ async function pollDevToolsActivePort(options: {
 
 async function pollCdpMetadata(port: number, deadlineMs: number): Promise<{ targets: ElectronCdpTarget[]; version: ElectronCdpVersion } | undefined> {
 	while (Date.now() <= deadlineMs) {
-		const version = parseCdpVersion(await fetchJson(`http://127.0.0.1:${port}/json/version`));
+		const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`));
 		if (version) {
-			const targets = parseCdpTargets(await fetchJson(`http://127.0.0.1:${port}/json/list`));
+			const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`));
 			return { targets, version };
 		}
 		await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);

package/extensions/agent-browser/lib/electron/text.ts

@@ -0,0 +1,13 @@
+/**
+ * Purpose: Keep small Electron presentation string helpers in one place.
+ * Responsibilities: Trim optional probe strings and bound them to model-visible lengths.
+ * Scope: Electron diagnostics/probe text helpers only; redaction and result formatting stay with their owning modules.
+ * Usage: Imported by Electron host probes and browser-run Electron diagnostics.
+ * Invariants/Assumptions: Empty or whitespace-only strings stay omitted, and truncation keeps the prior ellipsis behavior.
+ */
+
+export function boundElectronProbeString(value: string | undefined, maxLength = 240): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	return trimmed.length > maxLength ? `${trimmed.slice(0, Math.max(0, maxLength - 3))}...` : trimmed;
+}

package/extensions/agent-browser/lib/fs-utils.ts

@@ -0,0 +1,18 @@
+import { access, stat } from "node:fs/promises";
+
+export async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function directoryExists(path: string): Promise<boolean> {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}