pi-agent-browser-native 0.2.48 → 0.2.49

package/extensions/agent-browser/lib/argv-descriptor.ts

@@ -1,90 +0,0 @@
-/**
- * Purpose: Parse raw agent-browser argv once into a stable command descriptor for planners and policy.
- * Responsibilities: Own command-token extraction, command/subcommand identification, and descriptor construction.
- * Scope: Pure argv parsing; runtime planning and session policy consume descriptors instead of re-parsing tokens.
- */
-
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS } from "./argv-grammar.js";
-import { isOpenNavigationCommand } from "./command-taxonomy.js";
-
-export interface CommandInfo {
-	command?: string;
-	subcommand?: string;
-}
-
-export interface ArgvDescriptor {
-	commandInfo: CommandInfo;
-	commandTokens: string[];
-}
-
-function isBooleanLiteral(token: string | undefined): boolean {
-	const normalized = token?.trim().toLowerCase();
-	return normalized === "true" || normalized === "false";
-}
-
-export function findCommandStartIndex(args: string[]): number | undefined {
-	for (let index = 0; index < args.length; index += 1) {
-		const token = args[index];
-		if (token.startsWith("--session=")) {
-			continue;
-		}
-		if (token.startsWith("-")) {
-			const normalizedToken = token.split("=", 1)[0] ?? token;
-			if (VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
-				index += 1;
-			} else if (
-				GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken) &&
-				!token.includes("=") &&
-				isBooleanLiteral(args[index + 1])
-			) {
-				index += 1;
-			}
-			continue;
-		}
-		return index;
-	}
-	return undefined;
-}
-
-export function extractCommandTokens(args: string[]): string[] {
-	const commandStartIndex = findCommandStartIndex(args);
-	return commandStartIndex === undefined ? [] : args.slice(commandStartIndex);
-}
-
-function getOpenCommandTarget(commandTokens: string[]): string | undefined {
-	for (let index = 1; index < commandTokens.length; index += 1) {
-		const token = commandTokens[index];
-		if (token === "--init-script" || token === "--enable") {
-			index += 1;
-			continue;
-		}
-		if (token.startsWith("--init-script=") || token.startsWith("--enable=")) {
-			continue;
-		}
-		if (token.startsWith("-")) {
-			continue;
-		}
-		return token;
-	}
-	return undefined;
-}
-
-export function parseCommandInfoFromTokens(commandTokens: string[]): CommandInfo {
-	const command = commandTokens[0];
-	return {
-		command,
-		subcommand: isOpenNavigationCommand(command) ? getOpenCommandTarget(commandTokens) : commandTokens[1],
-	};
-}
-
-export function parseCommandInfo(args: string[]): CommandInfo {
-	return parseCommandInfoFromTokens(extractCommandTokens(args));
-}
-
-export function parseArgvDescriptor(args: string[]): ArgvDescriptor {
-	const commandTokens = extractCommandTokens(args);
-	return {
-		commandInfo: parseCommandInfoFromTokens(commandTokens),
-		commandTokens,
-	};
-}

package/extensions/agent-browser/lib/argv-grammar.ts

