pi-agent-browser-native 0.2.47 → 0.2.49

package/dist/extensions/agent-browser/lib/argv-descriptor.js

@@ -0,0 +1,71 @@
+/**
+ * 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";
+function isBooleanLiteral(token) {
+    const normalized = token?.trim().toLowerCase();
+    return normalized === "true" || normalized === "false";
+}
+export function findCommandStartIndex(args) {
+    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) {
+    const commandStartIndex = findCommandStartIndex(args);
+    return commandStartIndex === undefined ? [] : args.slice(commandStartIndex);
+}
+function getOpenCommandTarget(commandTokens) {
+    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) {
+    const command = commandTokens[0];
+    return {
+        command,
+        subcommand: isOpenNavigationCommand(command) ? getOpenCommandTarget(commandTokens) : commandTokens[1],
+    };
+}
+export function parseCommandInfo(args) {
+    return parseCommandInfoFromTokens(extractCommandTokens(args));
+}
+export function parseArgvDescriptor(args) {
+    const commandTokens = extractCommandTokens(args);
+    return {
+        commandInfo: parseCommandInfoFromTokens(commandTokens),
+        commandTokens,
+    };
+}

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -0,0 +1,121 @@
+/**
+ * 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",
+];
+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",
+];
+export const VALUE_FLAGS = new Set([...GLOBAL_VALUE_FLAGS, ...COMMAND_VALUE_FLAGS]);
+export const PREVALIDATED_VALUE_FLAGS = new Set(GLOBAL_VALUE_FLAGS);
+export const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE = new Set(["--args"]);
+export const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES = 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) {
+    return token.split("=", 1)[0] ?? token;
+}
+export function isNonFlagToken(token) {
+    return typeof token === "string" && !token.startsWith("-");
+}
+export function hasOnlyBooleanFlags(tokens, allowedFlags) {
+    return tokens.every((token) => token.startsWith("-") && allowedFlags.has(getFlagName(token)));
+}
+export function hasOnlyOptionFlags(tokens, allowedBooleanFlags, allowedValueFlags) {
+    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) {
+    return commandTokens.filter((token) => token !== "--json");
+}

package/dist/extensions/agent-browser/lib/bash-guard.js

@@ -0,0 +1,190 @@
+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";
+function isShellAssignmentToken(token) {
+    return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
+}
+function stripOuterQuotes(token) {
+    if (token.length >= 2 && ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'")))) {
+        return token.slice(1, -1);
+    }
+    return token;
+}
+function segmentLaunchesAgentBrowser(tokens) {
+    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) {
+    let currentToken = "";
+    let quoteState;
+    let awaitingHeredocDelimiter;
+    let pendingHeredoc;
+    let pendingHeredocLine = "";
+    let segmentTokens = [];
+    const acceptToken = (token) => {
+        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) {
+    return HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN.test(command);
+}
+function isTruthyEnvValue(value) {
+    return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+async function isPackageDevelopmentCwd(cwd) {
+    try {
+        const packageJson = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+        return packageJson.name === PACKAGE_NAME;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isDirectAgentBrowserBashAllowed(cwd) {
+    return isTruthyEnvValue(process.env[DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV]) || await isPackageDevelopmentCwd(cwd);
+}

package/dist/extensions/agent-browser/lib/command-policy.js

@@ -0,0 +1,85 @@
+/**
+ * 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 { 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();
+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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return !isSessionlessCommand(descriptor.commandTokens);
+}