pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,340 @@
+const ADDITIONAL_COMMAND_TOKENS = [
+    "a11y",
+    "auth",
+    "chat",
+    "clipboard",
+    "confirm",
+    "connect",
+    "dashboard",
+    "deny",
+    "device",
+    "dialog",
+    "diff",
+    "doctor",
+    "errors",
+    "eval",
+    "find",
+    "frame",
+    "get",
+    "highlight",
+    "inspect",
+    "install",
+    "is",
+    "mcp",
+    "plugin",
+    "plugins",
+    "profiles",
+    "profiler",
+    "react",
+    "record",
+    "removeinitscript",
+    "session",
+    "set",
+    "skills",
+    "snapshot",
+    "state",
+    "stream",
+    "trace",
+    "upgrade",
+    "vitals",
+    "wait",
+    "web-vitals",
+    "webmcp",
+    "window",
+];
+const COMMAND_CAPABILITIES = [
+    {
+        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: "diff",
+        guardsPageRefs: true,
+    },
+    {
+        command: "download",
+        eligibleForPageChangeSummary: true,
+        guardsPageRefs: true,
+    },
+    {
+        command: "drag",
+        guardsPageRefs: true,
+        invalidatesBatchRefs: true,
+    },
+    {
+        command: "errors",
+        readOnlyDiagnosticSessionTarget: true,
+    },
+    {
+        command: "eval",
+        invalidatesBatchRefs: true,
+        navigationObservable: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "fill",
+        eligibleForElectronHealthProbe: true,
+        eligibleForPageChangeSummary: true,
+        guardsPageRefs: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "find",
+        eligibleForElectronHealthProbe: true,
+    },
+    {
+        command: "frame",
+        guardsPageRefs: true,
+    },
+    {
+        command: "focus",
+        guardsPageRefs: true,
+    },
+    {
+        command: "forward",
+        eligibleForElectronHealthProbe: true,
+        eligibleForPageChangeSummary: true,
+        invalidatesBatchRefs: true,
+        navigationObservable: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "get",
+        guardsPageRefs: true,
+    },
+    {
+        command: "highlight",
+        guardsPageRefs: true,
+    },
+    {
+        command: "hover",
+        eligibleForPageChangeSummary: true,
+        guardsPageRefs: true,
+        invalidatesBatchRefs: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "is",
+        guardsPageRefs: true,
+    },
+    {
+        command: "keydown",
+        eligibleForElectronHealthProbe: true,
+        eligibleForPageChangeSummary: true,
+        invalidatesBatchRefs: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "keyboard",
+        eligibleForElectronHealthProbe: true,
+        eligibleForPageChangeSummary: true,
+        invalidatesBatchRefs: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "keyup",
+        eligibleForElectronHealthProbe: true,
+        eligibleForPageChangeSummary: true,
+        invalidatesBatchRefs: true,
+        triggersPostMutationSnapshot: true,
+    },
+    {
+        command: "mouse",
+        eligibleForElectronHealthProbe: 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,
+        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: "read",
+        readOnlyDiagnosticSessionTarget: true,
+    },
+    {
+        command: "screenshot",
+        eligibleForPageChangeSummary: true,
+        guardsPageRefs: true,
+    },
+    {
+        command: "scroll",
+        eligibleForPageChangeSummary: true,
+        guardsPageRefs: 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();
+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);
+    }
+}
+const KNOWN_COMMAND_TOKENS = new Set([
+    ...COMMAND_CAPABILITY_BY_NAME.keys(),
+    ...ADDITIONAL_COMMAND_TOKENS,
+]);
+export function isKnownCommandToken(token) {
+    return KNOWN_COMMAND_TOKENS.has(token);
+}
+function getCommandCapability(command) {
+    return command === undefined ? undefined : COMMAND_CAPABILITY_BY_NAME.get(command);
+}
+export function hasCommandCapability(command, capability) {
+    return getCommandCapability(command)?.[capability] === true;
+}

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

