pi-agent-browser-native 0.9.3 → 0.9.4

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

@@ -0,0 +1,242 @@
+import { prepareAgentBrowserSpawnArgs } from "../../process.js";
+import { redactInvocationArgs } from "../../runtime-redaction.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { applyNamespaceToNextActions } from "../../results/next-actions.js";
+import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions, } from "../../results/recovery-next-actions.js";
+import { buildStaleRefPreflight, getTraceOwnerGuardMessage } from "./session-state.js";
+import { formatAgentBrowserNextActionsText, redactRecoveryHint } from "./final-result.js";
+import { validateQaAttachedPrecondition } from "./diagnostics.js";
+import { findRequestedArtifactCloseViolation } from "./prompt-guards.js";
+import { collectSamePageRefFreshnessPreflight } from "./prepare-refs.js";
+import { getExactSensitiveStdinValues, validateStdinCommandContract } from "./prepare-input.js";
+import { categorizedGuardFailure, preparationFailure, preparationSessionDetails, } from "./prepare-failure.js";
+export function prepareGuardEvidence(preserveAttachedBrowserSession, context) {
+    const plan = context.semantic.selection.executionPlan;
+    return {
+        redactedEffectiveArgs: redactInvocationArgs(prepareAgentBrowserSpawnArgs(plan.effectiveArgs, undefined, preserveAttachedBrowserSession, context.chromeStartupArgs)),
+        redactedRecoveryHint: redactRecoveryHint(plan.recoveryHint),
+        statePatch: plan.managedSessionName === context.freshSessionName
+            ? { freshSessionOrdinal: context.freshSessionOrdinal + 1 }
+            : {},
+        exactSensitiveValues: getExactSensitiveStdinValues({
+            command: plan.commandInfo.command,
+            commandTokens: context.semantic.commandTokens,
+            stdin: context.stdin,
+        }),
+    };
+}
+function guardRequest(context, evidence) {
+    return {
+        plan: context.semantic.selection.executionPlan,
+        redactedArgs: context.input.redactedArgs,
+        effectiveArgs: evidence.redactedEffectiveArgs,
+        sessionMode: context.sessionMode,
+        statePatch: evidence.statePatch,
+    };
+}
+function planRecoveryActions(context, tabError) {
+    const { selection, scrollRecovery } = context.semantic;
+    const plan = selection.executionPlan;
+    return applyNamespaceToNextActions(tabError
+        ? buildSessionTabRecoveryNextActions({
+            kind: "tab-drift",
+            resultCategory: "failure",
+            sessionName: plan.sessionName,
+            tabCorrection: selection.sessionTabCorrection,
+            target: selection.page.priorSessionTabTarget,
+        })
+        : scrollRecovery?.nextActions, plan.namespace);
+}
+function planFailure(restoreDisabled, context, evidence, cleanup) {
+    const { selection } = context.semantic;
+    const { executionPlan: plan, page } = selection;
+    const error = plan.validationError;
+    if (error === undefined || error === "") {
+        return undefined;
+    }
+    const tabError = selection.sessionTabSelectionError !== undefined && selection.sessionTabSelectionError !== "";
+    const nextActions = planRecoveryActions(context, tabError);
+    const nextActionsText = formatAgentBrowserNextActionsText(nextActions);
+    const input = context.input;
+    return preparationFailure({
+        message: [error, nextActionsText]
+            .filter((text) => text !== undefined)
+            .join("\n\n"),
+        statePatch: evidence.statePatch,
+        details: {
+            args: input.redactedArgs,
+            compiledElectron: input.redactedCompiledElectron,
+            compiledJob: input.redactedCompiledJob,
+            compiledQaPreset: input.redactedCompiledQaPreset,
+            compiledSourceLookup: input.redactedCompiledSourceLookup,
+            compiledNetworkSourceLookup: input.redactedCompiledNetworkSourceLookup,
+            invalidValueFlag: plan.invalidValueFlag,
+            managedSessionCleanupOnlyReason: cleanup.reason,
+            ...preparationSessionDetails(restoreDisabled, plan),
+            ...(cleanup.reason !== undefined ? { namespace: cleanup.namespace ?? "" } : {}),
+            nextActions,
+            sessionMode: context.sessionMode,
+            sessionRecoveryHint: evidence.redactedRecoveryHint,
+            startupScopedFlags: plan.startupScopedFlags,
+            ...(tabError
+                ? {
+                    effectiveArgs: evidence.redactedEffectiveArgs,
+                    sessionTabCorrection: selection.sessionTabCorrection,
+                }
+                : {}),
+            ...(page.coldManagedSession
+                ? { refSnapshotInvalidation: page.priorRefSnapshotInvalidation }
+                : {}),
+            ...buildAgentBrowserResultCategoryDetails({
+                args: input.redactedArgs,
+                command: plan.commandInfo.command,
+                errorText: error,
+                failureCategory: tabError ? "tab-drift" : undefined,
+                succeeded: false,
+                validationError: error,
+            }),
+            validationError: error,
+        },
+    });
+}
+function synchronousGuards(traceOwners, restoreDisabled, context, evidence) {
+    const plan = context.semantic.selection.executionPlan;
+    const traceError = getTraceOwnerGuardMessage({
+        command: plan.commandInfo.command,
+        sessionName: context.semantic.selection.page.sessionStateKey,
+        subcommand: plan.commandInfo.subcommand,
+        traceOwners,
+    });
+    const error = traceError !== undefined && traceError !== ""
+        ? traceError
+        : validateStdinCommandContract({
+            command: plan.commandInfo.command,
+            commandTokens: context.semantic.commandTokens,
+            stdin: context.stdin,
+        });
+    return error !== undefined && error !== ""
+        ? categorizedGuardFailure(restoreDisabled, guardRequest(context, evidence), {
+            message: error,
+            validationError: error,
+        })
+        : undefined;
+}
+async function artifactCloseGuard(artifactManifest, facts, context, evidence) {
+    const violation = await findRequestedArtifactCloseViolation({
+        artifactManifest,
+        command: context.semantic.selection.executionPlan.commandInfo.command,
+        cwd: facts.cwd,
+        promptPolicy: facts.promptPolicy,
+    });
+    return violation
+        ? categorizedGuardFailure(facts.isRestoreDisabled(), guardRequest(context, evidence), {
+            message: violation.message,
+            validationError: violation.message,
+            failureCategory: "policy-blocked",
+            details: { promptGuard: violation },
+        })
+        : undefined;
+}
+function staleRefFailure(restoreDisabled, context, evidence, request) {
+    const plan = context.semantic.selection.executionPlan;
+    return categorizedGuardFailure(restoreDisabled, guardRequest(context, evidence), {
+        message: request.stale.message,
+        failureCategory: "stale-ref",
+        details: {
+            nextActions: applyNamespaceToNextActions(buildSessionAwareStaleRefNextActions(plan.sessionName), plan.namespace),
+            refIds: request.stale.refIds,
+            refSnapshot: request.stale.snapshot,
+            ...(request.includeInvalidation
+                ? { refSnapshotInvalidation: request.stale.snapshotInvalidation }
+                : {}),
+        },
+    });
+}
+async function refGuards(owners, facts, context, evidence) {
+    const { commandTokens, resolvedSnapshot, selection } = context.semantic;
+    const { page, executionPlan: plan } = selection;
+    const stale = buildStaleRefPreflight({
+        commandTokens,
+        currentTarget: page.priorSessionTabTarget,
+        requireExactTargetUrl: page.reuseConfirmedCapture,
+        refSnapshot: resolvedSnapshot ?? page.priorRefSnapshotState,
+        refSnapshotInvalidation: resolvedSnapshot ? undefined : page.priorRefSnapshotInvalidation,
+        stdin: context.stdin,
+    });
+    if (stale) {
+        return staleRefFailure(facts.isRestoreDisabled(), context, evidence, {
+            stale,
+            includeInvalidation: true,
+        });
+    }
+    const freshness = await collectSamePageRefFreshnessPreflight({
+        commandTokens,
+        cwd: facts.cwd,
+        currentTarget: page.priorSessionTabTarget,
+        previousSnapshot: resolvedSnapshot || page.reuseConfirmedCapture ? undefined : page.priorRefSnapshotState,
+        stdin: context.stdin,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: facts.signal,
+    });
+    if (!freshness) {
+        return undefined;
+    }
+    if (freshness.snapshot && page.sessionStateKey !== undefined && page.sessionStateKey !== "") {
+        owners.pageState.applyRefSnapshot({
+            fallbackTarget: page.priorSessionTabTarget,
+            sessionName: page.sessionStateKey,
+            snapshot: freshness.snapshot,
+            update: owners.update,
+        });
+    }
+    return staleRefFailure(facts.isRestoreDisabled(), context, evidence, {
+        stale: freshness,
+        includeInvalidation: false,
+    });
+}
+async function qaAttachedGuard(facts, context, evidence) {
+    if (context.input.compiledQaPreset?.checks.attached !== true) {
+        return undefined;
+    }
+    const plan = context.semantic.selection.executionPlan;
+    const failure = await validateQaAttachedPrecondition({
+        cwd: facts.cwd,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: facts.signal,
+    });
+    return failure
+        ? categorizedGuardFailure(facts.isRestoreDisabled(), guardRequest(context, evidence), {
+            omitCommand: true,
+            message: failure.error,
+            validationError: failure.error,
+            details: {
+                compiledQaPreset: context.input.redactedCompiledQaPreset,
+                nextActions: applyNamespaceToNextActions(failure.nextActions, plan.namespace),
+            },
+        })
+        : undefined;
+}
+export async function validatePreparationGuards(owners, facts, context, evidence) {
+    const invalidPlan = planFailure(facts.isRestoreDisabled(), context, evidence, {
+        reason: context.policy.cleanupOnlyReason,
+        namespace: context.session.ownedManagedSession?.namespace,
+    });
+    if (invalidPlan) {
+        return invalidPlan;
+    }
+    const synchronous = synchronousGuards(owners.traceOwners, facts.isRestoreDisabled(), context, evidence);
+    if (synchronous) {
+        return synchronous;
+    }
+    const artifact = await artifactCloseGuard(owners.artifactManifest, facts, context, evidence);
+    if (artifact) {
+        return artifact;
+    }
+    const refs = await refGuards(owners, facts, context, evidence);
+    if (refs) {
+        return refs;
+    }
+    return qaAttachedGuard(facts, context, evidence);
+}

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