@@ -1,128 +0,0 @@
-/**
- * Purpose: Shared argv flag-shape metadata and helpers for command discovery and sessionless policy checks.
- * Responsibilities: Own global/command value-flag sets and boolean/value-flag validation used during argv parsing.
- * Scope: Pure token grammar; command semantics and subprocess execution live elsewhere.
- */
-
-export const GLOBAL_VALUE_FLAGS = [
-	"--session",
-	"--cdp",
-	"--config",
-	"--profile",
-	"--session-name",
-	"--proxy",
-	"--proxy-bypass",
-	"--headers",
-	"--executable-path",
-	"--extension",
-	"--init-script",
-	"--enable",
-	"--provider",
-	"-p",
-	"--engine",
-	"--state",
-	"--download-path",
-	"--screenshot-dir",
-	"--screenshot-format",
-	"--screenshot-quality",
-	"--color-scheme",
-	"--device",
-	"--args",
-	"--user-agent",
-	"--allowed-domains",
-	"--action-policy",
-	"--confirm-actions",
-	"--max-output",
-	"--model",
-	"--idle-timeout",
-] as const;
-
-export const COMMAND_VALUE_FLAGS = [
-	"--baseline",
-	"--body",
-	"--categories",
-	"--curl",
-	"--depth",
-	"-d",
-	"--domain",
-	"--expires",
-	"--filter",
-	"--fn",
-	"--label",
-	"--load",
-	"--method",
-	"--name",
-	"--older-than",
-	"--output",
-	"--path",
-	"--port",
-	"--resource-type",
-	"--resource-types",
-	"--sameSite",
-	"--selector",
-	"-s",
-	"--status",
-	"--text",
-	"--threshold",
-	"--timeout",
-	"--type",
-	"--url",
-	"--username",
-	"--password",
-	"--wait-until",
-] as const;
-
-export const VALUE_FLAGS: ReadonlySet<string> = new Set([...GLOBAL_VALUE_FLAGS, ...COMMAND_VALUE_FLAGS]);
-export const PREVALIDATED_VALUE_FLAGS: ReadonlySet<string> = new Set(GLOBAL_VALUE_FLAGS);
-export const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE: ReadonlySet<string> = new Set(["--args"]);
-export const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES: ReadonlySet<string> = new Set([
-	"--allow-file-access",
-	"--annotate",
-	"--auto-connect",
-	"--confirm-interactive",
-	"--content-boundaries",
-	"--debug",
-	"--headed",
-	"--ignore-https-errors",
-	"--json",
-	"--no-auto-dialog",
-	"--quiet",
-	"-q",
-	"--verbose",
-	"-v",
-]);
-
-export function getFlagName(token: string): string {
-	return token.split("=", 1)[0] ?? token;
-}
-
-export function isNonFlagToken(token: string | undefined): token is string {
-	return typeof token === "string" && !token.startsWith("-");
-}
-
-export function hasOnlyBooleanFlags(tokens: readonly string[], allowedFlags: ReadonlySet<string>): boolean {
-	return tokens.every((token) => token.startsWith("-") && allowedFlags.has(getFlagName(token)));
-}
-
-export function hasOnlyOptionFlags(
-	tokens: readonly string[],
-	allowedBooleanFlags: ReadonlySet<string>,
-	allowedValueFlags: ReadonlySet<string>,
-): boolean {
-	for (let index = 0; index < tokens.length; index += 1) {
-		const token = tokens[index];
-		if (!token.startsWith("-")) return false;
-		const flagName = getFlagName(token);
-		if (allowedBooleanFlags.has(flagName)) continue;
-		if (!allowedValueFlags.has(flagName)) return false;
-		if (token.includes("=")) continue;
-		const value = tokens[index + 1];
-		if (!isNonFlagToken(value)) return false;
-		index += 1;
-	}
-	return true;
-}
-
-export function stripSessionlessShapeGlobalFlags(commandTokens: readonly string[]): string[] {
-	return commandTokens.filter((token) => token !== "--json");
-}

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

@@ -1,205 +0,0 @@
-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/command-policy.ts

