pi-agent-browser-native 0.2.34 → 0.2.35

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

@@ -0,0 +1,90 @@
+/**
+ * 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

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

@@ -0,0 +1,71 @@
+/**
+ * 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);
+}

package/extensions/agent-browser/lib/command-taxonomy.ts

@@ -0,0 +1,336 @@
+/**
+ * Purpose: Centralize upstream agent-browser command capabilities that wrapper behavior depends on.
+ * Responsibilities: Normalize command aliases once and expose capability predicates for runtime planning,
+ * session/ref guards, result recommendations, and presentation summaries without coupling unrelated behaviors.
+ * Scope: Static command capability taxonomy only; command-shape parsing, spawning, and formatting live elsewhere.
+ */
+
+type CommandCapabilityFlag =
+	| "closesSession"
+	| "openNavigation"
+	| "readOnlyDiagnosticSessionTarget"
+	| "excludedFromPinning"
+	| "excludedFromPostCommandCorrection"
+	| "guardsPageRefs"
+	| "invalidatesBatchRefs"
+	| "eligibleForElectronHealthProbe"
+	| "navigationObservable"
+	| "triggersPostMutationSnapshot"
+	| "eligibleForPageChangeSummary";
+
+interface CommandCapabilityEntry extends Partial<Record<CommandCapabilityFlag, true>> {
+	aliases?: readonly string[];
+	command: string;
+}
+
+const COMMAND_CAPABILITIES: readonly CommandCapabilityEntry[] = [
+	{
+		command: "back",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		navigationObservable: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "batch",
+		excludedFromPostCommandCorrection: true,
+	},
+	{
+		command: "check",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "click",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		navigationObservable: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		aliases: ["quit", "exit"],
+		closesSession: true,
+		command: "close",
+		excludedFromPinning: true,
+		excludedFromPostCommandCorrection: true,
+	},
+	{
+		command: "console",
+		readOnlyDiagnosticSessionTarget: true,
+	},
+	{
+		command: "cookies",
+		readOnlyDiagnosticSessionTarget: true,
+	},
+	{
+		command: "dblclick",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		navigationObservable: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "dialog",
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "download",
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+	},
+	{
+		command: "drag",
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+	},
+	{
+		command: "errors",
+		readOnlyDiagnosticSessionTarget: true,
+	},
+	{
+		command: "fill",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "find",
+		eligibleForElectronHealthProbe: true,
+	},
+	{
+		command: "focus",
+		guardsPageRefs: true,
+	},
+	{
+		command: "forward",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		navigationObservable: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "hover",
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "keydown",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "keyboard",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "keyup",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "mouse",
+		eligibleForElectronHealthProbe: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+	},
+	{
+		command: "network",
+		readOnlyDiagnosticSessionTarget: true,
+	},
+	{
+		aliases: ["goto", "navigate"],
+		command: "open",
+		eligibleForPageChangeSummary: true,
+		excludedFromPinning: true,
+		invalidatesBatchRefs: true,
+		openNavigation: true,
+	},
+	{
+		command: "pdf",
+		eligibleForPageChangeSummary: true,
+	},
+	{
+		aliases: ["key"],
+		command: "press",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "pushstate",
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "reload",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		navigationObservable: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "screenshot",
+		eligibleForPageChangeSummary: true,
+	},
+	{
+		command: "scroll",
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		aliases: ["scrollinto"],
+		command: "scrollintoview",
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "select",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "session",
+		excludedFromPinning: true,
+		excludedFromPostCommandCorrection: true,
+	},
+	{
+		command: "storage",
+		readOnlyDiagnosticSessionTarget: true,
+	},
+	{
+		command: "swipe",
+		eligibleForPageChangeSummary: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "tab",
+		excludedFromPinning: true,
+		excludedFromPostCommandCorrection: true,
+	},
+	{
+		command: "tap",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "type",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "uncheck",
+		eligibleForElectronHealthProbe: true,
+		eligibleForPageChangeSummary: true,
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+		triggersPostMutationSnapshot: true,
+	},
+	{
+		command: "upload",
+		guardsPageRefs: true,
+		invalidatesBatchRefs: true,
+	},
+];
+
+const COMMAND_CAPABILITY_BY_NAME = new Map<string, CommandCapabilityEntry>();
+for (const entry of COMMAND_CAPABILITIES) {
+	COMMAND_CAPABILITY_BY_NAME.set(entry.command, entry);
+	for (const alias of entry.aliases ?? []) {
+		COMMAND_CAPABILITY_BY_NAME.set(alias, entry);
+	}
+}
+
+function getCommandCapability(command: string | undefined): CommandCapabilityEntry | undefined {
+	return command === undefined ? undefined : COMMAND_CAPABILITY_BY_NAME.get(command);
+}
+
+function hasCommandCapability(command: string | undefined, capability: CommandCapabilityFlag): boolean {
+	return getCommandCapability(command)?.[capability] === true;
+}
+
+export function normalizeCommandName(command: string | undefined): string | undefined {
+	return getCommandCapability(command)?.command ?? command;
+}
+
+export function isCloseCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "closesSession");
+}
+
+export function isOpenNavigationCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "openNavigation");
+}
+
+export function isReadOnlyDiagnosticSessionTargetCommand(command: string | undefined, _subcommand?: string): boolean {
+	return hasCommandCapability(command, "readOnlyDiagnosticSessionTarget");
+}
+
+export function isSessionTabPinningExcludedCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "excludedFromPinning");
+}
+
+export function isSessionTabPostCommandCorrectionExcludedCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "excludedFromPostCommandCorrection");
+}
+
+export function isRefInvalidatingBatchCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "invalidatesBatchRefs");
+}
+
+export function isRefGuardedCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "guardsPageRefs");
+}
+
+export function isElectronPostCommandHealthCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "eligibleForElectronHealthProbe");
+}
+
+export function isNavigationObservableCommandName(command: string | undefined): boolean {
+	return hasCommandCapability(command, "navigationObservable");
+}
+
+export function isPageMutationCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "triggersPostMutationSnapshot");
+}
+
+export function isPageChangeSummaryCommand(command: string | undefined): boolean {
+	return hasCommandCapability(command, "eligibleForPageChangeSummary");
+}

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

@@ -33,6 +33,7 @@ export interface ElectronLaunchStatus {
 export interface ElectronCleanupStep {
 	error?: string;
 	resource: "debug-port" | "managed-session" | "process" | "user-data-dir";
+	sessionName?: string;
 	state: "already-gone" | "failed" | "removed" | "skipped";
 }
 

package/extensions/agent-browser/lib/executable-path.ts

@@ -0,0 +1,19 @@
+import { constants as fsConstants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+
+export async function executableExistsOnPath(command: string): Promise<boolean> {
+	const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [""];
+	for (const directory of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+		for (const extension of extensions) {
+			try {
+				const candidate = join(directory, `${command}${extension}`);
+				await access(candidate, fsConstants.X_OK);
+				if ((await stat(candidate)).isFile()) return true;
+			} catch {
+				// Try the next PATH candidate.
+			}
+		}
+	}
+	return false;
+}