pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-semantic.js

@@ -0,0 +1,121 @@
+import { getExplicitSessionPageVerificationRequirement } from "../../page-target-validation.js";
+import { buildExecutionPlan, extractUpstreamCommandTokens } from "../../runtime.js";
+import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
+import { buildUnsupportedScrollIntoViewRecovery } from "./diagnostics.js";
+import { canResolveSemanticVisibleRef, requiresResolvedSemanticVisibleRef, resolveSemanticActionVisibleRefArgs, } from "./prepare-refs.js";
+import { callerOwnedExplicitSession, requiresLivePageVerification, verifyPreparationLivePage, verifyCommandLivePage, } from "./prepare-page-selection.js";
+import { planHasValidationError, withPlanValidationError } from "./prepare-session-plan.js";
+function semanticLocatorError(request, active) {
+    if (request.selection.executionPlan.managedSessionName === request.freshSessionName) {
+        return "semanticAction select with locator cannot resolve a current @ref in sessionMode fresh. Open the page first, then reuse that session, or pass selector plus value/values.";
+    }
+    return active
+        ? "semanticAction select with locator could not resolve to exactly one current visible combobox/listbox ref. Run snapshot -i and retry with selector or a more specific role/name."
+        : "semanticAction select with locator requires an active browser session so the wrapper can resolve a current @ref; open a page first or pass selector plus value/values.";
+}
+function rebuildSemanticPlan(facts, request, resolution) {
+    return {
+        ...request.selection,
+        executionPlan: buildExecutionPlan(resolution.args, {
+            freshSessionName: request.freshSessionName,
+            managedSessionActive: facts.managedSessionActive,
+            managedSessionCompatibilityWorkaround: facts.managedSessionCompatibilityWorkaround,
+            managedSessionName: facts.managedSessionName,
+            managedSessionNamespace: facts.managedSessionNamespace,
+            sessionMode: request.sessionMode,
+        }),
+    };
+}
+function hasLiveSemanticSession(managedSessionActive, preserveAttachedBrowserSession, routing, selection) {
+    return (managedSessionActive ||
+        selection.page.priorSessionTabTarget !== undefined ||
+        callerOwnedExplicitSession(routing.ownsSession, selection.executionPlan) ||
+        preserveAttachedBrowserSession === true);
+}
+async function currentSemanticRef(process, request) {
+    const { page, executionPlan: plan } = request.selection;
+    return resolveSemanticActionVisibleRefArgs({
+        compiled: request.input.compiledSemanticAction,
+        cwd: process.cwd,
+        namespace: plan.namespace,
+        refSnapshot: page.reuseConfirmedCapture &&
+            page.priorSessionTabTargetUnknown !== true &&
+            !page.priorRefSnapshotInvalidation
+            ? page.priorRefSnapshotState
+            : undefined,
+        sessionName: plan.sessionName,
+        signal: process.signal,
+    });
+}
+function finalizeSemanticResolution(facts, request, active, resolution) {
+    if (resolution) {
+        return rebuildSemanticPlan(facts, request, resolution);
+    }
+    if (!planHasValidationError(request.selection.executionPlan) &&
+        requiresResolvedSemanticVisibleRef(request.input.compiledSemanticAction)) {
+        return {
+            ...request.selection,
+            executionPlan: {
+                ...request.selection.executionPlan,
+                validationError: semanticLocatorError(request, active),
+            },
+        };
+    }
+    return request.selection;
+}
+async function resolveSemantic(process, facts, routing, request) {
+    let selection = request.selection;
+    const active = hasLiveSemanticSession(facts.managedSessionActive, process.preserveAttachedBrowserSession, routing, selection);
+    const mayResolve = selection.executionPlan.managedSessionName !== request.freshSessionName &&
+        active &&
+        canResolveSemanticVisibleRef(request.input.compiledSemanticAction);
+    if (!planHasValidationError(selection.executionPlan) &&
+        mayResolve &&
+        requiresLivePageVerification(process.preserveAttachedBrowserSession, routing, selection)) {
+        selection = await verifyPreparationLivePage(process, selection, {
+            args: ["snapshot", "-i"],
+            requirement: getExplicitSessionPageVerificationRequirement({ args: ["snapshot", "-i"] }),
+        });
+    }
+    let resolution;
+    if (!planHasValidationError(selection.executionPlan) && mayResolve) {
+        resolution = await currentSemanticRef(process, { ...request, selection });
+    }
+    selection = finalizeSemanticResolution(facts, { ...request, selection }, active, resolution);
+    return { selection, resolution };
+}
+export async function prepareSemanticAction(process, facts, routing, request) {
+    const semantic = await resolveSemantic(process, facts, routing, request);
+    let selection = semantic.selection;
+    const commandTokens = extractUpstreamCommandTokens(semantic.resolution ? semantic.resolution.args : request.preparedArgs.args);
+    const scrollRecovery = planHasValidationError(selection.executionPlan) || selection.executionPlan.plainTextInspection
+        ? undefined
+        : [commandTokens, ...getUpstreamEffectiveBatchSteps(commandTokens, request.stdin)]
+            .map((tokens) => buildUnsupportedScrollIntoViewRecovery({
+            commandTokens: tokens,
+            sessionName: selection.executionPlan.sessionName,
+        }))
+            .find((recovery) => recovery !== undefined);
+    if (scrollRecovery) {
+        selection = {
+            ...selection,
+            executionPlan: withPlanValidationError(selection.executionPlan, scrollRecovery.error),
+        };
+    }
+    const snapshot = semantic.resolution?.snapshot;
+    const resolvedSnapshot = snapshot
+        ? { ...snapshot, target: snapshot.target ?? selection.page.priorSessionTabTarget }
+        : undefined;
+    selection = await verifyCommandLivePage(process, routing, selection, {
+        commandTokens,
+        resolvedSnapshot,
+        stdin: request.stdin,
+    });
+    return {
+        selection,
+        commandTokens,
+        resolution: semantic.resolution,
+        resolvedSnapshot,
+        scrollRecovery,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-session-plan.js

@@ -0,0 +1,222 @@
+import { extractExplicitSessionName, getBooleanFlagValue, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace, } from "../../argv-grammar.js";
+import { isCloseCommand } from "../../command-taxonomy.js";
+import { isBrowserIndependentRead } from "../../command-policy.js";
+import { isBrowserIndependentConfirmation, suppressConfirmationPageHelpers, } from "../../read-confirmation.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { getPageTargetValidationError } from "../../page-target-validation.js";
+import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, extractUpstreamCommandTokens, getDefaultHeadlessCompatUserAgent, } from "../../runtime.js";
+import { buildOwnedManagedSessionRestoreContext, resolveExplicitAutosaveInterval, } from "../../managed-session-restore.js";
+import { getRunningHeadedAutosavePolicyChangeError } from "./managed-session-daemon-policy.js";
+import { getSessionContextKey } from "./session-state.js";
+export function withPlanValidationError(plan, error) {
+    return { ...plan, recoveryHint: undefined, validationError: error };
+}
+export function planHasValidationError(plan) {
+    return plan.validationError !== undefined && plan.validationError.length > 0;
+}
+function getIdleTimeoutMismatch(args, configuredValue) {
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== "--idle-timeout") {
+            continue;
+        }
+        const requestedToken = args.at(++index);
+        if (requestedToken === undefined ||
+            requestedToken === "" ||
+            !/^\d+$/.test(requestedToken) ||
+            Number(requestedToken) === Number(configuredValue)) {
+            continue;
+        }
+        return `--idle-timeout ${requestedToken} conflicts with this Pi process's managed-session idle timeout (${configuredValue} ms). Restart Pi with PI_AGENT_BROWSER_IMPLICIT_SESSION_IDLE_TIMEOUT_MS=${requestedToken} and omit --idle-timeout; changing the launch value for one call can restart the upstream browser and discard the active tab.`;
+    }
+    return undefined;
+}
+function validatePlannedPage(page, plan, request) {
+    if (request.hasReadConfirmation && plan.commandInfo.command !== "batch") {
+        return plan;
+    }
+    const error = getPageTargetValidationError({
+        allowFirstBatchConfirmation: request.hasReadConfirmation,
+        args: plan.effectiveArgs,
+        currentPageUrl: page.tabTarget?.url,
+        pageUrlUnknown: page.tabTargetUnknown === true,
+        stdin: request.stdin,
+    });
+    return !planHasValidationError(plan) && error !== undefined && error !== ""
+        ? withPlanValidationError(plan, error)
+        : plan;
+}
+function restoreOffCurrentCompatibility(plan, request) {
+    if (request.browserIndependent ||
+        !request.offCurrent ||
+        !canUseHeadlessCompatibilityUserAgent(request.args, getAgentBrowserProcessEnvironment())) {
+        return plan;
+    }
+    const workaround = plan.compatibilityWorkaround ?? request.recorded?.compatibilityWorkaround;
+    if (!workaround) {
+        return plan;
+    }
+    const index = plan.effectiveArgs.indexOf("--user-agent");
+    return {
+        ...plan,
+        compatibilityWorkaround: workaround,
+        effectiveArgs: index < 0
+            ? plan.effectiveArgs
+            : [...plan.effectiveArgs.slice(0, index), ...plan.effectiveArgs.slice(index + 2)],
+    };
+}
+function retainedAutosaveSettings(facts, request) {
+    const retainedDisabled = request.recorded?.headedManagedAutosaveDisabled === true ||
+        (request.targetsCurrent && facts.managedSessionHeadedAutosaveDisabled === true);
+    const retainedInterval = request.recorded?.headedManagedAutosaveInterval ??
+        (request.targetsCurrent ? facts.managedSessionHeadedAutosaveInterval : undefined);
+    return { retainedDisabled, retainedInterval };
+}
+function autosaveSettings(plan, retained, browserIndependent) {
+    const env = getAgentBrowserProcessEnvironment();
+    const explicitInterval = resolveExplicitAutosaveInterval(env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
+    const error = getRunningHeadedAutosavePolicyChangeError(retained.retainedInterval, isCloseCommand(plan.commandInfo.command));
+    const executionPlan = !browserIndependent && !planHasValidationError(plan) && error !== undefined
+        ? withPlanValidationError(plan, error)
+        : plan;
+    const headedLaunch = getBooleanFlagValue(plan.effectiveArgs, "--headed") ??
+        isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_HEADED);
+    return {
+        executionPlan,
+        headedLaunch,
+        ...retained,
+        disabled: retained.retainedDisabled || (explicitInterval === undefined && headedLaunch),
+        interval: retained.retainedInterval ?? (headedLaunch ? (explicitInterval ?? "0") : undefined),
+    };
+}
+function ownedRestoreContext(restoreState, facts, plan, request) {
+    if (request.browserIndependent && !request.recorded && !request.targetsCurrent) {
+        return undefined;
+    }
+    return buildOwnedManagedSessionRestoreContext({
+        args: plan.effectiveArgs,
+        reuseOnly: request.browserIndependent,
+        cwd: request.recorded?.cwd ?? request.cwd,
+        currentManagedSessionName: facts.managedSessionName,
+        currentManagedSessionNamespace: facts.managedSessionNamespace,
+        headedManagedAutosaveDisabled: request.browserIndependent
+            ? request.autosave.retainedDisabled
+            : request.autosave.disabled,
+        headedManagedAutosaveInterval: request.browserIndependent
+            ? request.autosave.retainedInterval
+            : request.autosave.interval,
+        managedSessionName: plan.managedSessionName,
+        namespace: plan.namespace,
+        parentEnv: getAgentBrowserProcessEnvironment(),
+        recordedOwnedSession: request.recorded,
+        restoreState,
+        sessionName: plan.sessionName,
+        stdin: request.stdin,
+        compatibilityUserAgent: request.compatibilityUserAgentApplied
+            ? request.compatibilityUserAgent
+            : undefined,
+        wrapperInjectedUserAgent: request.compatibilityUserAgentApplied,
+    });
+}
+function validateManagedIdle(facts, plan, request) {
+    const owned = (plan.managedSessionName !== undefined && plan.managedSessionName !== "") ||
+        request.recorded !== undefined ||
+        request.targetsCurrent ||
+        (facts.managedSessionActive && extractExplicitSessionName(request.args) === undefined);
+    if (request.browserIndependent || !owned) {
+        return plan;
+    }
+    const error = getIdleTimeoutMismatch(request.args, request.idleTimeoutMs);
+    return error !== undefined && error !== "" ? withPlanValidationError(plan, error) : plan;
+}
+function prepareNativePlan(pageState, facts, preparedArgs, request) {
+    const env = getAgentBrowserProcessEnvironment();
+    const routed = pageState.findReadConfirmation(preparedArgs.args, resolveAgentBrowserNamespace(preparedArgs.args, env.AGENT_BROWSER_NAMESPACE), request.stdin);
+    const readConfirmation = suppressConfirmationPageHelpers(routed) ? routed : undefined;
+    const independentConfirmation = isBrowserIndependentConfirmation(readConfirmation);
+    let plan = buildExecutionPlan(preparedArgs.args, {
+        freshSessionName: request.freshSessionName,
+        managedSessionActive: facts.managedSessionActive,
+        managedSessionCompatibilityWorkaround: facts.managedSessionCompatibilityWorkaround,
+        managedSessionName: facts.managedSessionName,
+        managedSessionNamespace: facts.managedSessionNamespace,
+        sessionMode: request.sessionMode,
+        stdin: request.stdin,
+        browserIndependentReadConfirmation: independentConfirmation,
+    });
+    const browserIndependent = independentConfirmation ||
+        isBrowserIndependentRead(extractUpstreamCommandTokens(preparedArgs.args), request.stdin) ||
+        (plan.commandInfo.command === "session" && plan.commandInfo.subcommand === "info");
+    plan = validatePlannedPage(pageState.get(getSessionContextKey(plan.sessionName, plan.namespace)), plan, { stdin: request.stdin, hasReadConfirmation: readConfirmation !== undefined });
+    return { plan, browserIndependent, readConfirmation };
+}
+function sessionOwnership(ownedSessions, facts, plan) {
+    const key = getSessionContextKey(plan.sessionName, plan.namespace);
+    const recorded = key !== undefined && key !== "" ? ownedSessions.get(key) : undefined;
+    const targetsCurrent = facts.managedSessionActive &&
+        key === getSessionContextKey(facts.managedSessionName, facts.managedSessionNamespace);
+    return { recorded, targetsCurrent, offCurrent: recorded !== undefined && !targetsCurrent };
+}
+function compatibilityLaunchFacts(plan) {
+    const compatibilityUserAgent = plan.compatibilityWorkaround
+        ? getDefaultHeadlessCompatUserAgent()
+        : undefined;
+    return {
+        compatibilityUserAgent,
+        compatibilityUserAgentApplied: compatibilityUserAgent !== undefined &&
+            plan.effectiveArgs.some((token, index) => token === "--user-agent" && plan.effectiveArgs[index + 1] === compatibilityUserAgent),
+    };
+}
+export function prepareSessionPlan(owners, facts, preparedArgs, request) {
+    const native = prepareNativePlan(owners.pageState, facts, preparedArgs, request);
+    const { browserIndependent, readConfirmation } = native;
+    let plan = native.plan;
+    const { recorded, targetsCurrent, offCurrent } = sessionOwnership(owners.ownedSessions, facts, plan);
+    plan = validateManagedIdle(facts, plan, {
+        idleTimeoutMs: request.idleTimeoutMs,
+        browserIndependent,
+        recorded,
+        targetsCurrent,
+        args: preparedArgs.args,
+    });
+    const offCurrentLaunchScopedFlags = offCurrent
+        ? plan.startupScopedFlags.filter((flag) => flag !== "--namespace")
+        : [];
+    const offCurrentCompatibilityUpgrade = offCurrent &&
+        plan.compatibilityWorkaround !== undefined &&
+        recorded?.compatibilityWorkaround === undefined;
+    plan = restoreOffCurrentCompatibility(plan, {
+        offCurrent,
+        browserIndependent,
+        recorded,
+        args: preparedArgs.args,
+    });
+    const { executionPlan: autosavePlan, ...autosave } = autosaveSettings(plan, retainedAutosaveSettings(facts, { recorded, targetsCurrent }), browserIndependent);
+    plan = autosavePlan;
+    const { compatibilityUserAgent, compatibilityUserAgentApplied } = compatibilityLaunchFacts(plan);
+    const ownedManagedSession = ownedRestoreContext(owners.restoreState, facts, plan, {
+        cwd: request.cwd,
+        browserIndependent,
+        recorded,
+        targetsCurrent,
+        autosave,
+        compatibilityUserAgent,
+        compatibilityUserAgentApplied,
+        stdin: request.stdin,
+    });
+    return {
+        plan,
+        session: {
+            browserIndependent,
+            readConfirmation,
+            recordedOwnedSession: recorded,
+            ownedManagedSession,
+            offCurrentLaunchScopedFlags,
+            offCurrentCompatibilityUpgrade,
+            compatibilityUserAgent,
+            compatibilityUserAgentApplied,
+            headedLaunch: autosave.headedLaunch,
+            providerLaunch: plan.startupScopedFlags.some((flag) => flag === "--provider" || flag === "-p") ||
+                getAgentBrowserProcessEnvironment().AGENT_BROWSER_PROVIDER !== undefined,
+        },
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-timeouts.js

@@ -0,0 +1,68 @@
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { getGuardedRefUsage, runSessionCommandData, extractStringResultField, } from "./session-state.js";
+import { commandTimeoutNeedsActivePageUrl, getCommandAwareProcessTimeoutMs, } from "./prepare/wait-timeouts.js";
+const DIALOG_TRIGGER_TEXT_PATTERN = /\b(?:alert|confirm|dialog|prompt)\b/i;
+function getPositiveIntegerEnv(name) {
+    const value = getAgentBrowserProcessEnvironment()[name];
+    if (value === undefined || value === "" || !/^\d+$/.test(value.trim())) {
+        return undefined;
+    }
+    const parsed = Number(value.trim());
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function commandTextLooksLikeDialogTrigger(commandTokens, refSnapshot) {
+    if (commandTokens.some((token) => DIALOG_TRIGGER_TEXT_PATTERN.test(token))) {
+        return true;
+    }
+    for (const refId of new Set(getGuardedRefUsage(commandTokens))) {
+        const ref = refSnapshot?.refs?.[refId];
+        if (ref && DIALOG_TRIGGER_TEXT_PATTERN.test(`${ref.role} ${ref.name}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function likelyDialogTrigger(commandTokens, refSnapshot, stdin) {
+    const command = commandTokens[0];
+    if (command === "eval" && typeof stdin === "string" && DIALOG_TRIGGER_TEXT_PATTERN.test(stdin)) {
+        return true;
+    }
+    const clickable = command === "click" ||
+        command === "tap" ||
+        (command === "find" && commandTokens.includes("click"));
+    return clickable && commandTextLooksLikeDialogTrigger(commandTokens, refSnapshot);
+}
+function getDialogAwareProcessTimeoutMs(commandTokens, refSnapshot, stdin) {
+    if (commandTokens[0] === "dialog") {
+        return getPositiveIntegerEnv("PI_AGENT_BROWSER_DIALOG_PROCESS_TIMEOUT_MS") ?? 5000;
+    }
+    if (likelyDialogTrigger(commandTokens, refSnapshot, stdin)) {
+        return getPositiveIntegerEnv("PI_AGENT_BROWSER_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS") ?? 8000;
+    }
+    return undefined;
+}
+export async function prepareProcessTimeout(process, request) {
+    let pageUrl = request.pageUrl;
+    if (process.timeoutMs === undefined &&
+        pageUrl === undefined &&
+        request.sessionName !== undefined &&
+        request.sessionName !== "" &&
+        commandTimeoutNeedsActivePageUrl(request.commandTokens, request.stdin)) {
+        try {
+            const data = await runSessionCommandData({
+                args: ["get", "url"],
+                cwd: process.cwd,
+                namespace: request.namespace,
+                sessionName: request.sessionName,
+                signal: process.signal,
+            });
+            pageUrl = extractStringResultField(data, "result") ?? extractStringResultField(data, "url");
+        }
+        catch {
+            // Timeout selection is advisory; failed URL inspection retains native defaults.
+        }
+    }
+    return (process.timeoutMs ??
+        getDialogAwareProcessTimeoutMs(request.commandTokens, request.refSnapshot, request.stdin) ??
+        getCommandAwareProcessTimeoutMs(request.commandTokens, request.stdin, pageUrl));
+}