@@ -1,71 +0,0 @@
-/**
- * Purpose: Own upstream command-shape policies that decide whether the wrapper should allocate a managed browser session.
- * Responsibilities: Keep local/sessionless command grammar out of the runtime execution planner while preserving exact upstream shapes.
- * Scope: Pure argv-token policy; command discovery, subprocess execution, and presentation live in focused modules.
- */
-
-import type { ArgvDescriptor } from "./argv-descriptor.js";
-import { hasOnlyBooleanFlags, hasOnlyOptionFlags, isNonFlagToken, stripSessionlessShapeGlobalFlags } from "./argv-grammar.js";
-
-const SESSIONLESS_AUTH_SUBCOMMANDS = new Set(["save", "list", "show", "delete", "remove"]);
-const EMPTY_BOOLEAN_FLAGS = new Set<string>();
-const JSON_BOOLEAN_FLAGS = new Set(["--json"]);
-const AUTH_SAVE_BOOLEAN_FLAGS = new Set(["--json", "--password-stdin"]);
-const AUTH_SAVE_VALUE_FLAGS = new Set(["--password", "--password-selector", "--submit-selector", "--url", "--username", "--username-selector"]);
-const DASHBOARD_SUBCOMMANDS = new Set(["start", "stop"]);
-const DASHBOARD_START_VALUE_FLAGS = new Set(["--port"]);
-const DOCTOR_BOOLEAN_FLAGS = new Set(["--fix", "--json", "--offline", "--quick"]);
-const INSTALL_BOOLEAN_FLAGS = new Set(["--with-deps", "-d"]);
-const STATE_SESSIONLESS_SUBCOMMANDS = new Set(["list", "show", "clear", "clean", "rename"]);
-const STATE_CLEAN_VALUE_FLAGS = new Set(["--older-than"]);
-
-function isSessionlessAuthCommand(commandTokens: readonly string[]): boolean {
-	const [, subcommand, target, ...rest] = commandTokens;
-	if (!SESSIONLESS_AUTH_SUBCOMMANDS.has(subcommand ?? "")) return false;
-	if (subcommand === "list") return target === undefined;
-	if (!isNonFlagToken(target)) return false;
-	if (subcommand === "save") return hasOnlyOptionFlags(rest, AUTH_SAVE_BOOLEAN_FLAGS, AUTH_SAVE_VALUE_FLAGS);
-	return rest.length === 0;
-}
-
-function isSessionlessDashboardCommand(commandTokens: readonly string[]): boolean {
-	const [, subcommand, ...rest] = commandTokens;
-	if (subcommand === undefined) return true;
-	if (!DASHBOARD_SUBCOMMANDS.has(subcommand)) return false;
-	return subcommand === "start" ? hasOnlyOptionFlags(rest, JSON_BOOLEAN_FLAGS, DASHBOARD_START_VALUE_FLAGS) : rest.length === 0;
-}
-
-function isSessionlessStateCommand(commandTokens: readonly string[]): boolean {
-	const [, subcommand, firstArg, secondArg, ...rest] = commandTokens;
-	if (!STATE_SESSIONLESS_SUBCOMMANDS.has(subcommand ?? "")) return false;
-	if (subcommand === "list") return firstArg === undefined;
-	if (subcommand === "show") return isNonFlagToken(firstArg) && secondArg === undefined;
-	if (subcommand === "rename") return isNonFlagToken(firstArg) && isNonFlagToken(secondArg) && rest.length === 0;
-	if (subcommand === "clean") {
-		const optionTokens = commandTokens.slice(2);
-		return optionTokens.length > 0 && hasOnlyOptionFlags(optionTokens, EMPTY_BOOLEAN_FLAGS, STATE_CLEAN_VALUE_FLAGS);
-	}
-	if (subcommand !== "clear") return false;
-	if ((firstArg === "--all" || firstArg === "-a") && secondArg === undefined) return true;
-	if (!isNonFlagToken(firstArg)) return false;
-	return secondArg === undefined || (secondArg === "--all" && rest.length === 0);
-}
-
-function isSessionlessCommand(commandTokens: readonly string[]): boolean {
-	const normalizedTokens = stripSessionlessShapeGlobalFlags(commandTokens);
-	const [command, subcommand] = normalizedTokens;
-	if (command === "skills") return ["list", "get", "path"].includes(subcommand ?? "");
-	if (command === "auth") return isSessionlessAuthCommand(normalizedTokens);
-	if (command === "dashboard") return isSessionlessDashboardCommand(normalizedTokens);
-	if (command === "device") return normalizedTokens.length === 2 && subcommand === "list";
-	if (command === "doctor") return hasOnlyBooleanFlags(normalizedTokens.slice(1), DOCTOR_BOOLEAN_FLAGS);
-	if (command === "install") return hasOnlyBooleanFlags(normalizedTokens.slice(1), INSTALL_BOOLEAN_FLAGS);
-	if (command === "profiles" || command === "upgrade") return normalizedTokens.length === 1;
-	if (command === "session") return normalizedTokens.length === 2 && subcommand === "list";
-	if (command === "state") return isSessionlessStateCommand(normalizedTokens);
-	return false;
-}
-
-export function needsManagedSession(descriptor: ArgvDescriptor): boolean {
-	return !isSessionlessCommand(descriptor.commandTokens);
-}