@@ -1,136 +1,155 @@
-import { hasOnlyBooleanFlags, hasOnlyOptionFlags, isNonFlagToken, stripSessionlessShapeGlobalFlags } from "./argv-grammar.js";
+import { getExplicitReadUrl } from "./read-command.js";
+export { getExplicitReadUrl } from "./read-command.js";
+import { hasOnlyBooleanFlags, hasOnlyOptionFlags, isNonFlagToken, stripSessionlessShapeGlobalFlags, } from "./argv-grammar.js";
 import { getUpstreamEffectiveBatchSteps } from "./orchestration/batch-stdin.js";
 const SESSIONLESS_AUTH_SUBCOMMANDS = new Set(["save", "list", "show", "delete", "remove"]);
 const PLUGIN_SESSIONLESS_SUBCOMMANDS = new Set(["list", "show", "add", "run"]);
 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 AUTH_SAVE_VALUE_FLAGS = new Set([
+    "--password",
+    "--password-selector",
+    "--submit-selector",
+    "--url",
+    "--username",
+    "--username-selector",
+]);
 const DASHBOARD_VALUE_FLAGS = new Set(["--allowed-origins", "--port"]);
-const DOCTOR_BOOLEAN_FLAGS = new Set(["--fix", "--headed", "--json", "--offline", "--quick", "--webgpu"]);
+const DOCTOR_BOOLEAN_FLAGS = new Set([
+    "--fix",
+    "--headed",
+    "--json",
+    "--offline",
+    "--quick",
+    "--webgpu",
+]);
 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"]);
 const SESSION_ID_VALUE_FLAGS = new Set(["--scope", "--prefix"]);
 function isSessionlessAuthCommand(commandTokens) {
-    const [, subcommand, target, ...rest] = commandTokens;
-    if (!SESSIONLESS_AUTH_SUBCOMMANDS.has(subcommand ?? ""))
+    const subcommand = commandTokens.at(1);
+    const target = commandTokens.at(2);
+    const rest = commandTokens.slice(3);
+    if (!SESSIONLESS_AUTH_SUBCOMMANDS.has(subcommand ?? "")) {
         return false;
-    if (subcommand === "list")
+    }
+    if (subcommand === "list") {
         return target === undefined;
-    if (!isNonFlagToken(target))
+    }
+    if (!isNonFlagToken(target)) {
         return false;
-    if (subcommand === "save")
+    }
+    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 === "stop")
+    if (subcommand === "stop") {
         return rest.length === 0;
+    }
     return hasOnlyOptionFlags(subcommand === "start" ? rest : commandTokens.slice(1), JSON_BOOLEAN_FLAGS, DASHBOARD_VALUE_FLAGS);
 }
+function isSessionlessStateClear(operands) {
+    const firstArg = operands.at(0);
+    const secondArg = operands.at(1);
+    const rest = operands.slice(2);
+    if ((firstArg === "--all" || firstArg === "-a") && secondArg === undefined) {
+        return true;
+    }
+    return (isNonFlagToken(firstArg) &&
+        (secondArg === undefined || (secondArg === "--all" && rest.length === 0)));
+}
 function isSessionlessStateCommand(commandTokens) {
-    const [, subcommand, firstArg, secondArg, ...rest] = commandTokens;
-    if (!STATE_SESSIONLESS_SUBCOMMANDS.has(subcommand ?? ""))
+    const subcommand = commandTokens.at(1);
+    const firstArg = commandTokens.at(2);
+    const secondArg = commandTokens.at(3);
+    const rest = commandTokens.slice(4);
+    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);
+    switch (subcommand) {
+        case undefined:
+            return false;
+        case "list":
+            return firstArg === undefined;
+        case "show":
+            return isNonFlagToken(firstArg) && secondArg === undefined;
+        case "rename":
+            return isNonFlagToken(firstArg) && isNonFlagToken(secondArg) && rest.length === 0;
+        case "clean": {
+            const optionTokens = commandTokens.slice(2);
+            return (optionTokens.length > 0 &&
+                hasOnlyOptionFlags(optionTokens, EMPTY_BOOLEAN_FLAGS, STATE_CLEAN_VALUE_FLAGS));
+        }
+        case "clear":
+            return isSessionlessStateClear(commandTokens.slice(2));
+        default:
+            return false;
+    }
 }
 function isSessionlessPluginCommand(commandTokens) {
-    const [, subcommand] = commandTokens;
-    if (subcommand === undefined)
+    const subcommand = commandTokens.at(1);
+    if (subcommand === undefined) {
         return true;
+    }
     return PLUGIN_SESSIONLESS_SUBCOMMANDS.has(subcommand);
 }
 function isSessionlessSessionCommand(commandTokens) {
     const [, subcommand, ...rest] = commandTokens;
-    if (subcommand === "list" || subcommand === "info")
+    if (subcommand === "list" || subcommand === "info") {
         return rest.length === 0;
-    if (subcommand === "id")
+    }
+    if (subcommand === "id") {
         return hasOnlyOptionFlags(rest, JSON_BOOLEAN_FLAGS, SESSION_ID_VALUE_FLAGS);
+    }
     return false;
 }
 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 === "plugin")
