pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/page-target-validation.js

@@ -1,281 +1,90 @@
 import { parseArgvDescriptor } from "./argv-descriptor.js";
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, } from "./argv-grammar.js";
 import { isBrowserIndependentRead, needsManagedSession } from "./command-policy.js";
-import { isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 import { detectConfirmationRequired } from "./results/confirmation.js";
-import { parseBatchCommandArgument, parseUserBatchStdin } from "./orchestration/batch-stdin.js";
-const UNVERIFIED_PAGE_MESSAGE = "The active page became unverified after a tab, attachment, history, script, or state-load transition. Run get url or navigate explicitly before page-content inspection.";
-const BATCH_UNVERIFIED_PAGE_MESSAGE = `${UNVERIFIED_PAGE_MESSAGE} In a batch, put get url after the transition before later content steps, or split the batch at that boundary.`;
-const UNSAFE_BATCH_ARGUMENT_MESSAGE = "Batch command arguments could not be inspected. Use batch stdin JSON command arrays instead.";
-const NESTED_BATCH_ARGUMENT_MESSAGE = "Nested batch commands are not supported. Flatten the batch steps instead.";
-const NON_BAIL_BATCH_NAVIGATION_MESSAGE = "Batches that change or re-verify the page target before page-content access must use exact batch --bail so a failed step cannot act on an unverified or prior page.";
-const MAX_NON_BAIL_BATCH_PAGE_STATES = 64;
-const EXPLICIT_NAVIGATION_COMMANDS = new Set(["a11y", "goto", "navigate", "open", "pushstate", "visit", "vitals", "web-vitals"]);
-const POSITIONAL_VALUE_FLAGS = new Set([...VALUE_FLAGS, "--llms"]);
-function getPositionalOperands(commandTokens) {
-    const values = [];
-    for (let index = 1; index < commandTokens.length; index += 1) {
-        const token = commandTokens[index];
-        if (!token || (token.includes("=") && token.startsWith("-")))
-            continue;
-        if (POSITIONAL_VALUE_FLAGS.has(token)) {
-            index += 1;
-            continue;
-        }
-        if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(token)) {
-            if (["true", "false"].includes(commandTokens[index + 1] ?? ""))
-                index += 1;
-            continue;
-        }
-        if (!token.startsWith("-") || token.includes("/") || token.includes("\\"))
-            values.push(token);
-    }
-    return values;
-}
-export function getExplicitNavigationTarget(args) {
-    const descriptor = parseArgvDescriptor(args);
-    const positionals = getPositionalOperands(descriptor.upstreamCommandTokens);
-    if (EXPLICIT_NAVIGATION_COMMANDS.has(descriptor.commandInfo.command ?? ""))
-        return positionals[0];
-    if (descriptor.commandInfo.command === "tab" && descriptor.commandInfo.subcommand === "new")
-        return positionals[1];
-    if (descriptor.commandInfo.command === "window" && descriptor.commandInfo.subcommand === "new")
-        return "about:blank";
-    if (descriptor.commandInfo.command === "diff" && descriptor.commandInfo.subcommand === "url")
-        return descriptor.upstreamCommandTokens[3];
-    return undefined;
-}
-function getResultingExplicitNavigationTarget(args, currentPageUrl) {
-    const target = getExplicitNavigationTarget(args);
-    if (target === undefined)
-        return undefined;
-    if (parseArgvDescriptor(args).commandInfo.command !== "pushstate")
-        return target;
-    try {
-        return new URL(target).href;
-    }
-    catch {
-        if (!currentPageUrl)
-            return undefined;
-        try {
-            return new URL(target, currentPageUrl).href;
-        }
-        catch {
-            return undefined;
-        }
-    }
-}
-function getBatchCommandSteps(args, stdin) {
-    const descriptor = parseArgvDescriptor(args);
-    if (descriptor.commandInfo.command !== "batch")
-        return { steps: [] };
-    const argumentCommands = descriptor.upstreamCommandTokens.slice(1).filter((command) => command !== "--bail");
-    const steps = [];
-    if (argumentCommands.length > 0) {
-        for (const command of argumentCommands) {
-            const parsed = parseBatchCommandArgument(command);
-            if (parsed.error || parsed.step === undefined)
-                return { error: parsed.error ?? UNSAFE_BATCH_ARGUMENT_MESSAGE, steps: [] };
-            if (parseArgvDescriptor(parsed.step).commandInfo.command === "batch")
-                return { error: NESTED_BATCH_ARGUMENT_MESSAGE, steps: [] };
-            steps.push(parsed.step);
-        }
-        return { steps };
-    }
-    const parsedStdin = parseUserBatchStdin(stdin);
-    if (parsedStdin.error)
-        return { error: parsedStdin.error, steps: [] };
-    for (const step of parsedStdin.steps ?? []) {
-        if (step.length === 0)
-            continue;
-        if (parseArgvDescriptor(step).commandInfo.command === "batch")
-            return { error: NESTED_BATCH_ARGUMENT_MESSAGE, steps: [] };
-        steps.push(step);
-    }
-    return { steps };
-}
-function batchBailsOnFirstError(args) {
-    const descriptor = parseArgvDescriptor(args);
-    return descriptor.commandInfo.command === "batch" && descriptor.upstreamCommandTokens.slice(1).includes("--bail");
-}
-function commandMayChangePageTarget(args, trustedBatchTabSelection) {
-    const descriptor = parseArgvDescriptor(args);
-    return getExplicitNavigationTarget(args) !== undefined
-        || (isUnverifiedPageTransitionCommand(descriptor.commandInfo.command, descriptor.commandInfo.subcommand)
-            && !(trustedBatchTabSelection && descriptor.commandInfo.command === "tab"));
-}
-function commandVerifiesPageTarget(args) {
-    const { command, subcommand } = parseArgvDescriptor(args).commandInfo;
-    return command === "get" && subcommand === "url";
-}
-function deduplicatePossibleBatchPageStates(states) {
-    const deduplicated = new Map();
-    for (const state of states) {
-        const key = `${state.pageUrlUnknown ? "unknown" : "known"}\0${state.currentPageUrl ?? ""}`;
-        const existing = deduplicated.get(key);
-        if (!existing)
-            deduplicated.set(key, state);
-        else
-            existing.retainedAfterFailedNavigation ||= state.retainedAfterFailedNavigation;
-    }
-    return [...deduplicated.values()];
-}
+import { getBatchCommandSteps, validateBatchPageTargets, UNSAFE_BATCH_ARGUMENT_MESSAGE, NESTED_BATCH_ARGUMENT_MESSAGE, } from "./page-target-batch.js";
+import { UNVERIFIED_PAGE_MESSAGE, BATCH_UNVERIFIED_PAGE_MESSAGE, NON_BAIL_BATCH_NAVIGATION_MESSAGE, getUnverifiedPageError, isRecoveringPageTransitionCommand, } from "./page-target-guards.js";
+import { commandMayChangePageTarget, getResultingPageState, } from "./page-target-navigation.js";
+export { getExplicitNavigationTarget } from "./page-target-navigation.js";
 export function commandRequiresLivePageVerification(args, stdin) {
-    const descriptor = parseArgvDescriptor(args);
-    if (descriptor.commandInfo.command === "eval")
+    const { command } = parseArgvDescriptor(args).commandInfo;
+    if (command === "eval") {
         return true;
-    if (descriptor.commandInfo.command !== "batch")
-        return false;
-    const batch = getBatchCommandSteps(args, stdin);
-    return batch.error === undefined && batch.steps.some((step) => commandRequiresLivePageVerification(step));
-}
-function getResultingPageState(options) {
-    const descriptor = parseArgvDescriptor(options.args);
-    if (descriptor.commandInfo.command === "get" && descriptor.commandInfo.subcommand === "url") {
-        return { currentPageUrl: options.currentPageUrl, pageUrlUnknown: false };
     }
-    const rawExplicitTarget = getExplicitNavigationTarget(options.args);
-    const explicitTarget = getResultingExplicitNavigationTarget(options.args, options.currentPageUrl);
-    if (explicitTarget !== undefined)
-        return { currentPageUrl: explicitTarget, pageUrlUnknown: false };
-    if (rawExplicitTarget !== undefined)
-        return { pageUrlUnknown: true };
-    if (isUnverifiedPageTransitionCommand(descriptor.commandInfo.command, descriptor.commandInfo.subcommand)) {
-        return options.trustedBatchTabSelection && descriptor.commandInfo.command === "tab"
-            ? { currentPageUrl: options.currentPageUrl, pageUrlUnknown: options.pageUrlUnknown }
-            : { pageUrlUnknown: true };
+    if (command !== "batch") {
+        return false;
     }
-    return { currentPageUrl: options.currentPageUrl, pageUrlUnknown: options.pageUrlUnknown };
+    const batch = getBatchCommandSteps(args, stdin);
+    return (batch.error === undefined &&
+        batch.steps.some((step) => commandRequiresLivePageVerification(step)));
 }
 export function getResultingPageTargetState(options) {
-    const descriptor = parseArgvDescriptor(options.args);
-    let state = { currentPageUrl: options.currentPageUrl, pageUrlUnknown: options.pageUrlUnknown ?? false };
-    let pageTargetMayHaveChanged = false;
-    if (descriptor.commandInfo.command !== "batch") {
-        pageTargetMayHaveChanged = getExplicitNavigationTarget(options.args) !== undefined
-            || isUnverifiedPageTransitionCommand(descriptor.commandInfo.command, descriptor.commandInfo.subcommand);
-        return { ...getResultingPageState({ ...state, args: options.args, trustedBatchTabSelection: false }), pageTargetMayHaveChanged };
+    let state = {
+        currentPageUrl: options.currentPageUrl,
+        pageUrlUnknown: options.pageUrlUnknown ?? false,
+    };
+    if (parseArgvDescriptor(options.args).commandInfo.command !== "batch") {
+        return {
+            ...getResultingPageState({ ...state, args: options.args, trustedBatchTabSelection: false }),
+            pageTargetMayHaveChanged: commandMayChangePageTarget(options.args, false),
+        };
     }
+    let pageTargetMayHaveChanged = false;
     for (const [index, step] of options.executedBatchSteps.entries()) {
-        const row = Array.isArray(options.batchResults) ? options.batchResults[index] : undefined;
-        if (isRecord(row) && detectConfirmationRequired(row.result))
+        const row = Array.isArray(options.batchResults)
+            ? options.batchResults[index]
+            : undefined;
+        if (isRecord(row) && detectConfirmationRequired(row.result)) {
             continue;
-        const stepDescriptor = parseArgvDescriptor(step);
-        pageTargetMayHaveChanged ||= getExplicitNavigationTarget(step) !== undefined
-            || isUnverifiedPageTransitionCommand(stepDescriptor.commandInfo.command, stepDescriptor.commandInfo.subcommand);
+        }
+        pageTargetMayHaveChanged ||= commandMayChangePageTarget(step, false);
         state = getResultingPageState({ ...state, args: step, trustedBatchTabSelection: false });
     }
     return { ...state, pageTargetMayHaveChanged };
 }
-function isRecoveringPageTransitionCommand(command, subcommand) {
-    return command !== "eval"
-        && !(command === "webmcp" && subcommand === "invoke")
-        && isUnverifiedPageTransitionCommand(command, subcommand);
-}
-function getUnverifiedPageError(options) {
-    const descriptor = parseArgvDescriptor(options.args);
-    if (!options.pageUrlUnknown || !needsManagedSession(descriptor))
-        return undefined;
-    const { command, subcommand } = descriptor.commandInfo;
-    const closesPage = ["close", "exit", "quit"].includes(command ?? "") || (command === "tab" && subcommand === "close");
-    const inspectsTarget = (command === "tab" && subcommand === "list") || (command === "get" && subcommand === "url");
-    const selectsTab = command === "tab" && subcommand !== undefined && !["close", "list", "new"].includes(subcommand);
-    const settlesPendingWebMcp = command === "webmcp" && ["result", "cancel"].includes(subcommand ?? "");
-    const stopsRecording = command === "record" && subcommand === "stop";
-    const handlesBlockingDialog = command === "dialog" && ["status", "accept", "dismiss"].includes(subcommand ?? "");
-    const transitionsPage = options.allowUnverifiedPageTransitions === true && isRecoveringPageTransitionCommand(command, subcommand);
-    const navigatesExplicitly = getExplicitNavigationTarget(options.args) !== undefined;
-    return closesPage || handlesBlockingDialog || inspectsTarget || selectsTab || settlesPendingWebMcp || stopsRecording || transitionsPage || navigatesExplicitly || (options.trustedBatchTabSelection && command === "tab")
-        ? undefined
-        : UNVERIFIED_PAGE_MESSAGE;
-}
 export function getPageTargetValidationError(options) {
     const descriptor = parseArgvDescriptor(options.args);
     const command = descriptor.commandInfo.command;
-    if (isBrowserIndependentRead(descriptor.upstreamCommandTokens, options.stdin))
-        return undefined;
-    if (["close", "exit", "quit"].includes(command ?? ""))
-        return undefined;
-    if (command === "batch") {
-        if (descriptor.upstreamCommandTokens.slice(1).some((token) => token.startsWith("--bail="))) {
-            return "Use exact batch --bail for fail-fast, or omit it to continue after errors. --bail=<value> is a raw command upstream; stdin is ignored when raw batch arguments are present.";
-        }
-        const batch = getBatchCommandSteps(options.args, options.stdin);
-        if (batch.error)
-            return batch.error.startsWith("agent_browser batch stdin") || batch.error === NESTED_BATCH_ARGUMENT_MESSAGE
-                ? batch.error
-                : UNSAFE_BATCH_ARGUMENT_MESSAGE;
-        const bailOnFirstError = batchBailsOnFirstError(options.args);
-        let possibleStates = [{
-                currentPageUrl: options.currentPageUrl,
-                pageUrlUnknown: options.pageUrlUnknown ?? false,
-                retainedAfterFailedNavigation: false,
-            }];
-        for (let index = 0; index < batch.steps.length; index += 1) {
-            const step = batch.steps[index];
-            const trustedBatchTabSelection = options.trustedFirstBatchTabSelection === true && index === 0;
-            let directError;
-            let failedNavigationHazard = false;
-            for (const state of possibleStates) {
-                const error = options.allowFirstBatchConfirmation === true && index === 0 ? undefined : getUnverifiedPageError({
-                    allowUnverifiedPageTransitions: options.allowUnverifiedPageTransitions,
-                    args: step,
-                    pageUrlUnknown: state.pageUrlUnknown,
-                    trustedBatchTabSelection,
-                });
-                if (!error)
-                    continue;
-                if (state.retainedAfterFailedNavigation)
-                    failedNavigationHazard = true;
-                else
-                    directError ??= error;
-            }
-            if (directError)
-                return BATCH_UNVERIFIED_PAGE_MESSAGE;
-            if (failedNavigationHazard)
-                return NON_BAIL_BATCH_NAVIGATION_MESSAGE;
-            const mayChangePageTarget = commandMayChangePageTarget(step, trustedBatchTabSelection);
-            const verifiesPageTarget = commandVerifiesPageTarget(step);
-            const nextStates = [];
-            for (const state of possibleStates) {
-                const successState = getResultingPageState({
-                    args: step,
-                    currentPageUrl: state.currentPageUrl,
-                    pageUrlUnknown: state.pageUrlUnknown,
-                    trustedBatchTabSelection,
-                });
-                if (nextStates.length >= MAX_NON_BAIL_BATCH_PAGE_STATES)
-                    return NON_BAIL_BATCH_NAVIGATION_MESSAGE;
-                nextStates.push({ ...successState, retainedAfterFailedNavigation: mayChangePageTarget || verifiesPageTarget ? false : state.retainedAfterFailedNavigation });
-                if (!bailOnFirstError && (mayChangePageTarget || (verifiesPageTarget && state.pageUrlUnknown))) {
-                    nextStates.push({ ...state, retainedAfterFailedNavigation: true });
-                }
-            }
-            possibleStates = deduplicatePossibleBatchPageStates(nextStates);
-        }
+    if (isBrowserIndependentRead(descriptor.upstreamCommandTokens, options.stdin) ||
+        ["close", "exit", "quit"].includes(command ?? "")) {
         return undefined;
     }
-    return getUnverifiedPageError({
-        allowUnverifiedPageTransitions: options.allowUnverifiedPageTransitions,
-        args: options.args,
-        pageUrlUnknown: options.pageUrlUnknown,
-        trustedBatchTabSelection: options.trustedFirstBatchTabSelection,
-    });
+    if (command !== "batch") {
+        return getUnverifiedPageError({
+            ...options,
+            trustedBatchTabSelection: options.trustedFirstBatchTabSelection,
+        });
+    }
+    const rawArguments = descriptor.upstreamCommandTokens.slice(1);
+    if (rawArguments.some((token) => token.startsWith("--bail="))) {
+        return "Use exact batch --bail for fail-fast, or omit it to continue after errors. --bail=<value> is a raw command upstream; stdin is ignored when raw batch arguments are present.";
+    }
+    const batch = getBatchCommandSteps(options.args, options.stdin);
+    if (batch.error !== undefined && batch.error.length > 0) {
+        return batch.error.startsWith("agent_browser batch stdin") ||
+            batch.error === NESTED_BATCH_ARGUMENT_MESSAGE
+            ? batch.error
+            : UNSAFE_BATCH_ARGUMENT_MESSAGE;
+    }
+    return validateBatchPageTargets(batch.steps, rawArguments.includes("--bail"), options);
 }
 export function getExplicitSessionPageVerificationRequirement(options) {
     const descriptor = parseArgvDescriptor(options.args);
-    if (!needsManagedSession(descriptor, options.stdin))
-        return undefined;
-    if (isRecoveringPageTransitionCommand(descriptor.commandInfo.command, descriptor.commandInfo.subcommand))
+    if (!needsManagedSession(descriptor, options.stdin) ||
+        isRecoveringPageTransitionCommand(descriptor.commandInfo.command, descriptor.commandInfo.subcommand)) {
         return undefined;
+    }
     const validationError = getPageTargetValidationError({
         args: options.args,
         pageUrlUnknown: true,
         stdin: options.stdin,
         allowUnverifiedPageTransitions: true,
     });
-    return validationError === UNVERIFIED_PAGE_MESSAGE || validationError === BATCH_UNVERIFIED_PAGE_MESSAGE || validationError === NON_BAIL_BATCH_NAVIGATION_MESSAGE
+    return [
+        UNVERIFIED_PAGE_MESSAGE,
+        BATCH_UNVERIFIED_PAGE_MESSAGE,
+        NON_BAIL_BATCH_NAVIGATION_MESSAGE,
+    ].includes(validationError ?? "")
         ? UNVERIFIED_PAGE_MESSAGE
         : undefined;
 }

package/dist/extensions/agent-browser/lib/parsing.js

@@ -5,17 +5,26 @@ export function isRecord(value) {
 export function parseRefId(selector) {
     const trimmed = selector.trim();
     const prefixed = trimmed.startsWith("@") || trimmed.startsWith("ref=");
-    const candidate = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+    let candidate = trimmed;
+    if (trimmed.startsWith("@")) {
+        candidate = trimmed.slice(1);
+    }
+    else if (trimmed.startsWith("ref=")) {
+        candidate = trimmed.slice(4);
+    }
     return (prefixed ? /^e\d*$/ : /^e\d+$/).test(candidate) ? candidate : undefined;
 }
 export function parsePositiveInteger(rawValue) {
-    if (typeof rawValue !== "string")
+    if (typeof rawValue !== "string") {
         return undefined;
+    }
     const normalizedValue = rawValue.trim();
-    if (!/^\d+$/.test(normalizedValue))
+    if (!/^\d+$/.test(normalizedValue)) {
         return undefined;
+    }
     const parsedValue = Number(normalizedValue);
-    if (!Number.isSafeInteger(parsedValue) || parsedValue <= 0)
+    if (!Number.isSafeInteger(parsedValue) || parsedValue <= 0) {
         return undefined;
+    }
     return parsedValue;
 }