pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-outcomes.js

@@ -0,0 +1,187 @@
+import { isCloseCommand } from "../../command-taxonomy.js";
+import { buildNextToolAction, withOptionalNamespaceArgs, withOptionalSessionArgs, } from "../../results/next-actions.js";
+function describeClose(facts, attemptedSessionName) {
+    if (facts.succeeded) {
+        return { status: "closed", summary: `Managed session ${attemptedSessionName} was closed.` };
+    }
+    if (facts.activeBefore) {
+        return {
+            status: "preserved",
+            summary: `Managed session close failed; previous managed session ${facts.previousSessionName} remains current.`,
+        };
+    }
+    return {
+        status: "abandoned",
+        summary: "Managed session close failed; no managed session is active.",
+    };
+}
+function describeSuccessfulLaunch(facts) {
+    if ((facts.replacedSessionName?.length ?? 0) > 0) {
+        return {
+            status: "replaced",
+            summary: `Managed session ${facts.replacedSessionName ?? ""} was replaced by ${facts.currentSessionName}.`,
+        };
+    }
+    if (!facts.activeBefore && facts.activeAfter) {
+        return {
+            status: "created",
+            summary: `Managed session ${facts.currentSessionName} is now current.`,
+        };
+    }
+    return {
+        status: "unchanged",
+        summary: `Managed session ${facts.currentSessionName} remains current.`,
+    };
+}
+function describeFailedLaunch(facts, attemptedSessionName) {
+    if (facts.activeBefore) {
+        const summary = facts.sessionMode === "fresh" && attemptedSessionName !== facts.previousSessionName
+            ? `Fresh managed session ${attemptedSessionName} failed before becoming current; previous managed session ${facts.previousSessionName} was preserved.`
+            : `Managed session call failed; previous managed session ${facts.previousSessionName} was preserved.`;
+        return { status: "preserved", summary };
+    }
+    return {
+        status: "abandoned",
+        summary: facts.sessionMode === "fresh"
+            ? `Fresh managed session ${attemptedSessionName} failed before becoming current; no previous managed session was active, so no managed session is current.`
+            : "Managed session call failed before any managed session became current.",
+    };
+}
+export function buildManagedSessionOutcome(facts) {
+    const attemptedSessionName = facts.attemptedSessionName;
+    if (attemptedSessionName === undefined || attemptedSessionName.length === 0) {
+        return;
+    }
+    let description;
+    if (isCloseCommand(facts.command)) {
+        description = describeClose(facts, attemptedSessionName);
+    }
+    else if (facts.succeeded) {
+        description = describeSuccessfulLaunch(facts);
+    }
+    else {
+        description = describeFailedLaunch(facts, attemptedSessionName);
+    }
+    return {
+        activeAfter: facts.activeAfter,
+        activeBefore: facts.activeBefore,
+        attemptedSessionName,
+        currentSessionName: facts.currentSessionName,
+        ...((facts.currentSessionNamespace?.length ?? 0) > 0
+            ? { currentSessionNamespace: facts.currentSessionNamespace }
+            : {}),
+        previousSessionName: facts.previousSessionName,
+        replacedSessionName: facts.replacedSessionName,
+        replacedSessionNamespace: facts.replacedSessionNamespace,
+        sessionMode: facts.sessionMode,
+        succeeded: facts.succeeded,
+        ...description,
+    };
+}
+function isFreshPostLaunchFailure(outcome) {
+    return (!outcome.succeeded &&
+        outcome.sessionMode === "fresh" &&
+        outcome.activeAfter &&
+        outcome.currentSessionName.length > 0 &&
+        ["created", "replaced", "unchanged"].includes(outcome.status));
+}
+function formatOutcomeHeadline(outcome) {
+    if (outcome.status === "preserved") {
+        return "Managed session outcome: Fresh launch failed; your previous browser session is still active.";
+    }
+    if (outcome.status === "abandoned") {
+        return "Managed session outcome: Fresh launch failed; no managed browser session is current.";
+    }
+    if (isFreshPostLaunchFailure(outcome)) {
+        return "Managed session outcome: Fresh launch became current, but this tool call failed after launch.";
+    }
+    return `Managed session outcome: ${outcome.summary}`;
+}
+function formatRecoveryGuidance(outcome) {
+    const lines = ["Recovery:"];
+    if (outcome.status === "preserved") {
+        lines.push('- Continue with sessionMode "auto" on the current session, or retry the intended launch with sessionMode "fresh".', "- Run doctor to verify agent-browser install and environment when failures persist.");
+    }
+    else if (outcome.status === "abandoned") {
+        lines.push('- Retry with sessionMode "fresh" (for example args: ["open", "<url>"]) after verifying agent-browser is on PATH.', "- Run doctor when install or environment issues are suspected.");
+    }
+    else if (isFreshPostLaunchFailure(outcome)) {
+        lines.push('- Continue with sessionMode "auto" on the current session, or inspect failureCategory / qaPreset to fix the post-launch failure.', "- Run doctor only if later browser commands also fail.");
+    }
+    else {
+        lines.push('- Retry with sessionMode "fresh" when launch-scoped flags must apply, or run doctor to verify the environment.');
+    }
+    lines.push("- Full session names and transition details remain in details.managedSessionOutcome.");
+    return lines.join("\n");
+}
+export function formatManagedSessionOutcomeText(outcome) {
+    if (!outcome) {
+        return;
+    }
+    if (outcome.replacedSessionClosed === false) {
+        const cleanupWarning = "Cleanup warning: Automatic close of the previous wrapper-managed session failed, so it remains wrapper-owned. Use details.managedSessionOutcome for its exact identity and close it explicitly when safe.";
+        return outcome.succeeded
+            ? ["Managed session outcome: The fresh browser became current.", cleanupWarning].join("\n")
+            : [formatOutcomeHeadline(outcome), formatRecoveryGuidance(outcome), cleanupWarning].join("\n");
+    }
+    if (outcome.status === "closed" && outcome.succeeded) {
+        return [
+            "Managed session outcome: The current wrapper-managed browser session was closed.",
+            "Next sessionMode auto call will start or attach a managed session as needed. If upstream session list still shows rows, they are separate saved/upstream sessions; use close --all only when full cleanup is intended.",
+            "Full session names and transition details remain in details.managedSessionOutcome.",
+        ].join("\n");
+    }
+    if (outcome.succeeded || outcome.sessionMode !== "fresh") {
+        return;
+    }
+    return [formatOutcomeHeadline(outcome), formatRecoveryGuidance(outcome)].join("\n");
+}
+function currentSessionRecovery(outcome) {
+    const sessionLabel = isFreshPostLaunchFailure(outcome)
+        ? "current managed session"
+        : "preserved managed session";
+    const identityArgs = withOptionalNamespaceArgs(outcome.currentSessionNamespace, withOptionalSessionArgs(outcome.currentSessionName, []));
+    return [
+        buildNextToolAction({
+            args: [...identityArgs, "get", "url"],
+            id: "verify-current-managed-session",
+            reason: `Confirm the ${sessionLabel} before continuing with sessionMode auto.`,
+            safety: `Read-only URL check on the ${sessionLabel}.`,
+        }),
+        buildNextToolAction({
+            args: [...identityArgs, "snapshot", "-i"],
+            id: "snapshot-current-managed-session",
+            reason: `Refresh interactive refs on the ${sessionLabel} before retrying the workflow.`,
+            safety: "Read-only snapshot; no navigation.",
+        }),
+    ];
+}
+export function buildManagedSessionFreshFailureNextActions(outcome) {
+    if (!outcome || outcome.succeeded || outcome.sessionMode !== "fresh") {
+        return [];
+    }
+    const actions = [];
+    if (!isFreshPostLaunchFailure(outcome)) {
+        actions.push(buildNextToolAction({
+            args: ["doctor"],
+            id: "run-agent-browser-doctor",
+            reason: "Verify agent-browser install, PATH, and environment after a failed fresh launch.",
+            safety: "Read-only local diagnostics; does not mutate browser state.",
+        }));
+    }
+    if ((outcome.status === "preserved" || isFreshPostLaunchFailure(outcome)) &&
+        outcome.activeAfter &&
+        outcome.currentSessionName.length > 0) {
+        actions.push(...currentSessionRecovery(outcome));
+    }
+    else {
+        actions.push(buildNextToolAction({
+            args: ["open", "about:blank"],
+            id: "retry-fresh-managed-session",
+            reason: "Start a new managed browser session after the failed fresh launch.",
+            safety: "Replace about:blank with the intended URL from your workflow.",
+            sessionMode: "fresh",
+        }));
+    }
+    return actions;
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-refs.js

@@ -0,0 +1,171 @@
+import { isRefGuardedCommand, isRefInvalidatingBatchCommand } from "../../command-taxonomy.js";
+import { parseRefId } from "../../parsing.js";
+import { targetsMatch, } from "../../session-page-state.js";
+import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
+import { getScreenshotPositionalIndices } from "./artifact-paths.js";
+export function getStaleRefArgs(commandTokens, stdin) {
+    if (commandTokens[0] !== "batch") {
+        return commandTokens;
+    }
+    const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
+    return steps.length > 0 ? steps.flatMap((step) => step) : commandTokens;
+}
+function getFlaggedSelector(tokens) {
+    let selector;
+    for (let index = tokens[0] === "diff" ? 2 : 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === "--selector" || token === "-s") {
+            selector = tokens[++index];
+        }
+        else if (tokens[0] === "diff" &&
+            ["--baseline", "-b", "--output", "-o", "--threshold", "-t", "--depth", "-d"].includes(token)) {
+            index += 1;
+        }
+    }
+    return selector;
+}
+function getSelectorOperands(tokens) {
+    switch (tokens[0]) {
+        case "click":
+            return [tokens.slice(1).find((token) => token !== "--new-tab" && token !== "--human")];
+        case "drag":
+            return tokens.slice(1, 3);
+        case "get":
+            return [!["url", "title", "cdp-url", "count"].includes(tokens[1]) ? tokens[2] : undefined];
+        case "is":
+            return [tokens[2]];
+        case "screenshot":
+            return [tokens[getScreenshotPositionalIndices(tokens)[0]]];
+        case "diff":
+        case "scroll":
+            return [getFlaggedSelector(tokens)];
+        default:
+            return [tokens[1]];
+    }
+}
+// Inspect only upstream's selector slots: fill text, file paths and key data are not refs.
+function collectRefsFromTokens(tokens) {
+    if (!isRefGuardedCommand(tokens[0]) || (tokens[0] === "diff" && tokens[1] !== "screenshot")) {
+        return [];
+    }
+    return getSelectorOperands(tokens).flatMap((selector) => {
+        const ref = selector === undefined ? undefined : parseRefId(selector);
+        return ref === undefined ? [] : [ref];
+    });
+}
+export function getGuardedRefUsage(commandTokens, stdin, options = {}) {
+    if (commandTokens[0] !== "batch") {
+        return collectRefsFromTokens(commandTokens);
+    }
+    const refs = [];
+    for (const step of getUpstreamEffectiveBatchSteps(commandTokens, stdin)) {
+        if (options.includeRefsAfterBatchSnapshot !== true && (step[0] ?? "") === "snapshot") {
+            break;
+        }
+        refs.push(...collectRefsFromTokens(step));
+    }
+    return refs;
+}
+function isSafeSameSnapshotFormBatchStep(step, refSnapshot) {
+    const refIds = collectRefsFromTokens(step);
+    if (refIds.length === 0 || !refSnapshot) {
+        return false;
+    }
+    const roles = refIds.map((refId) => refSnapshot.refs?.[refId]?.role.toLowerCase());
+    if (roles.some((role) => role === undefined)) {
+        return false;
+    }
+    switch (step[0]) {
+        case "check":
+        case "uncheck":
+        case "click":
+        case "tap":
+            return roles.every((role) => role === "checkbox" || role === "radio");
+        case "select":
+            return roles.every((role) => role === "combobox");
+        default:
+            return false;
+    }
+}
+function getBatchRefInvalidationMessage(commandTokens, stdin, refSnapshot) {
+    if (commandTokens[0] !== "batch") {
+        return;
+    }
+    let priorStepInvalidatesRefs = false;
+    for (const step of getUpstreamEffectiveBatchSteps(commandTokens, stdin)) {
+        if ((step[0] ?? "") === "snapshot") {
+            priorStepInvalidatesRefs = false;
+        }
+        const refIds = collectRefsFromTokens(step);
+        if (refIds.length > 0 && isRefGuardedCommand(step[0]) && priorStepInvalidatesRefs) {
+            return `Batch step ${step[0]} uses page-scoped ref ${refIds.map((refId) => `@${refId}`).join(", ")} after an earlier batch step can navigate or mutate the page. Split the batch, run snapshot -i after the page-changing step, then retry with current refs.`;
+        }
+        if (isRefInvalidatingBatchCommand(step) &&
+            !isSafeSameSnapshotFormBatchStep(step, refSnapshot)) {
+            priorStepInvalidatesRefs = true;
+        }
+    }
+    return;
+}
+function invalidatedRefFailure(invalidation, refIds) {
+    return {
+        message: invalidation.reason === "page-transition"
+            ? `Ref ${refIds.map((refId) => `@${refId}`).join(", ")} cannot be used yet. ${invalidation.summary}`
+            : `Ref ${refIds.map((refId) => `@${refId}`).join(", ")} cannot be used because the latest snapshot for this session reported No active page. Run snapshot -i successfully before using page-scoped refs.`,
+        refIds,
+        snapshotInvalidation: invalidation,
+    };
+}
+function snapshotTargetChanged(snapshotTarget, currentTarget, requireExactTargetUrl) {
+    const exactUrlMismatch = requireExactTargetUrl &&
+        snapshotTarget !== undefined &&
+        currentTarget !== undefined &&
+        snapshotTarget.url !== currentTarget.url;
+    return !targetsMatch(snapshotTarget, currentTarget) || exactUrlMismatch;
+}
+function snapshotRefFailure(facts, snapshot, usedRefIds) {
+    if (snapshotTargetChanged(snapshot.target, facts.currentTarget, facts.requireExactTargetUrl === true)) {
+        return {
+            message: `Ref ${usedRefIds.map((refId) => `@${refId}`).join(", ")} came from a snapshot for ${snapshot.target?.url ?? "a prior page"}, but the current session target is ${facts.currentTarget?.url ?? "unknown"}. Run snapshot -i again before using page-scoped refs.`,
+            refIds: usedRefIds,
+            snapshot,
+        };
+    }
+    const knownRefs = new Set(snapshot.refIds);
+    const missingRefs = usedRefIds.filter((refId) => !knownRefs.has(refId));
+    if (missingRefs.length > 0) {
+        return {
+            message: `Ref ${missingRefs.map((refId) => `@${refId}`).join(", ")} was not present in the latest snapshot for this session. Run snapshot -i again before using page-scoped refs.`,
+            refIds: missingRefs,
+            snapshot,
+        };
+    }
+    return;
+}
+export function buildStaleRefPreflight(facts) {
+    const guardedRefIds = [...new Set(getGuardedRefUsage(facts.commandTokens, facts.stdin))];
+    const usedRefIds = facts.refSnapshotInvalidation
+        ? [
+            ...new Set(getGuardedRefUsage(facts.commandTokens, facts.stdin, {
+                includeRefsAfterBatchSnapshot: true,
+            })),
+        ]
+        : guardedRefIds;
+    const batchInvalidationMessage = getBatchRefInvalidationMessage(facts.commandTokens, facts.stdin, facts.refSnapshot);
+    if (batchInvalidationMessage !== undefined &&
+        batchInvalidationMessage.length > 0 &&
+        guardedRefIds.length > 0) {
+        return {
+            message: batchInvalidationMessage,
+            refIds: guardedRefIds,
+            snapshot: facts.refSnapshot,
+        };
+    }
+    if (usedRefIds.length === 0) {
+        return;
+    }
+    if (facts.refSnapshotInvalidation) {
+        return invalidatedRefFailure(facts.refSnapshotInvalidation, usedRefIds);
+    }
+    return facts.refSnapshot ? snapshotRefFailure(facts, facts.refSnapshot, usedRefIds) : undefined;
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-tabs.js

@@ -0,0 +1,228 @@
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
+import { getRecordCommandOperands, isCloseCommand, isOpenNavigationCommand, isSessionTabPinningExcludedCommand, isSessionTabPostCommandCorrectionExcludedCommand, isWindowOrDiffPageTransitionCommand, } from "../../command-taxonomy.js";
+import { isRecord } from "../../parsing.js";
+import { chooseOpenResultTabCorrection } from "../../runtime-tab-correction.js";
+import { normalizeComparableUrl } from "../../session-page-state.js";
+import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
+import { findFirstPositionalArgument } from "./prepare/wait-timeouts.js";
+import { runSessionCommandData } from "./session-state-commands.js";
+import { extractStringResultField } from "./session-state-observations.js";
+function hasExplicitNavigationOperand(tokens) {
+    const command = tokens[0];
+    return ((command === "a11y" && findFirstPositionalArgument(tokens) !== undefined) ||
+        (["vitals", "web-vitals"].includes(command) &&
+            tokens.slice(1).some((token) => !token.startsWith("--"))) ||
+        getRecordCommandOperands(tokens).url !== undefined);
+}
+export function commandChoosesSessionTabTarget(args) {
+    const tokens = parseArgvDescriptor(args).upstreamCommandTokens;
+    const command = tokens[0];
+    const subcommand = tokens.at(1);
+    return (isOpenNavigationCommand(command) ||
+        isCloseCommand(command) ||
+        command === "connect" ||
+        (command === "state" && subcommand === "load") ||
+        (command === "tab" && subcommand !== undefined && subcommand !== "list") ||
+        isWindowOrDiffPageTransitionCommand(command, subcommand) ||
+        hasExplicitNavigationOperand(tokens));
+}
+function isNonTargetProbe(tokens, reopenPending) {
+    const [command, subcommand] = tokens;
+    if (command === "get" && subcommand === "url" && !reopenPending) {
+        return true;
+    }
+    if (command === "record" && subcommand === "stop") {
+        return true;
+    }
+    if (["console", "errors"].includes(command)) {
+        return true;
+    }
+    return (command === "network" &&
+        !(subcommand === "requests" &&
+            tokens.some((token) => ["--current-page", "--current-origin", "--current-url"].includes(token))));
+}
+function classifyTabPinningStep(step, reopenPending) {
+    const descriptor = parseArgvDescriptor(step);
+    const tokens = descriptor.upstreamCommandTokens;
+    if (commandChoosesSessionTabTarget(tokens)) {
+        return "destination";
+    }
+    if (!needsManagedSession(descriptor) ||
+        isSessionTabPinningExcludedCommand(tokens[0]) ||
+        isNonTargetProbe(tokens, reopenPending)) {
+        return "excluded";
+    }
+    return "page";
+}
+function hasTabPinningContext(facts) {
+    return (facts.pinningRequired === true &&
+        (facts.sessionName ?? "").length > 0 &&
+        (facts.command ?? "").length > 0);
+}
+export function shouldPinSessionTabForCommand(options) {
+    if (!hasTabPinningContext(options) ||
+        isBrowserIndependentRead(options.commandTokens, options.stdin)) {
+        return false;
+    }
+    const steps = options.command === "batch"
+        ? getUpstreamEffectiveBatchSteps(options.commandTokens, options.stdin)
+        : [options.commandTokens];
+    for (const step of steps) {
+        const requirement = classifyTabPinningStep(step, options.reopenPending === true);
+        // A later page action uses the explicit destination, not the remembered tab.
+        if (requirement === "destination") {
+            return false;
+        }
+        if (requirement === "page") {
+            return true;
+        }
+    }
+    return false;
+}
+export function shouldCorrectSessionTabAfterCommand(options) {
+    return (options.pinningRequired === true &&
+        options.sessionName !== undefined &&
+        options.command !== undefined &&
+        !isSessionTabPostCommandCorrectionExcludedCommand(options.command));
+}
+function getTabSelection(tab) {
+    if ((tab.targetId?.length ?? 0) > 0) {
+        return { selectedTab: tab.targetId ?? "", selectionKind: "targetId" };
+    }
+    if (typeof tab.tabId === "string" && tab.tabId.trim().length > 0) {
+        return { selectedTab: tab.tabId.trim(), selectionKind: "tabId" };
+    }
+    if (typeof tab.label === "string" && tab.label.trim().length > 0) {
+        return { selectedTab: tab.label.trim(), selectionKind: "label" };
+    }
+    return typeof tab.index === "number"
+        ? { selectedTab: String(tab.index), selectionKind: "index" }
+        : undefined;
+}
+function selectPreferredTab(tabs, title) {
+    const titledTabs = title.length > 0 ? tabs.filter((tab) => tab.title?.trim() === title) : [];
+    return (titledTabs.find((tab) => tab.active === true) ??
+        titledTabs.at(0) ??
+        tabs.find((tab) => tab.active === true) ??
+        tabs.at(0));
+}
+function selectAnySessionTargetTab(tabs, target) {
+    const targetUrl = typeof target.url === "string" ? normalizeComparableUrl(target.url) : undefined;
+    if (targetUrl === undefined || targetUrl.length === 0) {
+        return;
+    }
+    const matchingTabs = tabs.filter((tab) => (target.targetId?.length ?? 0) > 0
+        ? tab.targetId === target.targetId
+        : normalizeComparableUrl(tab.url ?? "") === targetUrl);
+    const targetTitle = target.title?.trim() ?? "";
+    const selectedTab = selectPreferredTab(matchingTabs, targetTitle);
+    const selection = selectedTab ? getTabSelection(selectedTab) : undefined;
+    return selection
+        ? {
+            ...selection,
+            ...(targetTitle.length > 0 ? { targetTitle } : {}),
+            targetUrl,
+        }
+        : undefined;
+}
+function selectSessionTargetTab(tabs, target) {
+    if ((target.targetId?.length ?? 0) > 0) {
+        const correction = selectAnySessionTargetTab(tabs, target);
+        return correction && tabs.find((tab) => tab.targetId === target.targetId)?.active !== true
+            ? correction
+            : undefined;
+    }
+    return chooseOpenResultTabCorrection({ tabs, targetTitle: target.title, targetUrl: target.url });
+}
+function mapTabData(data) {
+    if (!isRecord(data) || !Array.isArray(data.tabs)) {
+        return;
+    }
+    return data.tabs.filter(isRecord).map((tab, index) => ({
+        active: tab.active === true,
+        index: typeof tab.index === "number" ? tab.index : index,
+        label: typeof tab.label === "string" ? tab.label : undefined,
+        tabId: typeof tab.tabId === "string" ? tab.tabId : undefined,
+        targetId: typeof tab.targetId === "string" ? tab.targetId : undefined,
+        title: typeof tab.title === "string" ? tab.title : undefined,
+        url: typeof tab.url === "string" ? tab.url : undefined,
+    }));
+}
+export async function collectOpenResultTabCorrection(options) {
+    const { cwd, namespace, sessionName, signal, targetTitle, targetUrl } = options;
+    const tabs = mapTabData(await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal }));
+    return tabs ? chooseOpenResultTabCorrection({ tabs, targetTitle, targetUrl }) : undefined;
+}
+function tabMetadataDisagreesWithObservedUrl(tabs, active, observedUrl) {
+    return (normalizeComparableUrl(active?.url) !== observedUrl &&
+        tabs?.some((tab) => normalizeComparableUrl(tab.url) === observedUrl) === true);
+}
+export async function collectSessionTabTarget(options) {
+    const tabs = mapTabData(await runSessionCommandData({ ...options, args: ["tab", "list"] }));
+    const active = tabs?.find((tab) => tab.active === true);
+    const observedUrl = normalizeComparableUrl(options.target.url);
+    if (tabMetadataDisagreesWithObservedUrl(tabs, active, observedUrl)) {
+        return options.target;
+    }
+    return (active?.targetId?.length ?? 0) > 0
+        ? { ...options.target, targetId: active?.targetId }
+        : options.target;
+}
+export async function collectSessionTabSelection(options) {
+    const { cwd, namespace, sessionName, signal, target } = options;
+    const tabs = mapTabData(await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal }));
+    return tabs ? selectSessionTargetTab(tabs, target) : undefined;
+}
+async function verifySelectedTabUrl(session, tab, targetUrl) {
+    if (normalizeComparableUrl(tab.url) === normalizeComparableUrl(targetUrl)) {
+        return true;
+    }
+    // Native tab metadata can retain the attempted URL while get url reports Chrome's error page.
+    const data = await runSessionCommandData({ ...session, args: ["get", "url"] });
+    return (normalizeComparableUrl(extractStringResultField(data, "url")) ===
+        normalizeComparableUrl(targetUrl));
+}
+const TAB_VERIFICATION_ERROR = "agent-browser could not re-select and verify the intended tab before running the command. Run tab list and select the intended tab, then snapshot -i before retrying.";
+function isSelectedTab(tab, selectedTab) {
+    return tab !== undefined && getTabSelection(tab)?.selectedTab === selectedTab;
+}
+async function verifyTargetTab(session, tab, selectedTab, targetUrl) {
+    if (!tab || !isSelectedTab(tab, selectedTab)) {
+        return false;
+    }
+    return verifySelectedTabUrl(session, tab, targetUrl);
+}
+export async function ensureSessionTabTarget(options) {
+    const { cwd, namespace, sessionName, signal, target } = options;
+    const session = { cwd, namespace, sessionName, signal };
+    const tabs = mapTabData(await runSessionCommandData({ ...session, args: ["tab", "list"] }));
+    const active = tabs?.find((tab) => tab.active === true);
+    const correction = tabs && selectAnySessionTargetTab(tabs, target);
+    if (!correction) {
+        return { error: TAB_VERIFICATION_ERROR };
+    }
+    // Native tab selection clears refs and frame scope even when selecting the current tab.
+    if (isSelectedTab(active, correction.selectedTab)) {
+        return (await verifyTargetTab(session, active, correction.selectedTab, target.url))
+            ? {}
+            : { error: TAB_VERIFICATION_ERROR };
+    }
+    if (!(await applyOpenResultTabCorrection({ ...session, correction }))) {
+        return { correction, error: TAB_VERIFICATION_ERROR };
+    }
+    const selected = mapTabData(await runSessionCommandData({ ...session, args: ["tab", "list"] }))?.find((tab) => tab.active === true);
+    const verified = await verifyTargetTab(session, selected, correction.selectedTab, target.url);
+    return verified ? { correction } : { correction, error: TAB_VERIFICATION_ERROR };
+}
+export async function applyOpenResultTabCorrection(options) {
+    const { correction, cwd, namespace, sessionName, signal } = options;
+    const result = await runSessionCommandData({
+        args: ["tab", correction.selectedTab],
+        cwd,
+        namespace,
+        sessionName,
+        signal,
+    });
+    return result === undefined ? undefined : correction;
+}