-        return isSessionlessPluginCommand(normalizedTokens);
-    if (command === "mcp")
-        return true;
-    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 isSessionlessSessionCommand(normalizedTokens);
-    if (command === "state")
-        return isSessionlessStateCommand(normalizedTokens);
-    return false;
-}
-// undefined is a valid DOM read; null is invalid native syntax, which must not trigger page helpers.
-export function getExplicitReadUrl(commandTokens) {
-    if (commandTokens[0] !== "read")
-        return undefined;
-    let url;
-    let llms = false;
-    let outline = false;
-    for (let index = 1; index < commandTokens.length; index += 1) {
-        const token = commandTokens[index];
-        if (["--filter", "--llms", "--timeout"].includes(token)) {
-            const value = commandTokens[++index];
-            if (value === undefined)
-                return null;
-            if (token === "--llms") {
-                if (!["index", "full"].includes(value))
-                    return null;
-                llms = true;
-            }
-            if (token === "--timeout" && (!/^\+?\d+$/.test(value) || BigInt(value) === 0n || BigInt(value) > 18446744073709551615n))
-                return null;
-        }
-        else if (["--raw", "--require-md", "--outline", "--json"].includes(token)) {
-            if (token === "--outline")
-                outline = true;
-        }
-        else if (token.startsWith("--") || url !== undefined)
-            return null;
-        else
-            url = token;
+    const command = normalizedTokens.at(0);
+    const subcommand = normalizedTokens.at(1);
+    switch (command) {
+        case undefined:
+            return false;
+        case "skills":
+            return ["list", "get", "path"].includes(subcommand ?? "");
+        case "auth":
+            return isSessionlessAuthCommand(normalizedTokens);
+        case "plugin":
+            return isSessionlessPluginCommand(normalizedTokens);
+        case "mcp":
+            return true;
+        case "dashboard":
+            return isSessionlessDashboardCommand(normalizedTokens);
+        case "device":
+            return normalizedTokens.length === 2 && subcommand === "list";
+        case "doctor":
+            return hasOnlyBooleanFlags(normalizedTokens.slice(1), DOCTOR_BOOLEAN_FLAGS);
+        case "install":
+            return hasOnlyBooleanFlags(normalizedTokens.slice(1), INSTALL_BOOLEAN_FLAGS);
+        case "profiles":
+        case "upgrade":
+            return normalizedTokens.length === 1;
+        case "session":
+            return isSessionlessSessionCommand(normalizedTokens);
+        case "state":
+            return isSessionlessStateCommand(normalizedTokens);
+        default:
+            return false;
     }
-    return llms && outline ? null : url;
 }
 export function isBrowserIndependentRead(commandTokens, stdin) {
-    if (commandTokens[0] !== "batch")
+    if (commandTokens[0] !== "batch") {
         return getExplicitReadUrl(commandTokens) !== undefined;
+    }
     const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
     return steps.length > 0 && steps.every((step) => getExplicitReadUrl(step) !== undefined);
 }
 export function needsManagedSession(descriptor, stdin) {
-    return !isSessionlessCommand(descriptor.upstreamCommandTokens) && !isBrowserIndependentRead(descriptor.upstreamCommandTokens, stdin);
+    return (!isSessionlessCommand(descriptor.upstreamCommandTokens) &&
+        !isBrowserIndependentRead(descriptor.upstreamCommandTokens, stdin));
 }