pi-agent-browser-native 0.2.47 → 0.2.49

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

@@ -0,0 +1,762 @@
+import { copyFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { launchElectronApp } from "../../electron/launch.js";
+import { pathExists } from "../../fs-utils.js";
+import { getCompiledSemanticActionSessionPrefix } from "../../input-modes.js";
+import { tryDirectAnchorDownload } from "./prepare/direct-anchor-download.js";
+import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
+import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
+import { trySnapshotFilter } from "./prepare/snapshot-filter.js";
+import { getWaitAwareProcessTimeoutMs } from "./prepare/wait-timeouts.js";
+import { getPersistentSessionArtifactStore } from "./session-artifacts.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions } from "../../results/recovery-next-actions.js";
+import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
+import { extractRefSnapshotFromData } from "../../session-page-state.js";
+import { buildExecutionPlan, createFreshSessionName, extractCommandTokens, redactInvocationArgs, } from "../../runtime.js";
+import { applyOpenResultTabCorrection, buildManagedSessionOutcome, buildPinnedBatchPlan, buildSessionDetailFields, buildStaleRefPreflight, collectSessionTabSelection, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
+import { parseBatchStdinJsonArray } from "../batch-stdin.js";
+import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
+import { prepareClickDispatchProbe } from "./click-dispatch.js";
+import { collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
+import { getScreenshotPathTokenIndex } from "./artifact-paths.js";
+import { findRequestedArtifactCloseViolation } from "./prompt-guards.js";
+export function normalizeRunInput(input) {
+    const base = { redactedArgs: input.redactedArgs, toolArgs: input.toolArgs, toolStdin: input.toolStdin };
+    switch (input.kind) {
+        case "electron":
+            return { ...base, compiledElectron: input.compiledElectron, redactedCompiledElectron: input.redactedCompiledElectron };
+        case "job":
+            return { ...base, compiledJob: input.compiledJob, redactedCompiledJob: input.redactedCompiledJob };
+        case "networkSourceLookup":
+            return { ...base, compiledNetworkSourceLookup: input.compiledNetworkSourceLookup, redactedCompiledNetworkSourceLookup: input.redactedCompiledNetworkSourceLookup };
+        case "qa":
+            return { ...base, compiledJob: input.compiledJob, compiledQaPreset: input.compiledQaPreset, redactedCompiledJob: input.redactedCompiledJob, redactedCompiledQaPreset: input.redactedCompiledQaPreset };
+        case "semanticAction":
+            return { ...base, compiledSemanticAction: input.compiledSemanticAction, redactedCompiledSemanticAction: input.redactedCompiledSemanticAction };
+        case "sourceLookup":
+            return { ...base, compiledSourceLookup: input.compiledSourceLookup, redactedCompiledSourceLookup: input.redactedCompiledSourceLookup };
+        case "args":
+            return base;
+    }
+}
+export function buildInvocationPreview(effectiveArgs) {
+    const preview = effectiveArgs.join(" ");
+    return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
+}
+function getArtifactParentPathTokenIndex(commandTokens) {
+    if (commandTokens[0] === "download" && commandTokens.length >= 3)
+        return 2;
+    if (commandTokens[0] === "pdf" && commandTokens.length >= 2)
+        return 1;
+    if (commandTokens[0] === "state" && commandTokens[1] === "save" && commandTokens.length >= 3)
+        return 2;
+    if (commandTokens[0] === "wait") {
+        const downloadIndex = commandTokens.findIndex((token) => token === "--download");
+        const pathIndex = downloadIndex >= 0 ? downloadIndex + 1 : -1;
+        if (pathIndex > 0 && typeof commandTokens[pathIndex] === "string" && !commandTokens[pathIndex].startsWith("-"))
+            return pathIndex;
+    }
+    return undefined;
+}
+async function ensureArtifactParentDirectory(commandTokens, cwd) {
+    const pathIndex = getArtifactParentPathTokenIndex(commandTokens);
+    if (pathIndex === undefined)
+        return;
+    const requestedPath = commandTokens[pathIndex];
+    if (!requestedPath)
+        return;
+    await mkdir(dirname(resolve(cwd, requestedPath)), { recursive: true });
+}
+async function normalizeScreenshotPathInTokens(commandTokens, cwd) {
+    const screenshotPathTokenIndex = getScreenshotPathTokenIndex(commandTokens);
+    if (screenshotPathTokenIndex === undefined) {
+        return { tokens: commandTokens };
+    }
+    const requestedPath = commandTokens[screenshotPathTokenIndex];
+    const absolutePath = resolve(cwd, requestedPath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    const tokens = [...commandTokens];
+    tokens[screenshotPathTokenIndex] = absolutePath;
+    const terminatorIndex = tokens.indexOf("--");
+    if (terminatorIndex >= 0) {
+        tokens.splice(terminatorIndex, 1);
+    }
+    return {
+        request: {
+            absolutePath,
+            path: requestedPath,
+        },
+        tokens,
+    };
+}
+async function prepareBatchScreenshotPaths(args, stdin, cwd) {
+    const commandTokens = extractCommandTokens(args);
+    if (commandTokens[0] !== "batch" || stdin === undefined) {
+        return undefined;
+    }
+    const parsed = parseBatchStdinJsonArray(stdin);
+    if (parsed.error || parsed.steps === undefined) {
+        return undefined;
+    }
+    let changed = false;
+    const batchScreenshotPathRequests = [];
+    const preparedSteps = await Promise.all(parsed.steps.map(async (step, index) => {
+        if (!Array.isArray(step) || !step.every((item) => typeof item === "string")) {
+            return step;
+        }
+        await ensureArtifactParentDirectory(step, cwd);
+        if (step[0] !== "screenshot") {
+            return step;
+        }
+        const normalized = await normalizeScreenshotPathInTokens(step, cwd);
+        batchScreenshotPathRequests[index] = normalized.request;
+        if (normalized.request) {
+            changed = true;
+        }
+        return normalized.tokens;
+    }));
+    return changed
+        ? {
+            args,
+            batchScreenshotPathRequests,
+            stdin: JSON.stringify(preparedSteps),
+        }
+        : undefined;
+}
+export async function prepareAgentBrowserArgs(args, stdin, cwd) {
+    const preparedBatch = await prepareBatchScreenshotPaths(args, stdin, cwd);
+    if (preparedBatch) {
+        return preparedBatch;
+    }
+    const commandTokens = extractCommandTokens(args);
+    await ensureArtifactParentDirectory(commandTokens, cwd);
+    const normalized = await normalizeScreenshotPathInTokens(commandTokens, cwd);
+    if (!normalized.request) {
+        return { args };
+    }
+    const commandStartIndex = args.length - commandTokens.length;
+    return {
+        args: [...args.slice(0, commandStartIndex), ...normalized.tokens],
+        screenshotPathRequest: normalized.request,
+    };
+}
+async function repairScreenshotData(options) {
+    const { cwd, data, request } = options;
+    const reportedPath = typeof data.path === "string" ? data.path : undefined;
+    const reportedAbsolutePath = reportedPath ? resolve(cwd, reportedPath) : undefined;
+    let status = await pathExists(request.absolutePath) ? "saved" : "missing";
+    let tempPath;
+    if (reportedAbsolutePath && reportedAbsolutePath !== request.absolutePath) {
+        tempPath = reportedAbsolutePath;
+        if (status === "missing" && await pathExists(reportedAbsolutePath)) {
+            await mkdir(dirname(request.absolutePath), { recursive: true });
+            await copyFile(reportedAbsolutePath, request.absolutePath);
+            status = "repaired-from-temp";
+        }
+    }
+    return {
+        data: {
+            ...data,
+            path: request.absolutePath,
+        },
+        request: {
+            ...request,
+            status,
+            tempPath,
+        },
+    };
+}
+export { repairScreenshotData };
+const DIALOG_COMMAND_PROCESS_TIMEOUT_MS = 5_000;
+const DIALOG_COMMAND_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_DIALOG_PROCESS_TIMEOUT_MS";
+const LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS = 8_000;
+const LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS";
+const DIALOG_TRIGGER_TEXT_PATTERN = /\b(?:alert|confirm|dialog|prompt)\b/i;
+function getPositiveIntegerEnv(name) {
+    const value = process.env[name];
+    if (!value || !/^\d+$/.test(value.trim()))
+        return undefined;
+    const parsed = Number(value.trim());
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function getRefIdsFromDirectCommand(commandTokens) {
+    return [...new Set(getGuardedRefUsage(commandTokens))];
+}
+function commandTextLooksLikeDialogTrigger(commandTokens, refSnapshot) {
+    if (commandTokens.some((token) => DIALOG_TRIGGER_TEXT_PATTERN.test(token)))
+        return true;
+    for (const refId of getRefIdsFromDirectCommand(commandTokens)) {
+        const ref = refSnapshot?.refs?.[refId];
+        if (ref && DIALOG_TRIGGER_TEXT_PATTERN.test(`${ref.role} ${ref.name}`))
+            return true;
+    }
+    return false;
+}
+function getDialogAwareProcessTimeoutMs(commandTokens, refSnapshot, stdin) {
+    const command = commandTokens[0];
+    if (command === "dialog")
+        return getPositiveIntegerEnv(DIALOG_COMMAND_PROCESS_TIMEOUT_ENV) ?? DIALOG_COMMAND_PROCESS_TIMEOUT_MS;
+    if (command === "eval" && typeof stdin === "string" && DIALOG_TRIGGER_TEXT_PATTERN.test(stdin))
+        return getPositiveIntegerEnv(LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_ENV) ?? LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS;
+    if ((command === "click" || command === "tap" || (command === "find" && commandTokens.includes("click"))) && commandTextLooksLikeDialogTrigger(commandTokens, refSnapshot))
+        return getPositiveIntegerEnv(LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_ENV) ?? LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS;
+    return undefined;
+}
+function describeRef(refSnapshot, refId) {
+    const ref = refSnapshot?.refs?.[refId];
+    return ref ? `${ref.role} ${JSON.stringify(ref.name)}` : "not present";
+}
+function getSamePageFreshnessPreflightFailure(options) {
+    if (options.commandTokens[0] === "batch")
+        return undefined;
+    const refIds = getRefIdsFromDirectCommand(options.commandTokens);
+    if (refIds.length === 0)
+        return undefined;
+    const previousUrl = options.previousSnapshot.target?.url;
+    const currentUrl = options.currentSnapshot.target?.url;
+    if (!previousUrl || !currentUrl || previousUrl !== currentUrl || currentUrl === "about:blank")
+        return undefined;
+    const mismatchedRefs = refIds.filter((refId) => {
+        const previous = options.previousSnapshot.refs?.[refId];
+        const current = options.currentSnapshot.refs?.[refId];
+        if (!options.currentSnapshot.refIds.includes(refId))
+            return true;
+        if (!previous || !current)
+            return previous !== current;
+        return previous.role !== current.role || previous.name !== current.name;
+    });
+    if (mismatchedRefs.length === 0)
+        return undefined;
+    const refText = mismatchedRefs.map((refId) => `@${refId}`).join(", ");
+    const evidence = mismatchedRefs.map((refId) => `@${refId}: previous ${describeRef(options.previousSnapshot, refId)}, current ${describeRef(options.currentSnapshot, refId)}`).join("; ");
+    return {
+        message: `Ref ${refText} no longer matches the latest same-page snapshot. The page likely rerendered after the previous snapshot; run snapshot -i and retry with current refs. Evidence: ${evidence}.`,
+        refIds: mismatchedRefs,
+    };
+}
+async function collectSamePageRefFreshnessPreflight(options) {
+    if (!options.previousSnapshot || !options.sessionName || options.commandTokens[0] === "batch" || getRefIdsFromDirectCommand(options.commandTokens).length === 0)
+        return undefined;
+    const previousUrl = options.previousSnapshot.target?.url;
+    const currentTargetUrl = options.currentTarget?.url;
+    if (currentTargetUrl === "about:blank" || (previousUrl && currentTargetUrl && previousUrl !== currentTargetUrl))
+        return undefined;
+    const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal });
+    const currentSnapshot = extractRefSnapshotFromData(snapshotData);
+    if (!currentSnapshot)
+        return undefined;
+    const snapshotWithTarget = { ...currentSnapshot, target: currentSnapshot.target ?? options.currentTarget };
+    const mismatch = getSamePageFreshnessPreflightFailure({ commandTokens: options.commandTokens, currentSnapshot: snapshotWithTarget, previousSnapshot: options.previousSnapshot });
+    if (!mismatch)
+        return undefined;
+    return { message: mismatch.message, refIds: mismatch.refIds, snapshot: snapshotWithTarget };
+}
+function isPasswordStdinAuthSave(options) {
+    return options.command === "auth" && options.commandTokens[1] === "save" && options.commandTokens.includes("--password-stdin");
+}
+export function getExactSensitiveStdinValues(options) {
+    if (options.stdin === undefined || !isPasswordStdinAuthSave(options)) {
+        return [];
+    }
+    return [...new Set([options.stdin, options.stdin.trimEnd(), options.stdin.trim()].filter((value) => value.length > 0))];
+}
+export function validateStdinCommandContract(options) {
+    if (options.stdin === undefined) {
+        return undefined;
+    }
+    if (options.command === "batch") {
+        return undefined;
+    }
+    if (options.command === "eval" && options.commandTokens.includes("--stdin")) {
+        return undefined;
+    }
+    if (isPasswordStdinAuthSave(options)) {
+        return undefined;
+    }
+    const commandLabel = options.command ? `\`${options.command}\`` : "the requested command";
+    return `agent_browser stdin is only supported for \`batch\`, \`eval --stdin\`, and \`auth save --password-stdin\`; remove stdin from ${commandLabel} or use one of those command forms.`;
+}
+export async function resolveSemanticActionVisibleRefArgs(options) {
+    if (!options.compiled || !options.sessionName || options.compiled.locator !== "role" || !["check", "click", "fill"].includes(options.compiled.action))
+        return undefined;
+    const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal });
+    const resolution = resolveVisibleRefActionFromSnapshot({ allowFill: true, compiledAction: options.compiled, snapshotData });
+    if (!resolution)
+        return undefined;
+    return { args: [...getCompiledSemanticActionSessionPrefix(options.compiled), ...resolution.args], snapshot: resolution.snapshot };
+}
+export async function prepareBrowserRun(options) {
+    const { cwd, implicitSessionIdleTimeoutMs, onUpdate, params, signal, state } = options;
+    const { sessionPageState, traceOwners, managedSessionBaseName, ephemeralSessionSeed } = state;
+    let freshSessionOrdinal = state.freshSessionOrdinal;
+    const { compiledElectron, compiledJob, compiledNetworkSourceLookup, compiledQaPreset, compiledSemanticAction, compiledSourceLookup, redactedArgs, redactedCompiledElectron, redactedCompiledJob, redactedCompiledNetworkSourceLookup, redactedCompiledQaPreset, redactedCompiledSemanticAction, redactedCompiledSourceLookup, toolArgs, toolStdin, } = normalizeRunInput(options.input);
+    let runtimeToolArgs = toolArgs;
+    let runtimeToolStdin = toolStdin;
+    let electronLaunch;
+    const sessionMode = compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto";
+    const freshSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1);
+    if (compiledElectron?.action === "launch") {
+        const launchResult = await launchElectronApp(compiledElectron);
+        if (!launchResult.ok) {
+            const managedSessionOutcome = buildManagedSessionOutcome({
+                activeAfter: state.managedSessionActive,
+                activeBefore: state.managedSessionActive,
+                attemptedSessionName: freshSessionName,
+                command: "connect",
+                currentSessionName: state.managedSessionName,
+                previousSessionName: state.managedSessionName,
+                sessionMode: "fresh",
+                succeeded: false,
+            });
+            return { kind: "early-result", result: buildElectronHostFailureResult({
+                    compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                    errorText: launchResult.failure.error,
+                    failureCategory: getElectronLaunchFailureCategory(launchResult.failure),
+                    launchFailure: launchResult.failure,
+                    managedSessionOutcome,
+                    status: launchResult.failure.reason,
+                }) };
+        }
+        electronLaunch = launchResult.value;
+        runtimeToolArgs = ["connect", electronLaunch.connectArg];
+        runtimeToolStdin = undefined;
+    }
+    const preparedArgs = await prepareAgentBrowserArgs(runtimeToolArgs, runtimeToolStdin, cwd);
+    const userRequestedJson = runtimeToolArgs.includes("--json");
+    let executionPlan = buildExecutionPlan(preparedArgs.args, {
+        freshSessionName,
+        managedSessionActive: state.managedSessionActive,
+        managedSessionName: state.managedSessionName,
+        sessionMode,
+    });
+    let semanticActionVisibleRefResolution;
+    if (!executionPlan.validationError && executionPlan.managedSessionName !== freshSessionName) {
+        semanticActionVisibleRefResolution = await resolveSemanticActionVisibleRefArgs({
+            compiled: compiledSemanticAction,
+            cwd,
+            sessionName: executionPlan.sessionName,
+            signal,
+        });
+        if (semanticActionVisibleRefResolution) {
+            executionPlan = buildExecutionPlan(semanticActionVisibleRefResolution.args, {
+                freshSessionName,
+                managedSessionActive: state.managedSessionActive,
+                managedSessionName: state.managedSessionName,
+                sessionMode,
+            });
+        }
+    }
+    const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
+    const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
+    const compatibilityWorkaround = executionPlan.compatibilityWorkaround;
+    const statePatch = executionPlan.managedSessionName === freshSessionName
+        ? { freshSessionOrdinal: freshSessionOrdinal + 1 }
+        : {};
+    if (executionPlan.managedSessionName === freshSessionName) {
+        freshSessionOrdinal += 1;
+    }
+    if (executionPlan.validationError) {
+        return { kind: "early-result", statePatch, result: {
+                content: [{ type: "text", text: executionPlan.validationError }],
+                details: {
+                    args: redactedArgs,
+                    compiledElectron: redactedCompiledElectron,
+                    compiledJob: redactedCompiledJob,
+                    compiledQaPreset: redactedCompiledQaPreset,
+                    compiledSourceLookup: redactedCompiledSourceLookup,
+                    compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
+                    invalidValueFlag: executionPlan.invalidValueFlag,
+                    sessionMode,
+                    sessionRecoveryHint: redactedRecoveryHint,
+                    startupScopedFlags: executionPlan.startupScopedFlags,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, command: executionPlan.commandInfo.command, errorText: executionPlan.validationError, succeeded: false, validationError: executionPlan.validationError }),
+                    validationError: executionPlan.validationError,
+                },
+                isError: true,
+            } };
+    }
+    const commandTokens = semanticActionVisibleRefResolution ? extractCommandTokens(semanticActionVisibleRefResolution.args) : extractCommandTokens(preparedArgs.args);
+    const exactSensitiveValues = getExactSensitiveStdinValues({
+        command: executionPlan.commandInfo.command,
+        commandTokens,
+        stdin: runtimeToolStdin,
+    });
+    const traceOwnerGuardMessage = getTraceOwnerGuardMessage({
+        command: executionPlan.commandInfo.command,
+        sessionName: executionPlan.sessionName,
+        subcommand: executionPlan.commandInfo.subcommand,
+        traceOwners,
+    });
+    if (traceOwnerGuardMessage) {
+        return { kind: "early-result", statePatch, result: {
+                content: [{ type: "text", text: traceOwnerGuardMessage }],
+                details: {
+                    args: redactedArgs,
+                    command: executionPlan.commandInfo.command,
+                    compatibilityWorkaround,
+                    effectiveArgs: redactedEffectiveArgs,
+                    sessionMode,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: traceOwnerGuardMessage, succeeded: false, validationError: traceOwnerGuardMessage }),
+                    validationError: traceOwnerGuardMessage,
+                    ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                },
+                isError: true,
+            } };
+    }
+    const stdinValidationError = validateStdinCommandContract({
+        command: executionPlan.commandInfo.command,
+        commandTokens,
+        stdin: runtimeToolStdin,
+    });
+    if (stdinValidationError) {
+        return { kind: "early-result", statePatch, result: {
+                content: [{ type: "text", text: stdinValidationError }],
+                details: {
+                    args: redactedArgs,
+                    command: executionPlan.commandInfo.command,
+                    compatibilityWorkaround,
+                    effectiveArgs: redactedEffectiveArgs,
+                    sessionMode,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: stdinValidationError, succeeded: false, validationError: stdinValidationError }),
+                    validationError: stdinValidationError,
+                    ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                },
+                isError: true,
+            } };
+    }
+    const priorSessionPageState = sessionPageState.get(executionPlan.sessionName);
+    const priorSessionTabTarget = priorSessionPageState.tabTarget;
+    const sessionTabPinningReason = priorSessionPageState.pinningReason;
+    const priorRefSnapshotState = priorSessionPageState.refSnapshot;
+    const priorRefSnapshotInvalidation = priorSessionPageState.refSnapshotInvalidation;
+    const resolvedSemanticActionRefSnapshot = semanticActionVisibleRefResolution?.snapshot
+        ? { ...semanticActionVisibleRefResolution.snapshot, target: semanticActionVisibleRefResolution.snapshot.target ?? priorSessionTabTarget }
+        : undefined;
+    const promptRefSnapshot = resolvedSemanticActionRefSnapshot ?? priorRefSnapshotState;
+    const requestedArtifactCloseViolation = await findRequestedArtifactCloseViolation({ artifactManifest: state.artifactManifest, command: executionPlan.commandInfo.command, cwd, promptPolicy: options.promptPolicy });
+    if (requestedArtifactCloseViolation) {
+        return { kind: "early-result", statePatch, result: {
+                content: [{ type: "text", text: requestedArtifactCloseViolation.message }],
+                details: {
+                    args: redactedArgs,
+                    command: executionPlan.commandInfo.command,
+                    compatibilityWorkaround,
+                    effectiveArgs: redactedEffectiveArgs,
+                    promptGuard: requestedArtifactCloseViolation,
+                    sessionMode,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: requestedArtifactCloseViolation.message, failureCategory: "policy-blocked", succeeded: false, validationError: requestedArtifactCloseViolation.message }),
+                    validationError: requestedArtifactCloseViolation.message,
+                    ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                },
+                isError: true,
+            } };
+    }
+    const staleRefPreflight = buildStaleRefPreflight({
+        commandTokens,
+        currentTarget: priorSessionTabTarget,
+        refSnapshot: resolvedSemanticActionRefSnapshot ?? priorRefSnapshotState,
+        refSnapshotInvalidation: resolvedSemanticActionRefSnapshot ? undefined : priorRefSnapshotInvalidation,
+        stdin: runtimeToolStdin,
+    });
+    if (staleRefPreflight) {
+        return { kind: "early-result", statePatch, result: {
+                content: [{ type: "text", text: staleRefPreflight.message }],
+                details: {
+                    args: redactedArgs,
+                    command: executionPlan.commandInfo.command,
+                    compatibilityWorkaround,
+                    effectiveArgs: redactedEffectiveArgs,
+                    nextActions: buildSessionAwareStaleRefNextActions(executionPlan.sessionName),
+                    refIds: staleRefPreflight.refIds,
+                    refSnapshot: staleRefPreflight.snapshot,
+                    refSnapshotInvalidation: staleRefPreflight.snapshotInvalidation,
+                    sessionMode,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: staleRefPreflight.message, failureCategory: "stale-ref", succeeded: false }),
+                    ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                },
+                isError: true,
+            } };
+    }
+    const samePageRefFreshnessPreflight = await collectSamePageRefFreshnessPreflight({
+        commandTokens,
+        cwd,
+        currentTarget: priorSessionTabTarget,
+        previousSnapshot: resolvedSemanticActionRefSnapshot ? undefined : priorRefSnapshotState,
+        sessionName: executionPlan.sessionName,
+        signal,
+    });
+    if (samePageRefFreshnessPreflight) {
+        if (samePageRefFreshnessPreflight.snapshot && executionPlan.sessionName) {
+            sessionPageState.applyRefSnapshot({ fallbackTarget: priorSessionTabTarget, sessionName: executionPlan.sessionName, snapshot: samePageRefFreshnessPreflight.snapshot, update: options.sessionPageStateUpdate });
+        }
+        return { kind: "early-result", statePatch, result: {
+                content: [{ type: "text", text: samePageRefFreshnessPreflight.message }],
+                details: {
+                    args: redactedArgs,
+                    command: executionPlan.commandInfo.command,
+                    compatibilityWorkaround,
+                    effectiveArgs: redactedEffectiveArgs,
+                    nextActions: buildSessionAwareStaleRefNextActions(executionPlan.sessionName),
+                    refIds: samePageRefFreshnessPreflight.refIds,
+                    refSnapshot: samePageRefFreshnessPreflight.snapshot,
+                    sessionMode,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: samePageRefFreshnessPreflight.message, failureCategory: "stale-ref", succeeded: false }),
+                    ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                },
+                isError: true,
+            } };
+    }
+    if (compiledQaPreset?.checks.attached) {
+        const qaAttachedPrecondition = await validateQaAttachedPrecondition({
+            cwd,
+            sessionName: executionPlan.sessionName,
+            signal,
+        });
+        if (qaAttachedPrecondition) {
+            return { kind: "early-result", statePatch, result: {
+                    content: [{ type: "text", text: qaAttachedPrecondition.error }],
+                    details: {
+                        args: redactedArgs,
+                        compiledQaPreset: redactedCompiledQaPreset,
+                        compatibilityWorkaround,
+                        effectiveArgs: redactedEffectiveArgs,
+                        nextActions: qaAttachedPrecondition.nextActions,
+                        sessionMode,
+                        ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: qaAttachedPrecondition.error, succeeded: false, validationError: qaAttachedPrecondition.error }),
+                        validationError: qaAttachedPrecondition.error,
+                        ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                    },
+                    isError: true,
+                } };
+        }
+    }
+    const persistentArtifactStore = getPersistentSessionArtifactStore(options.ctx);
+    const snapshotFilter = await trySnapshotFilter({
+        artifactManifest: state.artifactManifest,
+        commandTokens,
+        compatibilityWorkaround,
+        cwd,
+        effectiveArgs: redactedEffectiveArgs,
+        persistentArtifactStore,
+        previousRefSnapshot: priorRefSnapshotState,
+        redactedArgs,
+        sessionMode,
+        sessionName: executionPlan.sessionName,
+        sessionPageState,
+        sessionPageStateUpdate: options.sessionPageStateUpdate,
+        signal,
+        usedImplicitSession: executionPlan.usedImplicitSession,
+    });
+    if (snapshotFilter)
+        return { kind: "early-result", statePatch: { ...statePatch, artifactManifest: snapshotFilter.artifactManifest ?? statePatch.artifactManifest }, result: snapshotFilter.result };
+    const networkRequestsPageFilter = await tryNetworkRequestsPageFilter({
+        commandTokens,
+        compatibilityWorkaround,
+        cwd,
+        effectiveArgs: redactedEffectiveArgs,
+        redactedArgs,
+        sessionMode,
+        sessionName: executionPlan.sessionName,
+        signal,
+        usedImplicitSession: executionPlan.usedImplicitSession,
+    });
+    if (networkRequestsPageFilter)
+        return { kind: "early-result", statePatch, result: networkRequestsPageFilter };
+    const containerScroll = await tryContainerScroll({
+        commandTokens,
+        compatibilityWorkaround,
+        cwd,
+        effectiveArgs: redactedEffectiveArgs,
+        redactedArgs,
+        sessionMode,
+        sessionName: executionPlan.sessionName,
+        signal,
+        usedImplicitSession: executionPlan.usedImplicitSession,
+    });
+    if (containerScroll)
+        return { kind: "early-result", statePatch, result: containerScroll };
+    const pageScrollTo = await tryPageScrollTo({
+        commandTokens,
+        compatibilityWorkaround,
+        cwd,
+        effectiveArgs: redactedEffectiveArgs,
+        redactedArgs,
+        sessionMode,
+        sessionName: executionPlan.sessionName,
+        signal,
+        usedImplicitSession: executionPlan.usedImplicitSession,
+    });
+    if (pageScrollTo)
+        return { kind: "early-result", statePatch, result: pageScrollTo };
+    const directAnchorDownload = await tryDirectAnchorDownload({
+        artifactManifest: state.artifactManifest,
+        commandTokens,
+        compatibilityWorkaround,
+        cwd,
+        effectiveArgs: redactedEffectiveArgs,
+        redactedArgs,
+        sessionMode,
+        sessionName: executionPlan.sessionName,
+        signal,
+        usedImplicitSession: executionPlan.usedImplicitSession,
+    });
+    if (directAnchorDownload)
+        return { kind: "early-result", statePatch: { ...statePatch, artifactManifest: directAnchorDownload.artifactManifest ?? statePatch.artifactManifest }, result: directAnchorDownload.result };
+    let pinnedBatchUnwrapMode;
+    let includePinnedNavigationSummary = false;
+    let sessionTabCorrection;
+    let processArgs = executionPlan.effectiveArgs;
+    let processStdin = preparedArgs.stdin ?? runtimeToolStdin;
+    if (priorSessionTabTarget &&
+        shouldPinSessionTabForCommand({
+            command: executionPlan.commandInfo.command,
+            commandTokens,
+            pinningRequired: sessionTabPinningReason !== undefined,
+            sessionName: executionPlan.sessionName,
+            stdin: runtimeToolStdin,
+        })) {
+        const plannedSessionTabSelection = await collectSessionTabSelection({
+            cwd,
+            sessionName: executionPlan.sessionName,
+            signal,
+            target: priorSessionTabTarget,
+        });
+        if (plannedSessionTabSelection && executionPlan.sessionName) {
+            if (executionPlan.commandInfo.command === "eval" && runtimeToolStdin !== undefined) {
+                const appliedSessionTabSelection = await applyOpenResultTabCorrection({
+                    correction: plannedSessionTabSelection,
+                    cwd,
+                    sessionName: executionPlan.sessionName,
+                    signal,
+                });
+                if (!appliedSessionTabSelection) {
+                    const error = "agent-browser could not re-select the intended tab before running the command.";
+                    return { kind: "early-result", statePatch, result: {
+                            content: [{ type: "text", text: error }],
+                            details: {
+                                args: redactedArgs,
+                                command: executionPlan.commandInfo.command,
+                                compatibilityWorkaround,
+                                effectiveArgs: redactedEffectiveArgs,
+                                sessionMode,
+                                sessionTabCorrection: plannedSessionTabSelection,
+                                ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: error, failureCategory: "tab-drift", succeeded: false, tabDrift: true, validationError: error }),
+                                nextActions: buildSessionTabRecoveryNextActions({
+                                    kind: "tab-drift",
+                                    resultCategory: "failure",
+                                    sessionName: executionPlan.sessionName,
+                                    tabCorrection: plannedSessionTabSelection,
+                                    target: priorSessionTabTarget,
+                                }),
+                                validationError: error,
+                                ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                            },
+                            isError: true,
+                        } };
+                }
+                sessionTabCorrection = appliedSessionTabSelection;
+            }
+            else {
+                const pinnedBatchPlan = buildPinnedBatchPlan({
+                    command: executionPlan.commandInfo.command,
+                    commandTokens,
+                    selectedTab: plannedSessionTabSelection.selectedTab,
+                    stdin: runtimeToolStdin,
+                });
+                if (pinnedBatchPlan && "error" in pinnedBatchPlan) {
+                    return { kind: "early-result", statePatch, result: {
+                            content: [{ type: "text", text: pinnedBatchPlan.error }],
+                            details: {
+                                args: redactedArgs,
+                                command: executionPlan.commandInfo.command,
+                                compatibilityWorkaround,
+                                effectiveArgs: redactedEffectiveArgs,
+                                sessionMode,
+                                sessionTabCorrection: plannedSessionTabSelection,
+                                ...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: pinnedBatchPlan.error, failureCategory: "tab-drift", succeeded: false, tabDrift: true, validationError: pinnedBatchPlan.error }),
+                                nextActions: buildSessionTabRecoveryNextActions({
+                                    kind: "tab-drift",
+                                    resultCategory: "failure",
+                                    sessionName: executionPlan.sessionName,
+                                    tabCorrection: plannedSessionTabSelection,
+                                    target: priorSessionTabTarget,
+                                }),
+                                validationError: pinnedBatchPlan.error,
+                                ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+                            },
+                            isError: true,
+                        } };
+                }
+                if (pinnedBatchPlan) {
+                    sessionTabCorrection = plannedSessionTabSelection;
+                    processArgs = ["--json", "--session", executionPlan.sessionName, "batch"];
+                    processStdin = JSON.stringify(pinnedBatchPlan.steps);
+                    includePinnedNavigationSummary = pinnedBatchPlan.includeNavigationSummary;
+                    pinnedBatchUnwrapMode = pinnedBatchPlan.unwrapMode;
+                }
+            }
+        }
+    }
+    const clickDispatchProbe = pinnedBatchUnwrapMode === undefined && compiledElectron === undefined
+        ? await prepareClickDispatchProbe({ commandTokens, cwd, refSnapshot: promptRefSnapshot, sessionName: executionPlan.sessionName, signal })
+        : undefined;
+    const processTimeoutMs = options.params.timeoutMs ?? getDialogAwareProcessTimeoutMs(commandTokens, promptRefSnapshot, processStdin) ?? getWaitAwareProcessTimeoutMs(commandTokens, processStdin);
+    const redactedProcessArgs = redactInvocationArgs(processArgs);
+    const shouldProbeScrollNoop = executionPlan.commandInfo.command === "scroll" && executionPlan.startupScopedFlags.length === 0;
+    const scrollPositionBefore = shouldProbeScrollNoop
+        ? await collectScrollPositionSnapshot({ cwd, sessionName: executionPlan.sessionName, signal })
+        : undefined;
+    onUpdate?.({
+        content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(redactedProcessArgs)}` }],
+        details: {
+            compatibilityWorkaround,
+            effectiveArgs: redactedProcessArgs,
+            sessionMode,
+            sessionTabCorrection,
+            ...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+        },
+    });
+    return { kind: "ready", prepared: {
+            commandTokens,
+            compiledElectron,
+            compiledJob,
+            compiledNetworkSourceLookup,
+            compiledQaPreset,
+            compiledSemanticAction,
+            compiledSourceLookup,
+            compatibilityWorkaround,
+            clickDispatchProbe,
+            electronLaunch,
+            exactSensitiveValues,
+            executionPlan,
+            includePinnedNavigationSummary,
+            pinnedBatchUnwrapMode,
+            preparedArgs,
+            priorRefSnapshotState,
+            priorSessionTabTarget,
+            processArgs,
+            processStdin,
+            processTimeoutMs,
+            redactedArgs,
+            redactedCompiledElectron,
+            redactedCompiledJob,
+            redactedCompiledNetworkSourceLookup,
+            redactedCompiledQaPreset,
+            redactedCompiledSemanticAction,
+            redactedCompiledSourceLookup,
+            redactedEffectiveArgs,
+            redactedProcessArgs,
+            redactedRecoveryHint,
+            resolvedSemanticActionRefSnapshot,
+            runtimeToolArgs,
+            runtimeToolStdin,
+            scrollPositionBefore,
+            sessionMode,
+            sessionTabCorrection,
+            sessionTabPinningReason,
+            shouldProbeScrollNoop,
+            statePatch,
+            userRequestedJson,
+        } };
+}