pi-agent-browser-native 0.6.6 → 0.6.8

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

@@ -1,7 +1,9 @@
 import { rm } from "node:fs/promises";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { needsManagedSession } from "../../command-policy.js";
 import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "../../argv-grammar.js";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "../../batch-lifecycle.js";
-import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand, isUnverifiedPageTransitionCommand } from "../../command-taxonomy.js";
+import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWindowOrDiffPageTransitionCommand } from "../../command-taxonomy.js";
 import { OPEN_RESULT_TAB_CORRECTION_FLAGS } from "../../launch-scoped-flags.js";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { getResultingPageTargetState, commandRequiresLivePageVerification } from "../../page-target-validation.js";
@@ -9,7 +11,8 @@ import { analyzeNetworkSourceLookupResults, analyzeSourceLookupResults, redactNe
 import { analyzeQaPresetResults, analyzeQaPresetTimeout, buildQaCompactFailureText, buildQaCompactPassText, extractQaPageContext } from "../../input-modes/job.js";
 import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics } from "../../results/network-routes.js";
 import { buildToolPresentation } from "../../results/presentation.js";
-import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
+import { compactLargePresentationOutput } from "../../results/presentation/large-output.js";
+import { extractEnvelopeErrorText, getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { omitUpstreamLifecycle } from "../../results/presentation/common.js";
 import { getClipboardWritePayloadCandidates, redactClipboardPermissionEcho, redactClipboardPermissionErrorValue } from "../../results/presentation/errors.js";
 import { shouldCaptureSemanticActionNavigationSummary } from "../../results/presentation/semantic-action.js";
@@ -20,7 +23,7 @@ import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
 import { createFreshSessionName, extractUpstreamCommandTokens, resolveManagedSessionState } from "../../runtime.js";
 import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
 import { closeManagedSession, inspectManagedSessionDaemon } from "./managed-session-daemon-policy.js";
-import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBlankWarning, buildElectronPostCommandHealthDiagnostic, buildElectronRefFreshnessDiagnostic, buildElectronSessionMismatch, buildManagedSessionOutcome, collectOpenResultTabCorrection, collectSessionTabSelection, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, formatElectronPostCommandHealthText, formatElectronSessionMismatchText, getSessionContextKey, getStaleRefArgs, mergeNavigationSummaryIntoData, shouldCaptureNavigationSummary, shouldCorrectSessionTabAfterCommand, shouldInspectElectronPostCommandHealth, unwrapPinnedSessionBatchEnvelope, updateTraceOwnerState, } from "./session-state.js";
+import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBlankWarning, buildElectronPostCommandHealthDiagnostic, buildElectronRefFreshnessDiagnostic, buildElectronSessionMismatch, buildManagedSessionOutcome, collectOpenResultTabCorrection, collectSessionTabSelection, commandChoosesSessionTabTarget, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, formatElectronPostCommandHealthText, formatElectronSessionMismatchText, getSessionContextKey, getStaleRefArgs, mergeNavigationSummaryIntoData, shouldCaptureNavigationSummary, shouldCorrectSessionTabAfterCommand, shouldInspectElectronPostCommandHealth, updateTraceOwnerState, } from "./session-state.js";
 import { collectClickDispatchDiagnostic } from "./click-dispatch.js";
 import { buildScrollNoopDiagnostic, collectComboboxFocusDiagnostic, collectElectronBroadGetTextScopeDiagnostics, collectElectronHandoff, collectFillVerificationDiagnostic, collectNavigationSummary, collectOverlayBlockerDiagnostic, collectQaAttachedTarget, collectSnapshotOverlayBlockerDiagnostic, collectRecordingDependencyWarning, collectScrollPositionSnapshot, collectSelectorTextVisibilityDiagnostics, collectTimeoutPartialProgress, sleepMs, formatQaAttachedTargetText, getArtifactCleanupGuidance, getEvalResultWarning, getEvalStdinHint, getSourceLookupElectronContext, } from "./diagnostics.js";
 import { repairScreenshotData } from "./prepare.js";
@@ -160,17 +163,13 @@ export async function processBrowserOutput(input) {
     let networkRoutesBySession = state.networkRoutesBySession;
     try {
         const persistentArtifactStore = getPersistentSessionArtifactStore(ctx);
-        const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
+        // Native upgrade prints text even with --json; all other command shapes keep strict JSON parsing.
+        const plainTextUpgrade = !prepared.executionPlan.plainTextInspection && prepared.executionPlan.commandInfo.command === "upgrade" && !needsManagedSession(parseArgvDescriptor(prepared.runtimeToolArgs));
+        const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath, plainText: plainTextUpgrade });
         let parseError = parsed.parseError;
         let presentationEnvelope = parsed.envelope;
         let navigationSummary = undefined;
         let failedTransitionReverification = false;
-        if (prepared.pinnedBatchUnwrapMode) {
-            const pinnedBatchResult = unwrapPinnedSessionBatchEnvelope({ envelope: parsed.envelope, includeNavigationSummary: prepared.includePinnedNavigationSummary, mode: prepared.pinnedBatchUnwrapMode });
-            parseError = pinnedBatchResult.parseError ?? parseError;
-            presentationEnvelope = pinnedBatchResult.envelope ?? presentationEnvelope;
-            navigationSummary = pinnedBatchResult.navigationSummary;
-        }
         const repairedScreenshot = await repairScreenshotArtifact({ cwd, envelope: presentationEnvelope, request: prepared.preparedArgs.screenshotPathRequest });
         presentationEnvelope = repairedScreenshot.envelope;
         const repairedBatchScreenshots = await repairBatchScreenshotArtifacts({ cwd, envelope: presentationEnvelope, requests: prepared.preparedArgs.batchScreenshotPathRequests });