@@ -0,0 +1,75 @@
+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 "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 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 || options.command === "batch") {
+        return undefined;
+    }
+    if (options.command === "eval" && options.commandTokens.includes("--stdin")) {
+        return undefined;
+    }
+    if (isPasswordStdinAuthSave(options)) {
+        return undefined;
+    }
+    const commandLabel = options.command !== undefined && 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.`;
+}

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

@@ -0,0 +1,92 @@
+import { isRecord } from "../../parsing.js";
+import { trySnapshotFilter } from "./prepare/snapshot-filter.js";
+import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
+import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
+import { inspectPreparationGeneration } from "./prepare-page-state.js";
+function observationRequest(process, restoreDisabled, context, evidence) {
+    const plan = context.semantic.selection.executionPlan;
+    return {
+        commandTokens: [...context.semantic.commandTokens],
+        compatibilityWorkaround: plan.compatibilityWorkaround,
+        cwd: process.cwd,
+        effectiveArgs: [...evidence.redactedEffectiveArgs],
+        managedSessionRestoreDisabled: restoreDisabled,
+        redactedArgs: context.input.redactedArgs,
+        sessionMode: context.sessionMode,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: process.signal,
+        usedImplicitSession: plan.usedImplicitSession,
+    };
+}
+async function bindFilteredSnapshotGeneration(owners, process, context) {
+    const { page, executionPlan: plan } = context.semantic.selection;
+    const key = page.sessionStateKey;
+    if (key === undefined ||
+        key === "" ||
+        plan.sessionName === undefined ||
+        plan.sessionName === "") {
+        return;
+    }
+    const daemon = await inspectPreparationGeneration(process, {
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        owned: context.session.ownedManagedSession,
+    });
+    owners.pageState.bindSnapshotGeneration(key, daemon.status === "active" ? daemon.generation : undefined);
+    if (context.session.ownedManagedSession &&
+        daemon.status === "active" &&
+        daemon.generation !== undefined &&
+        daemon.generation !== "") {
+        owners.restoreState.recordDaemonRestoreKey(plan.sessionName, plan.namespace, daemon.restoreKey, daemon.generation);
+    }
+    return { refSnapshot: owners.pageState.get(key).refSnapshot };
+}
+async function filteredSnapshot(owners, process, context, evidence) {
+    const { page } = context.semantic.selection;
+    const result = await trySnapshotFilter({
+        ...observationRequest(process, () => owners.restoreState.isDisabled(context.semantic.selection.executionPlan.sessionName, context.semantic.selection.executionPlan.namespace), context, evidence),
+        modelVisible: process.modelVisible,
+        artifactManifest: owners.artifactManifest,
+        persistentArtifactStore: owners.artifactStore,
+        previousRefSnapshot: page.priorRefSnapshotState,
+        sessionStateKey: page.sessionStateKey,
+        sessionPageState: owners.pageState,
+        sessionPageStateUpdate: owners.update,
+    });
+    if (!result) {
+        return undefined;
+    }
+    const generation = await bindFilteredSnapshotGeneration(owners, process, context);
+    const toolResult = generation && isRecord(result.result.details)
+        ? { ...result.result, details: { ...result.result.details, ...generation } }
+        : result.result;
+    return {
+        kind: "early-result",
+        statePatch: {
+            ...evidence.statePatch,
+            artifactManifest: result.artifactManifest ?? evidence.statePatch.artifactManifest,
+        },
+        result: toolResult,
+    };
+}
+export async function prepareObservations(owners, process, context, evidence) {
+    const snapshot = await filteredSnapshot(owners, process, context, evidence);
+    if (snapshot) {
+        return snapshot;
+    }
+    const request = observationRequest(process, () => owners.restoreState.isDisabled(context.semantic.selection.executionPlan.sessionName, context.semantic.selection.executionPlan.namespace), context, evidence);
+    const network = await tryNetworkRequestsPageFilter(request);
+    if (network) {
+        return { kind: "early-result", statePatch: evidence.statePatch, result: network };
+    }
+    if (context.semantic.selection.executionPlan.startupScopedFlags.length !== 0) {
+        return undefined;
+    }
+    const container = await tryContainerScroll(request);
+    if (container) {
+        return { kind: "early-result", statePatch: evidence.statePatch, result: container };
+    }
+    const page = await tryPageScrollTo(request);
+    return page ? { kind: "early-result", statePatch: evidence.statePatch, result: page } : undefined;
+}

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

@@ -0,0 +1,254 @@
+import { isRecord } from "../../parsing.js";
+import { extractUpstreamCommandTokens } from "../../runtime.js";
+import { redactInvocationArgs } from "../../runtime-redaction.js";
+import { getExplicitSessionPageVerificationRequirement, getPageTargetValidationError, } from "../../page-target-validation.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { buildStaleRefPreflight, ensureSessionTabTarget, extractStringResultField, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
+import { validateStdinCommandContract } from "./prepare-input.js";
+import { preparationFailure, preparationSessionDetails } from "./prepare-failure.js";
+import { planHasValidationError, withPlanValidationError } from "./prepare-session-plan.js";
+function shouldSelectRememberedTab(plan, hasReadConfirmation, request) {
+    const tokens = extractUpstreamCommandTokens(request.preparedArgs.args);
+    const knownStaleRef = buildStaleRefPreflight({
+        commandTokens: tokens,
+        currentTarget: request.page.priorSessionTabTarget,
+        refSnapshot: request.page.priorRefSnapshotState,
+        refSnapshotInvalidation: request.page.priorRefSnapshotInvalidation,
+        stdin: request.stdin,
+    });
+    const invalidStdin = validateStdinCommandContract({
+        command: plan.commandInfo.command,
+        commandTokens: tokens,
+        stdin: request.stdin,
+    });
+    const pin = shouldPinSessionTabForCommand({
+        command: plan.commandInfo.command,
+        commandTokens: tokens,
+        pinningRequired: !hasReadConfirmation &&
+            request.page.sessionTabPinningReason !== undefined &&
+            request.input.compiledQaPreset?.checks.url === undefined,
+        reopenPending: request.page.coldManagedSession,
+        sessionName: plan.sessionName,
+        stdin: request.stdin,
+    });
+    return (!planHasValidationError(plan) &&
+        !plan.plainTextInspection &&
+        !knownStaleRef &&
+        invalidStdin === undefined &&
+        request.page.priorSessionTabTarget !== undefined &&
+        pin);
+}
+async function reopenRememberedTab(pageState, process, plan, request) {
+    const page = request.page;
+    const target = page.priorSessionTabTarget;
+    if (!page.coldManagedSession || !target) {
+        return { page, reopened: true };
+    }
+    const data = await runSessionCommandData({
+        args: ["open", target.url],
+        cwd: process.cwd,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: process.signal,
+        timeoutMs: process.timeoutMs,
+        onProcessResult: ({ agentBrowserStarted }) => {
+            // A started open may navigate even when its CLI is aborted before replying.
+            if (agentBrowserStarted &&
+                page.sessionStateKey !== undefined &&
+                page.sessionStateKey !== "") {
+                pageState.setTabReopenPending({
+                    pending: false,
+                    sessionName: page.sessionStateKey,
+                    update: request.update,
+                });
+            }
+        },
+    });
+    if (data === undefined) {
+        return { page, reopened: false };
+    }
+    return {
+        page: {
+            ...page,
+            priorSessionTabTarget: {
+                ...target,
+                targetId: isRecord(data) && typeof data.targetId === "string" ? data.targetId : undefined,
+            },
+        },
+        reopened: true,
+    };
+}
+function abortedReopenResult(restoreDisabled, plan, request) {
+    const errorText = "agent_browser was aborted while reopening the remembered page. The requested command did not run.";
+    return preparationFailure({
+        message: errorText,
+        details: {
+            aborted: true,
+            args: request.input.redactedArgs,
+            command: plan.commandInfo.command,
+            effectiveArgs: redactInvocationArgs(plan.effectiveArgs),
+            sessionMode: request.sessionMode,
+            ...preparationSessionDetails(restoreDisabled, plan),
+            ...buildAgentBrowserResultCategoryDetails({
+                args: request.input.redactedArgs,
+                command: plan.commandInfo.command,
+                errorText,
+                failureCategory: "aborted",
+                succeeded: false,
+            }),
+        },
+    });
+}
+async function selectReopenedTab(process, plan, reopened) {
+    if (process.signal?.aborted === true) {
+        return undefined;
+    }
+    if (!reopened.reopened) {
+        return {
+            error: "agent-browser could not reopen the remembered URL after the managed browser shut down. Navigate explicitly, then run snapshot -i before retrying.",
+        };
+    }
+    const target = reopened.page.priorSessionTabTarget;
+    if (!target) {
+        return undefined;
+    }
+    return ensureSessionTabTarget({
+        cwd: process.cwd,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: process.signal,
+        target,
+    });
+}
+function reconcileTabSelection(base, reopened, selection) {
+    const error = selection?.error;
+    return {
+        ...base,
+        page: reopened.page,
+        sessionTabCorrection: selection?.correction,
+        sessionTabSelectionError: error,
+        executionPlan: error !== undefined && error !== ""
+            ? withPlanValidationError(base.executionPlan, error)
+            : base.executionPlan,
+    };
+}
+export async function preparePageSelection(pageState, process, hasReadConfirmation, request) {
+    const base = {
+        page: request.page,
+        executionPlan: request.plan,
+        livePageVerified: false,
+    };
+    if (!shouldSelectRememberedTab(request.plan, hasReadConfirmation, request)) {
+        return base;
+    }
+    process.signal?.throwIfAborted();
+    const reopened = await reopenRememberedTab(pageState, process, request.plan, request);
+    const selection = await selectReopenedTab(process, request.plan, reopened);
+    if (request.page.coldManagedSession && process.signal?.aborted === true) {
+        return {
+            earlyResult: abortedReopenResult(request.restoreDisabled, request.plan, request),
+        };
+    }
+    process.signal?.throwIfAborted();
+    return reconcileTabSelection(base, reopened, selection);
+}
+export function callerOwnedExplicitSession(ownsSession, plan) {
+    return plan.sessionName !== undefined && !plan.usedImplicitSession && !ownsSession;
+}
+export function requiresLivePageVerification(preserveAttachedBrowserSession, routing, selection) {
+    return (!routing.hasReadConfirmation &&
+        (selection.page.reuseConfirmedCapture ||
+            callerOwnedExplicitSession(routing.ownsSession, selection.executionPlan) ||
+            preserveAttachedBrowserSession === true));
+}
+async function readLiveUrl(process, plan) {
+    try {
+        const data = await runSessionCommandData({
+            args: ["get", "url"],
+            cwd: process.cwd,
+            namespace: plan.namespace,
+            sessionName: plan.sessionName,
+            signal: process.signal,
+            throwOnFailure: true,
+        });
+        return extractStringResultField(data, "result") ?? extractStringResultField(data, "url");
+    }
+    catch (error) {
+        if (process.signal?.aborted === true) {
+            process.signal.throwIfAborted();
+            throw error;
+        }
+        // A failed read cannot establish the target; the caller retains the requirement error.
+    }
+    return undefined;
+}
+function verifiedLivePage(selection, url) {
+    const target = selection.page.priorSessionTabTarget;
+    return {
+        ...selection,
+        livePageVerified: true,
+        page: {
+            ...selection.page,
+            priorSessionTabTarget: target?.url === url ? { ...target, url } : { url },
+            priorSessionTabTargetUnknown: undefined,
+        },
+    };
+}
+export async function verifyPreparationLivePage(process, selection, request) {
+    const plan = selection.executionPlan;
+    if (request.requirement === undefined ||
+        request.requirement === "" ||
+        plan.sessionName === undefined ||
+        plan.sessionName === "") {
+        return selection;
+    }
+    if (process.establishAttachedBrowserSession === true) {
+        return { ...selection, executionPlan: withPlanValidationError(plan, request.requirement) };
+    }
+    const url = await readLiveUrl(process, plan);
+    if (url === undefined) {
+        return { ...selection, executionPlan: withPlanValidationError(plan, request.requirement) };
+    }
+    const error = getPageTargetValidationError({
+        args: request.args,
+        currentPageUrl: url,
+        pageUrlUnknown: false,
+        stdin: request.stdin,
+    });
+    if (error !== undefined && error !== "") {
+        return { ...selection, executionPlan: withPlanValidationError(plan, error) };
+    }
+    return verifiedLivePage(selection, url);
+}
+export async function verifyCommandLivePage(process, routing, selection, request) {
+    const { page, executionPlan: plan } = selection;
+    const stale = buildStaleRefPreflight({
+        commandTokens: request.commandTokens,
+        currentTarget: page.priorSessionTabTarget,
+        refSnapshot: request.resolvedSnapshot ?? page.priorRefSnapshotState,
+        refSnapshotInvalidation: request.resolvedSnapshot
+            ? undefined
+            : page.priorRefSnapshotInvalidation,
+        stdin: request.stdin,
+    });
+    const invalidStdin = validateStdinCommandContract({
+        command: plan.commandInfo.command,
+        commandTokens: request.commandTokens,
+        stdin: request.stdin,
+    });
+    const eligible = !planHasValidationError(plan) &&
+        stale === undefined &&
+        invalidStdin === undefined &&
+        requiresLivePageVerification(process.preserveAttachedBrowserSession, routing, selection);
+    const requirement = eligible && !selection.livePageVerified
+        ? getExplicitSessionPageVerificationRequirement({
+            args: plan.effectiveArgs,
+            stdin: request.stdin,
+        })
+        : undefined;
+    return verifyPreparationLivePage(process, selection, {
+        args: plan.effectiveArgs,
+        requirement,
+        stdin: request.stdin,
+    });
+}