@@ -180,6 +179,15 @@ export async function processBrowserOutput(input) {
         const batchCommandSteps = prepared.executionPlan.commandInfo.command === "batch"
             ? getUpstreamEffectiveBatchSteps(prepared.commandTokens, prepared.runtimeToolStdin)
             : [];
+        const dispatchedCommands = prepared.executionPlan.commandInfo.command !== "batch"
+            ? [prepared.commandTokens]
+            : Array.isArray(presentationEnvelope?.data)
+                ? presentationEnvelope.data.flatMap((row, index) => isRecord(row) ? [Array.isArray(row.command) && row.command.every((token) => typeof token === "string") ? row.command : batchCommandSteps[index] ?? []] : [])
+                : batchCommandSteps;
+        const destinationTransition = dispatchedCommands.some((step) => {
+            const [command, subcommand] = extractUpstreamCommandTokens(step);
+            return isWindowOrDiffPageTransitionCommand(command, subcommand);
+        });
         const nestedBatchClose = prepared.executionPlan.commandInfo.command === "batch"
             ? getSuccessfulBatchCloseLifecycle(presentationEnvelope?.data, batchCommandSteps)
             : undefined;
@@ -198,7 +206,7 @@ export async function processBrowserOutput(input) {
         const parseFailureOutput = parseError && processResult.stdoutSpillPath
             ? { fullOutputUnavailable: "Malformed upstream output was discarded because it may contain sensitive browser data." }
             : {};
-        const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
+        const processSucceeded = !processResult.timedOut && !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
         const plainTextInspection = prepared.executionPlan.plainTextInspection && processSucceeded;
         const parseSucceeded = plainTextInspection || parseError === undefined;
         if (isStreamEnableAlreadyEnabledNoop({ command: prepared.executionPlan.commandInfo.command, envelope: presentationEnvelope, processSucceeded, subcommand: prepared.executionPlan.commandInfo.subcommand })) {
@@ -209,6 +217,10 @@ export async function processBrowserOutput(input) {
         const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
         const sessionStateKey = getSessionContextKey(prepared.executionPlan.sessionName, prepared.executionPlan.namespace);
         const closeAllApplied = nestedBatchClosesAll || (directCloseAllRequested && succeeded);
+        if (sessionStateKey && processResult.agentBrowserStarted && sessionPageState.get(sessionStateKey).tabReopenPending === true) {
+            if (dispatchedCommands.some(commandChoosesSessionTabTarget))
+                sessionPageState.setTabReopenPending({ pending: false, sessionName: sessionStateKey, update: sessionPageStateUpdate });
+        }
         if (closeAllApplied) {
             networkRoutesBySession = withoutNamespaceEntries(networkRoutesBySession, prepared.executionPlan.namespace);
             deleteNamespaceEntries(state.attachedSessionKeys, prepared.executionPlan.namespace);
@@ -252,36 +264,32 @@ export async function processBrowserOutput(input) {
             }
         }
         const tabTransition = prepared.executionPlan.commandInfo.command === "tab" && prepared.executionPlan.commandInfo.subcommand !== undefined && !["list", "new"].includes(prepared.executionPlan.commandInfo.subcommand);
-        const resultingPageState = getResultingPageTargetState({
-            args: prepared.executionPlan.effectiveArgs,
-            currentPageUrl: prepared.priorSessionTabTarget?.url,
-            pageUrlUnknown: prepared.priorSessionTabTargetUnknown === true,
-            stdin: prepared.runtimeToolStdin,
-            trustedFirstBatchTabSelection: prepared.pinnedBatchUnwrapMode !== undefined,
-        });
+        // Non-page rows (including a failed prefix) cannot retire a cold target for a navigation that never ran.
+        const resultingPageState = sessionPageState.get(sessionStateKey).tabReopenPending === true
+            ? { currentPageUrl: prepared.priorSessionTabTarget?.url, pageTargetMayHaveChanged: false, pageUrlUnknown: prepared.priorSessionTabTargetUnknown === true }
+            : getResultingPageTargetState({
+                args: prepared.executionPlan.effectiveArgs,
+                executedBatchSteps: dispatchedCommands,
+                currentPageUrl: prepared.priorSessionTabTarget?.url,
+                pageUrlUnknown: prepared.priorSessionTabTargetUnknown === true,
+            });
         if (succeeded &&
-            !navigationSummary &&
             (shouldCaptureNavigationSummary(prepared.executionPlan.commandInfo.command, presentationEnvelope?.data, prepared.executionPlan.commandInfo.subcommand) ||
                 shouldCaptureSemanticActionNavigationSummary(prepared.compiledSemanticAction, presentationEnvelope?.data) ||
                 commandRequiresLivePageVerification(prepared.executionPlan.effectiveArgs, prepared.runtimeToolStdin) ||
-                tabTransition)) {
+                (destinationTransition && !nestedBatchClosed) || tabTransition)) {
             navigationSummary = await collectNavigationSummary({ cwd, namespace: prepared.executionPlan.namespace, priorTarget: prepared.priorSessionTabTarget, reusePriorTitle: !tabTransition, sessionName: prepared.executionPlan.sessionName, signal });
         }
-        // A failed eval/back/forward/reload/state-load/tab would otherwise drop the page to unverified and force the
-        // agent through a manual get url round trip. Probe the live URL ourselves instead: an observed page
-        // stays verified, and a failed
-        // probe preserves the existing unknown-target behavior.
+        // Failed transitions may already have changed the page; keep only a live observed URL.
         if (succeeded === false &&
-            !navigationSummary &&
             processResult.agentBrowserStarted &&
             !processResult.aborted &&
             !processResult.timedOut &&
-            prepared.executionPlan.commandInfo.command !== "batch" &&
-            isUnverifiedPageTransitionCommand(prepared.executionPlan.commandInfo.command, prepared.executionPlan.commandInfo.subcommand)) {
+            !nestedBatchClosed &&
+            (destinationTransition || (prepared.executionPlan.commandInfo.command !== "batch" &&
+                isUnverifiedPageTransitionCommand(prepared.executionPlan.commandInfo.command, prepared.executionPlan.commandInfo.subcommand)))) {
             navigationSummary = await collectNavigationSummary({ cwd, namespace: prepared.executionPlan.namespace, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName, signal });
-            // A failed transition command can still have mutated or replaced the document before throwing, so
-            // keeping the verified URL must not keep the prior snapshot refs (markTabTargetUnknown dropped
-            // them before this probe existed); invalidate so the next ref use requires a fresh snapshot.
+            // Re-verifying a failed transition's URL does not make its prior refs valid.
             failedTransitionReverification = navigationSummary !== undefined;
         }
         if (navigationSummary && presentationEnvelope && prepared.executionPlan.commandInfo.command !== "eval" && !Array.isArray(presentationEnvelope.data))
@@ -309,8 +317,9 @@ export async function processBrowserOutput(input) {
         const safeObservedSessionTabTarget = observedSessionTabTarget;
         let currentSessionTabTarget = safeObservedSessionTabTarget;
         if (!currentSessionTabTarget && nestedBatchClose === undefined) {
+            // Window/diff responses do not report the final URL; URL2 is intent, not redirect evidence.
             currentSessionTabTarget = resultingPageState.pageTargetMayHaveChanged
-                ? succeeded ? normalizeSessionTabTarget({ url: resultingPageState.currentPageUrl }) : undefined
+                ? succeeded && !destinationTransition ? normalizeSessionTabTarget({ url: resultingPageState.currentPageUrl }) : undefined
                 : deriveSessionTabTarget({ command: prepared.executionPlan.commandInfo.command, data: presentationEnvelope?.data, navigationSummary, previousTarget: prepared.priorSessionTabTarget, subcommand: prepared.executionPlan.commandInfo.subcommand });
         }
         let aboutBlankSessionMismatch;
@@ -318,7 +327,8 @@ export async function processBrowserOutput(input) {
         let electronRefFreshnessDiagnostic;
         let electronSessionMismatch;
         let electronStatusAfterCommand;
-        const shouldTreatAboutBlankAsMismatch = succeeded && !tabTransition && nestedBatchClose === undefined && prepared.priorSessionTabTarget !== undefined && !isAboutBlankSessionTabTarget(prepared.priorSessionTabTarget) && isAboutBlankSessionTabTarget(observedSessionTabTarget ?? currentSessionTabTarget) && !commandExplicitlyTargetsAboutBlank(prepared.commandTokens);
+        const explicitlyTargetsAboutBlank = dispatchedCommands.some((step) => commandExplicitlyTargetsAboutBlank(extractUpstreamCommandTokens(step)));
+        const shouldTreatAboutBlankAsMismatch = succeeded && !tabTransition && !destinationTransition && !explicitlyTargetsAboutBlank && nestedBatchClose === undefined && prepared.priorSessionTabTarget !== undefined && !isAboutBlankSessionTabTarget(prepared.priorSessionTabTarget) && isAboutBlankSessionTabTarget(observedSessionTabTarget ?? currentSessionTabTarget);
         let sessionTabCorrection = prepared.sessionTabCorrection;
         if (shouldTreatAboutBlankAsMismatch && prepared.priorSessionTabTarget) {
             const aboutBlankObservedTarget = observedSessionTabTarget ?? currentSessionTabTarget;
@@ -536,7 +546,7 @@ export async function processBrowserOutput(input) {
         if (sessionStateKey && succeeded) {
             if (openResultTabCorrection || sessionTabCorrection || aboutBlankSessionMismatch?.recoveryApplied)
                 sessionPageState.markPinning(sessionStateKey, "drift");
-            else if (prepared.sessionTabPinningReason === "restore")
+            else if (prepared.sessionTabPinningReason === "restore" && observedSessionTabTarget)
                 sessionPageState.clearRestorePinning(sessionStateKey);
         }
         if (replacedManagedSessionName) {
@@ -626,14 +636,25 @@ export async function processBrowserOutput(input) {
                 electronLaunchRecord = electronFailedConnectCleanup.record;
             }
         }
-        let errorText = getAgentBrowserErrorText({ aborted: processResult.aborted, command: prepared.executionPlan.commandInfo.command, effectiveArgs: prepared.redactedProcessArgs, envelope: presentationEnvelope, exitCode: processResult.exitCode, parseError, plainTextInspection, staleRefArgs: getStaleRefArgs(prepared.commandTokens, prepared.runtimeToolStdin), spawnError: processResult.spawnError, stderr: processResult.stderr, timedOut: processResult.timedOut, timeoutMs: processResult.timeoutMs, wrapperRecoveryHint: buildWrapperRecoveryHint({ pinnedBatchUnwrapMode: prepared.pinnedBatchUnwrapMode, sessionTabCorrection }) });
+        let errorText = getAgentBrowserErrorText({ aborted: processResult.aborted, command: prepared.executionPlan.commandInfo.command, effectiveArgs: prepared.redactedProcessArgs, envelope: presentationEnvelope, exitCode: processResult.exitCode, parseError, plainTextInspection, staleRefArgs: getStaleRefArgs(prepared.commandTokens, prepared.runtimeToolStdin), spawnError: processResult.spawnError, stderr: processResult.stderr, timedOut: processResult.timedOut, timeoutMs: processResult.timeoutMs, wrapperRecoveryHint: buildWrapperRecoveryHint({ sessionTabCorrection }) });
+        if (errorText && presentationEnvelope?.success === false && extractEnvelopeErrorText(presentationEnvelope.error) === undefined)
+            presentationEnvelope = { ...presentationEnvelope, error: errorText };
         if (errorText) {
             const clipboardWritePayloadCandidates = getClipboardWritePayloadCandidates(prepared.commandTokens);
             errorText = redactClipboardPermissionEcho(prepared.executionPlan.commandInfo, errorText);
             if (presentationEnvelope?.error !== undefined)
                 presentationEnvelope = { ...presentationEnvelope, error: redactClipboardPermissionErrorValue(prepared.executionPlan.commandInfo, presentationEnvelope.error, clipboardWritePayloadCandidates) };
         }
-        const presentation = plainTextInspection ? { artifacts: undefined, batchFailure: undefined, batchSteps: undefined, content: [{ type: "text", text: inspectionText ?? "" }], data: undefined, fullOutputPath: undefined, fullOutputPaths: undefined, imagePath: undefined, imagePaths: undefined, savedFile: undefined, savedFilePath: undefined, summary: `${prepared.redactedArgs.join(" ")} completed` } : await buildToolPresentation({ args: prepared.redactedProcessArgs, artifactManifest, artifactMaxUpdatedAtMs: Date.now(), artifactMinUpdatedAtMs: input.artifactRunStartedAtMs, artifactRequest: screenshotArtifactRequest, batchArtifactRequests: batchScreenshotArtifactRequests, commandInfo: prepared.executionPlan.commandInfo, compiledSemanticAction: prepared.compiledSemanticAction, cwd, envelope: presentationEnvelope, errorText, namespace: prepared.executionPlan.namespace, networkRouteDiagnostics, networkRoutes: activeNetworkRoutes, persistentArtifactStore, sessionName: prepared.executionPlan.sessionName });
+        if (plainTextUpgrade && errorText)
+            presentationEnvelope = { ...presentationEnvelope, success: false, error: errorText };
+        let presentation = plainTextInspection ? { artifacts: undefined, batchFailure: undefined, batchSteps: undefined, content: [{ type: "text", text: inspectionText ?? "" }], data: undefined, fullOutputPath: undefined, fullOutputPaths: undefined, imagePath: undefined, imagePaths: undefined, savedFile: undefined, savedFilePath: undefined, summary: `${prepared.redactedArgs.join(" ")} completed` } : await buildToolPresentation({ args: prepared.redactedProcessArgs, artifactManifest, artifactMaxUpdatedAtMs: Date.now(), artifactMinUpdatedAtMs: input.artifactRunStartedAtMs, artifactRequest: screenshotArtifactRequest, batchArtifactRequests: batchScreenshotArtifactRequests, commandInfo: prepared.executionPlan.commandInfo, compiledSemanticAction: prepared.compiledSemanticAction, cwd, envelope: presentationEnvelope, errorText, namespace: prepared.executionPlan.namespace, networkRouteDiagnostics, networkRoutes: activeNetworkRoutes, persistentArtifactStore, sessionName: prepared.executionPlan.sessionName });
+        if (plainTextUpgrade && !succeeded && typeof presentationEnvelope?.data === "string") {
+            presentation.data = presentationEnvelope.data;
+            const errorContent = presentation.content[0];
+            if (errorContent?.type === "text" && presentationEnvelope.data)
+                errorContent.text += `\n\n${presentationEnvelope.data}`;
+            presentation = await compactLargePresentationOutput({ artifactManifest, commandInfo: prepared.executionPlan.commandInfo, data: presentation.data, persistentArtifactStore, presentation });
+        }
         if (electronHandoff?.error && electronHandoff.failureCategory)
             presentation.failureCategory = electronHandoff.failureCategory;
         networkRoutesBySession = applyBatchNetworkRouteState({ data: presentationEnvelope?.data, routesBySession: networkRoutesBySession, sessionName: sessionStateKey, succeeded });
@@ -738,7 +759,14 @@ export async function processBrowserOutput(input) {
         const evalResultWarning = getEvalResultWarning({ command: prepared.executionPlan.commandInfo.command, data: presentationEnvelope?.data, navigationSummary: evalNavigationSummary, pageUrl: evalPageUrl, stdin: prepared.runtimeToolStdin });
         const resultArtifactManifest = presentation.artifactManifest ?? artifactManifest;
         const artifactCleanup = await getArtifactCleanupGuidance({ command: prepared.executionPlan.commandInfo.command, cwd, manifest: resultArtifactManifest, succeeded });
-        const warningText = electronPostCommandHealth ? formatElectronPostCommandHealthText(electronPostCommandHealth) : electronSessionMismatch ? formatElectronSessionMismatchText(electronSessionMismatch) : aboutBlankSessionMismatch ? buildAboutBlankWarning(aboutBlankSessionMismatch) : undefined;
+        const recordingTransitionReached = prepared.executionPlan.commandInfo.command === "batch"
+            ? presentation.batchSteps?.some((step) => isRecordPageTransitionCommand(extractUpstreamCommandTokens(step.command ?? [])))
+            : isRecordPageTransitionCommand(prepared.commandTokens);
+        const recordingPageWarning = processResult.agentBrowserStarted && !prepared.executionPlan.plainTextInspection && recordingTransitionReached
+            ? "Page state: this recording command can replace or navigate the active page, even on failure; prior in-page DOM and JavaScript state may not carry over. Take a fresh snapshot before continuing with page-scoped refs."
+            : undefined;
+        const sessionWarning = electronPostCommandHealth ? formatElectronPostCommandHealthText(electronPostCommandHealth) : electronSessionMismatch ? formatElectronSessionMismatchText(electronSessionMismatch) : aboutBlankSessionMismatch ? buildAboutBlankWarning(aboutBlankSessionMismatch) : undefined;
+        const warningText = [sessionWarning, recordingPageWarning].filter(Boolean).join("\n\n") || undefined;
         const redactedContent = buildRedactedPresentationContent({ exactSensitiveValues: prepared.exactSensitiveValues, plainTextInspection, presentation, presentationEnvelope, succeeded, userRequestedJson: prepared.userRequestedJson, warningText });
         const finalRecoveryState = await prepareFinalResultRecoveryState({ aboutBlankSessionMismatch, batchRefSnapshotState, commandTokens: prepared.commandTokens, compiledSemanticAction: prepared.compiledSemanticAction, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, cwd, electronPostCommandHealth, errorText, executionPlan: prepared.executionPlan, parseError, plainTextInspection, presentation, processResult, redactedProcessArgs: prepared.redactedProcessArgs, runtimeToolArgs: prepared.runtimeToolArgs, sessionPageState, sessionPageStateUpdate, sessionTabCorrection, signal, succeeded });
         currentRefSnapshot = finalRecoveryState.currentRefSnapshot;

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

@@ -1,15 +1,17 @@
 import { rm } from "node:fs/promises";
-import { getAgentBrowserSessionIdentityKey, VALUE_FLAGS } from "../../argv-grammar.js";
+import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { needsManagedSession } from "../../command-policy.js";
 import { runAgentBrowserProcess } from "../../process.js";
 import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
 import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { buildNextToolAction, withOptionalNamespaceArgs, withOptionalSessionArgs } from "../../results/next-actions.js";
-import { getSessionPageStateKey, isAboutBlankUrl, normalizeComparableUrl, normalizeSessionTabTarget, targetsMatch, } from "../../session-page-state.js";
-import { isCloseCommand, isElectronPostCommandHealthCommand, isNavigationObservableCommandName, isRefGuardedCommand, isRefInvalidatingBatchCommand, isSessionTabPinningExcludedCommand, isSessionTabPostCommandCorrectionExcludedCommand, } from "../../command-taxonomy.js";
+import { getSessionPageStateKey, isAboutBlankUrl, normalizeComparableUrl, targetsMatch, } from "../../session-page-state.js";
+import { isCloseCommand, isElectronPostCommandHealthCommand, isNavigationObservableCommandName, isOpenNavigationCommand, isRefGuardedCommand, isRefInvalidatingBatchCommand, isRecordPageTransitionCommand, isSessionTabPinningExcludedCommand, isSessionTabPostCommandCorrectionExcludedCommand, isWindowOrDiffPageTransitionCommand, } from "../../command-taxonomy.js";
 import { chooseOpenResultTabCorrection } from "../../runtime.js";
-import { isRecord } from "../../parsing.js";
-import { getUpstreamEffectiveBatchSteps, parseUserBatchStdin } from "../batch-stdin.js";
-export const NAVIGATION_SUMMARY_EVAL = `({ title: document.title, url: location.href })`;
+import { isRecord, parseRefId } from "../../parsing.js";
+import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
+import { findFirstPositionalArgument } from "./prepare/wait-timeouts.js";
 export function applyBrowserRunStatePatch(state, patch) {
     if (!patch)
         return;
@@ -278,39 +280,57 @@ export function getStaleRefArgs(commandTokens, stdin) {
     const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
     return steps.length > 0 ? steps.flatMap((step) => step) : commandTokens;
 }
-// Selector-carrying flags whose values remain page-scoped refs; values of other value-taking flags
-// (--text, --baseline, --name, and similar) are literal text or paths that may merely look like refs,
-// per upstream parsing. Boolean flags such as --new-tab or --full do not consume the following token,
-// so a ref after them is a genuine positional selector and must stay guarded.
-const SELECTOR_FLAG_TOKENS = new Set(["--selector", "-s"]);
-const SHORT_VALUE_FLAG_TOKENS = new Set(["-b", "-o", "-t"]);
-function isNonSelectorValueFlagToken(token) {
-    if (token === undefined || SELECTOR_FLAG_TOKENS.has(token))
-        return false;
-    return VALUE_FLAGS.has(token) || SHORT_VALUE_FLAG_TOKENS.has(token);
-}
+// Inspect only upstream's selector slots: fill text, file paths and key data are not refs.
 function collectRefsFromTokens(tokens) {
-    const refs = [];
-    for (const [index, token] of tokens.entries()) {
-        if (!/^@e\d+\b/.test(token))
-            continue;
-        if (isNonSelectorValueFlagToken(index > 0 ? tokens[index - 1] : undefined))
-            continue;
-        refs.push(token.slice(1));
+    if (!isRefGuardedCommand(tokens[0]) || (tokens[0] === "diff" && tokens[1] !== "screenshot"))
+        return [];
+    let selectors;
+    switch (tokens[0]) {
+        case "click":
+            selectors = [tokens.slice(1).find((token) => token !== "--new-tab")];
+            break;
+        case "drag":
+            selectors = tokens.slice(1, 3);
+            break;
+        case "get":
+            selectors = [!["url", "title", "cdp-url", "count"].includes(tokens[1]) ? tokens[2] : undefined];
+            break;
+        case "is":
+            selectors = [tokens[2]];
+            break;
+        case "screenshot":
+            selectors = [tokens.slice(1).find((token) => !["--full", "-f"].includes(token))];
+            break;
+        case "diff":
+        case "scroll": {
+            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;
+            }
+            selectors = [selector];
+            break;
+        }
+        default: selectors = [tokens[1]];
     }
-    return refs;
+    return selectors.flatMap((selector) => {
+        const ref = selector === undefined ? undefined : parseRefId(selector);
+        return ref === undefined ? [] : [ref];
+    });
 }
 export function getGuardedRefUsage(commandTokens, stdin, options = {}) {
-    const collectFromStep = (step) => isRefGuardedCommand(step[0]) ? collectRefsFromTokens(step) : [];
     if (commandTokens[0] !== "batch") {
-        return collectFromStep(commandTokens);
+        return collectRefsFromTokens(commandTokens);
     }
     const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
     const refsBeforeInBatchSnapshot = [];
     for (const step of steps) {
         if (!options.includeRefsAfterBatchSnapshot && (step[0] ?? "") === "snapshot")
             break;
-        refsBeforeInBatchSnapshot.push(...collectFromStep(step));
+        refsBeforeInBatchSnapshot.push(...collectRefsFromTokens(step));
     }
     return refsBeforeInBatchSnapshot;
 }
@@ -395,61 +415,41 @@ export function buildStaleRefPreflight(options) {
     }
     return undefined;
 }
-function supportsPinnedStdinCommand(options) {
-    if (options.command === "batch") {
-        return options.stdin !== undefined;
-    }
-    if (options.stdin === undefined) {
-        return true;
-    }
-    if (options.command === "eval") {
-        return options.commandTokens.includes("--stdin");
-    }
-    return false;
+export function commandChoosesSessionTabTarget(args) {
+    const tokens = parseArgvDescriptor(args).upstreamCommandTokens;
+    const [command, subcommand] = tokens;
+    return isOpenNavigationCommand(command) || isCloseCommand(command) || command === "connect"
+        || (command === "state" && subcommand === "load")
+        || (command === "tab" && subcommand !== undefined && subcommand !== "list")
+        || isWindowOrDiffPageTransitionCommand(command, subcommand)
+        || (command === "a11y" && findFirstPositionalArgument(tokens) !== undefined)
+        || (["vitals", "web-vitals"].includes(command) && tokens.slice(1).some((token) => !token.startsWith("--")))
+        || (isRecordPageTransitionCommand(tokens) && tokens[3] !== undefined);
 }
 export function shouldPinSessionTabForCommand(options) {
-    return (options.pinningRequired === true &&
-        options.sessionName !== undefined &&
-        options.command !== undefined &&
-        !isSessionTabPinningExcludedCommand(options.command) &&
-        supportsPinnedStdinCommand(options));
-}
-export function buildPinnedBatchPlan(options) {
-    if (options.command === "batch") {
-        const tabSelectionStep = ["tab", options.selectedTab];
-        // Upstream executes raw argument steps exclusively when any exist, so the
-        // pinned rewrite must dispatch those same steps rather than resurrecting
-        // caller stdin the guard never scanned.
-        const argumentSteps = getUpstreamEffectiveBatchSteps(options.commandTokens, undefined);
-        if (argumentSteps.length > 0) {
-            return {
-                includeNavigationSummary: false,
-                steps: [tabSelectionStep, ...argumentSteps],
-                unwrapMode: "user-batch",
-            };
-        }
-        const parsed = parseUserBatchStdin(options.stdin);
-        if (parsed.error) {
-            return { error: parsed.error };
-        }
-        return {
-            includeNavigationSummary: false,
-            steps: [tabSelectionStep, ...(parsed.steps ?? [])],
-            unwrapMode: "user-batch",
-        };
-    }
-    if (options.commandTokens.length === 0) {
-        return undefined;
+    if (!options.pinningRequired || !options.sessionName || !options.command)
+        return false;
+    const steps = options.command === "batch" ? getUpstreamEffectiveBatchSteps(options.commandTokens, options.stdin) : [options.commandTokens];
+    for (const step of steps) {
+        const descriptor = parseArgvDescriptor(step);
+        const tokens = descriptor.upstreamCommandTokens;
+        const [command, subcommand] = tokens;
+        // A later page action uses the explicit destination, not the remembered tab.
+        if (commandChoosesSessionTabTarget(tokens))
+            return false;
+        if (!needsManagedSession(descriptor) || isSessionTabPinningExcludedCommand(command))
+            continue;
+        if (command === "get" && subcommand === "url" && !options.reopenPending)
+            continue;
+        if (command === "read" && findFirstPositionalArgument(tokens) !== undefined)
+            continue;
+        if (["console", "errors"].includes(command))
+            continue;
+        if (command === "network" && !(subcommand === "requests" && tokens.some((token) => ["--current-page", "--current-origin", "--current-url"].includes(token))))
+            continue;
+        return true;
     }
-    const includeNavigationSummary = isNavigationObservableCommandName(options.command, options.commandTokens[1]);
-    const tabSelectionStep = ["tab", options.selectedTab];
-    const commandStep = options.commandTokens;
-    const navigationSummarySteps = includeNavigationSummary ? [["eval", NAVIGATION_SUMMARY_EVAL]] : [];
-    return {
-        includeNavigationSummary,
-        steps: [tabSelectionStep, commandStep, ...navigationSummarySteps],
-        unwrapMode: "single-command",
-    };
+    return false;
 }
 export function shouldCorrectSessionTabAfterCommand(options) {
     return (options.pinningRequired === true &&
@@ -477,59 +477,11 @@ function selectAnySessionTargetTab(options) {
         return undefined;
     const matchingTabs = options.tabs.filter((tab) => normalizeComparableUrl(tab.url ?? "") === targetUrl);
     const targetTitle = options.target.title?.trim() ?? "";
-    const selectedTab = (targetTitle ? matchingTabs.find((tab) => tab.title?.trim() === targetTitle) : undefined) ?? matchingTabs[0];
+    const titledTabs = targetTitle ? matchingTabs.filter((tab) => tab.title?.trim() === targetTitle) : [];
+    const selectedTab = titledTabs.find((tab) => tab.active) ?? titledTabs[0] ?? matchingTabs.find((tab) => tab.active) ?? matchingTabs[0];
     const selection = selectedTab ? getTabSelection(selectedTab) : undefined;
     return selection ? { ...selection, ...(targetTitle ? { targetTitle } : {}), targetUrl } : undefined;
 }
-export function unwrapPinnedSessionBatchEnvelope(options) {
-    if (!options.envelope) {
-        return {};
-    }
-    if (!Array.isArray(options.envelope.data)) {
-        return {
-            parseError: "agent-browser returned an unexpected response while applying the wrapper's tab-pinning batch.",
-        };
-    }
-    const steps = options.envelope.data.filter(isRecord);
-    const tabSelectionStep = steps[0];
-    const commandStep = steps[1];
-    if (tabSelectionStep?.success === false) {
-        return {
-            envelope: {
-                success: false,
-                error: tabSelectionStep.error ?? "agent-browser could not re-select the intended tab before running the command.",
-            },
-        };
-    }
-    if (options.mode === "user-batch") {
-        const userSteps = steps.slice(1);
-        return {
-            envelope: {
-                success: userSteps.every((step) => step.success !== false),
-                data: userSteps,
-                error: userSteps.find((step) => step.success === false)?.error,
-            },
-        };
-    }
-    if (!commandStep) {
-        return {
-            envelope: {
-                success: false,
-                error: "agent-browser did not return the corrected command result.",
-            },
-        };
-    }
-    const navigationSummaryStep = options.includeNavigationSummary ? steps[2] : undefined;
-    const navigationSummary = normalizeSessionTabTarget(extractNavigationSummaryFromData(navigationSummaryStep?.result));
-    return {
-        envelope: {
-            success: commandStep.success !== false,
-            data: commandStep.result,
-            error: commandStep.success === false ? commandStep.error : undefined,
-        },
-        navigationSummary,
-    };
-}
 export async function runSessionCommandData(options) {
     const { args, cwd, namespace, pinNamespace, sessionName, signal, stdin, throwOnFailure, timeoutMs } = options;
     if (!sessionName)
@@ -542,6 +494,7 @@ export async function runSessionCommandData(options) {
         timeoutMs,
     });
     try {
+        options.onProcessResult?.(processResult);
         if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
             if (throwOnFailure) {
                 const reason = processResult.aborted
@@ -604,11 +557,23 @@ export async function collectSessionTabSelection(options) {
     const tabs = mapTabData(tabData);
     return tabs ? selectSessionTargetTab({ tabs, target }) : undefined;
 }
-export async function collectAnySessionTabSelection(options) {
-    const { cwd, namespace, sessionName, signal, target } = options;
-    const tabData = await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal });
-    const tabs = mapTabData(tabData);
-    return tabs ? selectAnySessionTargetTab({ tabs, target }) : undefined;
+export async function ensureSessionTabTarget(options) {
+    const readTabs = async () => mapTabData(await runSessionCommandData({ ...options, args: ["tab", "list"] }));
+    const tabs = await readTabs();
+    const active = tabs?.find((tab) => tab.active);
+    const correction = tabs && selectAnySessionTargetTab({ tabs, target: options.target });
+    const 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.";
+    if (!correction)
+        return { error };
+    // Native tab selection clears refs and frame scope even when selecting the current tab.
+    if (active && getTabSelection(active)?.selectedTab === correction.selectedTab)
+        return {};
+    if (!await applyOpenResultTabCorrection({ ...options, correction }))
+        return { correction, error };
+    const selected = (await readTabs())?.find((tab) => tab.active);
+    return selected && getTabSelection(selected)?.selectedTab === correction.selectedTab && normalizeComparableUrl(selected.url ?? "") === normalizeComparableUrl(options.target.url)
+        ? { correction }
+        : { correction, error };
 }
 export async function applyOpenResultTabCorrection(options) {
     const { correction, cwd, namespace, sessionName, signal } = options;

package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js

@@ -174,7 +174,9 @@ function formatElectronStatusVisibleText(statuses, records, mismatches = [], man
         const sessionName = record?.sessionName;
         const appName = record?.appName ?? "Electron launch";
         const sessionText = sessionName ? `, sessionName ${sessionName}` : "";
-        lines.push(`- ${status.launchId}: ${appName}${sessionText}; ${status.portAlive ? "debug port alive" : "debug port dead"}${status.pidAlive === undefined ? "" : status.pidAlive ? ", pid alive" : ", pid dead"} (port ${status.port})`);
+        const historyText = status.cleanupState === "cleaned" ? "; historical cleaned launch record" : "";
+        lines.push(`- ${status.launchId}: ${appName}${sessionText}${historyText}; ${status.portAlive ? "debug port alive" : "debug port dead"}${status.pidAlive === undefined ? "" : status.pidAlive ? ", pid alive" : ", pid dead"} (port ${status.port})`);
+        lines.push(`  Tracked profile path: ${status.userDataDirState}.`);
         lines.push(`  Identifiers: launchId ${status.launchId}; sessionName ${sessionName ?? "not attached"}.`);
         for (const targetLine of formatElectronTargetLines(status.targets, 4))
             lines.push(`  ${targetLine}`);

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

@@ -114,7 +114,9 @@ export function resolveAgentBrowserInput(options) {
     const timeoutMsError = params.timeoutMs !== undefined && (typeof params.timeoutMs !== "number" || !Number.isSafeInteger(params.timeoutMs) || params.timeoutMs <= 0)
         ? "timeoutMs must be a positive integer when provided."
         : compiledElectron && params.timeoutMs !== undefined
-            ? "Use electron.timeoutMs for electron actions; top-level timeoutMs applies only to browser CLI subprocess calls."
+            ? compiledElectron.action === "list"
+                ? "electron.list has no configurable timeout; remove top-level timeoutMs."
+                : "Use electron.timeoutMs for this action; top-level timeoutMs applies only to browser CLI subprocess calls."
             : compiledScript && params.timeoutMs !== undefined && params.timeoutMs > AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS
                 ? `script timeoutMs must be ${AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS} or less.`
                 : undefined;

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

@@ -38,6 +38,10 @@ function getExplicitNavigationTarget(args) {
         return positionals[0];
     if (descriptor.commandInfo.command === "tab" && descriptor.commandInfo.subcommand === "new")
         return positionals[1];
+    if (descriptor.commandInfo.command === "window" && descriptor.commandInfo.subcommand === "new")
+        return "about:blank";
+    if (descriptor.commandInfo.command === "diff" && descriptor.commandInfo.subcommand === "url")
+        return descriptor.upstreamCommandTokens[3];
     return undefined;
 }
 function getResultingExplicitNavigationTarget(args, currentPageUrl) {
@@ -149,17 +153,11 @@ export function getResultingPageTargetState(options) {
             || isUnverifiedPageTransitionCommand(descriptor.commandInfo.command, descriptor.commandInfo.subcommand);
         return { ...getResultingPageState({ ...state, args: options.args, trustedBatchTabSelection: false }), pageTargetMayHaveChanged };
     }
-    const batch = getBatchCommandSteps(options.args, options.stdin);
-    if (batch.error)
-        return { pageTargetMayHaveChanged: true, pageUrlUnknown: true };
-    for (let index = 0; index < batch.steps.length; index += 1) {
-        const step = batch.steps[index];
-        const trustedBatchTabSelection = options.trustedFirstBatchTabSelection === true && index === 0;
+    for (const step of options.executedBatchSteps) {
         const stepDescriptor = parseArgvDescriptor(step);
         pageTargetMayHaveChanged ||= getExplicitNavigationTarget(step) !== undefined
-            || (isUnverifiedPageTransitionCommand(stepDescriptor.commandInfo.command, stepDescriptor.commandInfo.subcommand)
-                && !(trustedBatchTabSelection && stepDescriptor.commandInfo.command === "tab"));
-        state = getResultingPageState({ ...state, args: step, trustedBatchTabSelection });
+            || isUnverifiedPageTransitionCommand(stepDescriptor.commandInfo.command, stepDescriptor.commandInfo.subcommand);
+        state = getResultingPageState({ ...state, args: step, trustedBatchTabSelection: false });
     }
     return { ...state, pageTargetMayHaveChanged };
 }
@@ -189,6 +187,9 @@ export function getPageTargetValidationError(options) {
     if (["close", "exit", "quit"].includes(command ?? ""))
         return undefined;
     if (command === "batch") {
+        if (descriptor.upstreamCommandTokens.slice(1).some((token) => token.startsWith("--bail="))) {
+            return "Use exact batch --bail for fail-fast, or omit it to continue after errors. --bail=<value> is a raw command upstream; stdin is ignored when raw batch arguments are present.";
+        }
         const batch = getBatchCommandSteps(options.args, options.stdin);
         if (batch.error)
             return batch.error.startsWith("agent_browser batch stdin") || batch.error === NESTED_BATCH_ARGUMENT_MESSAGE
@@ -262,7 +263,6 @@ export function getExplicitSessionPageVerificationRequirement(options) {
         pageUrlUnknown: true,
         stdin: options.stdin,
         allowUnverifiedPageTransitions: true,
-        trustedFirstBatchTabSelection: options.trustedFirstBatchTabSelection,
     });
     return validationError === UNVERIFIED_PAGE_MESSAGE || validationError === BATCH_UNVERIFIED_PAGE_MESSAGE || validationError === NON_BAIL_BATCH_NAVIGATION_MESSAGE
         ? UNVERIFIED_PAGE_MESSAGE

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

@@ -1,6 +1,13 @@
 export function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
+/** Upstream native element::parse_ref accepts @eN, ref=eN and bare eN. */
+export function parseRefId(selector) {
+    const trimmed = selector.trim();
+    const prefixed = trimmed.startsWith("@") || trimmed.startsWith("ref=");
+    const candidate = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+    return (prefixed ? /^e\d*$/ : /^e\d+$/).test(candidate) ? candidate : undefined;
+}
 export function parsePositiveInteger(rawValue) {
     if (typeof rawValue !== "string")
         return undefined;