pi-agent-browser-native 0.5.0 → 0.6.5

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

@@ -2,6 +2,7 @@ import { isRecord } from "../../../parsing.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { buildSnapshotPresentation } from "../../../results/snapshot.js";
 import { extractRefSnapshotFromData } from "../../../session-page-state.js";
+import { redactSensitiveText } from "../../../runtime.js";
 import { collectScrollPositionSnapshot } from "../diagnostics.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
 function parseSnapshotFilterRequest(commandTokens) {
@@ -42,6 +43,116 @@ function parseSnapshotFilterRequest(commandTokens) {
         return undefined;
     return { cleanArgs, diff, role, search, viewport };
 }
+const RENDERED_TEXT_SEARCH_MAX_MATCHES = 8;
+function buildRenderedTextSearchEval(search) {
+    return `(() => {
+  const query = ${JSON.stringify(search.trim().toLowerCase())};
+  const limit = ${RENDERED_TEXT_SEARCH_MAX_MATCHES};
+  const normalize = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
+  const attributeTextOf = (element) => [element.getAttribute("aria-label"), element.getAttribute("title"), element.getAttribute("placeholder")].filter(Boolean).join(" ");
+  const searchableTextOf = (element) => normalize([attributeTextOf(element), element.textContent].filter(Boolean).join(" "));
+  const renderedTextOf = (element) => normalize([attributeTextOf(element), element instanceof HTMLElement ? element.innerText : element.textContent].filter(Boolean).join(" "));
+  const isRendered = (element) => {
+    if (!(element instanceof Element) || element.getClientRects().length === 0) return false;
+    const visibility = getComputedStyle(element).visibility;
+    if (visibility === "hidden" || visibility === "collapse") return false;
+    for (let current = element; current; current = current.parentElement) {
+      if (Number(getComputedStyle(current).opacity) === 0) return false;
+    }
+    return true;
+  };
+  const validationPattern = /(?:^|[-_\\s])(?:error|invalid|validation|warning)(?:$|[-_\\s])/i;
+  const validationAncestor = (element) => {
+    for (let current = element; current && current !== document.body; current = current.parentElement) {
+      const role = current.getAttribute("role");
+      const live = current.getAttribute("aria-live");
+      const descriptor = [current.id, current.className, current.getAttribute("data-testid")].map(normalize).join(" ");
+      if (["alert", "alertdialog", "status"].includes(role || "") || current.getAttribute("aria-invalid") === "true" || (live && live !== "off") || validationPattern.test(descriptor)) return current;
+    }
+    return null;
+  };
+  const candidates = Array.from(document.querySelectorAll("body *")).filter((element) => searchableTextOf(element).toLowerCase().includes(query));
+  const candidateSet = new Set(candidates);
+  const minimal = candidates.filter((element) => !Array.from(element.children).some((child) => candidateSet.has(child)));
+  const rendered = minimal.filter((element) => isRendered(element) && renderedTextOf(element).toLowerCase().includes(query));
+  const matches = rendered.map((element, index) => {
+    const semantic = validationAncestor(element);
+    const source = semantic || element;
+    const text = renderedTextOf(element);
+    const matchIndex = text.toLowerCase().indexOf(query);
+    const start = Math.max(0, matchIndex - 80);
+    const snippet = text.slice(start, start + 240);
+    const rect = element.getBoundingClientRect();
+    const name = normalize(element.getAttribute("aria-label") || element.getAttribute("title") || element.getAttribute("placeholder")) || undefined;
+    return {
+      index,
+      kind: semantic ? "validation" : "text",
+      name,
+      offscreen: rect.bottom < 0 || rect.right < 0 || rect.top > innerHeight || rect.left > innerWidth,
+      role: source.getAttribute("role") || undefined,
+      tagName: element.tagName.toLowerCase(),
+      text: snippet,
+    };
+  }).sort((left, right) => (left.kind === right.kind ? left.index - right.index : left.kind === "validation" ? -1 : 1));
+  const unique = [];
+  const seen = new Set();
+  for (const match of matches) {
+    const key = [match.kind, match.role, match.name, match.text].join("\\n");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const { index, ...visible } = match;
+    unique.push(visible);
+  }
+  return { matches: unique.slice(0, limit), totalMatches: unique.length, truncated: unique.length > limit };
+})()`;
+}
+function extractRenderedTextSearchResult(data) {
+    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
+    if (!isRecord(result) || !Array.isArray(result.matches))
+        return undefined;
+    const matches = result.matches.flatMap((value) => {
+        if (!isRecord(value) || (value.kind !== "text" && value.kind !== "validation") || typeof value.offscreen !== "boolean" || typeof value.tagName !== "string" || typeof value.text !== "string")
+            return [];
+        return [{
+                kind: value.kind,
+                ...(typeof value.name === "string" ? { name: redactSensitiveText(value.name) } : {}),
+                offscreen: value.offscreen,
+                ...(typeof value.role === "string" ? { role: value.role } : {}),
+                tagName: value.tagName,
+                text: redactSensitiveText(value.text),
+            }];
+    }).slice(0, RENDERED_TEXT_SEARCH_MAX_MATCHES);
+    const totalMatches = typeof result.totalMatches === "number" && Number.isInteger(result.totalMatches) && result.totalMatches >= matches.length ? result.totalMatches : matches.length;
+    return { matches, totalMatches, truncated: result.truncated === true || totalMatches > matches.length };
+}
+function attachRenderedTextMatchRefs(matches, snapshotData) {
+    if (!isRecord(snapshotData) || !isRecord(snapshotData.refs))
+        return matches;
+    const refs = snapshotData.refs;
+    return matches.map((match) => {
+        if (!match.name)
+            return match;
+        const normalizedName = match.name.replace(/\s+/g, " ").trim().toLowerCase();
+        const candidates = Object.entries(refs).filter(([, value]) => {
+            if (!isRecord(value) || typeof value.name !== "string")
+                return false;
+            const nameMatches = value.name.replace(/\s+/g, " ").trim().toLowerCase() === normalizedName;
+            return nameMatches && (!match.role || typeof value.role !== "string" || value.role.toLowerCase() === match.role.toLowerCase());
+        });
+        return candidates.length === 1 ? { ...match, ref: candidates[0][0] } : match;
+    });
+}
+function formatRenderedTextSearchMatches(result) {
+    if (!result || result.matches.length === 0)
+        return undefined;
+    const lines = result.matches.map((match) => {
+        const context = [match.kind === "validation" ? "validation" : undefined, match.offscreen ? "outside viewport" : undefined, match.role, match.tagName, match.ref ? `@${match.ref}` : undefined].filter(Boolean).join(", ");
+        return `- ${JSON.stringify(match.text)}${context ? ` (${context})` : ""}`;
+    });
+    if (result.truncated)
+        lines.push(`- ... (${result.totalMatches - result.matches.length} additional rendered-text matches omitted)`);
+    return ["Rendered page text matches:", ...lines].join("\n");
+}
 function buildSnapshotDiff(previous, current) {
     if (!current)
         return undefined;
@@ -113,6 +224,11 @@ export async function trySnapshotFilter(options) {
     const filtered = request.role || request.search ? filterSnapshotData(snapshotData, request) : isRecord(snapshotData) ? { data: snapshotData, matchedRefs: isRecord(snapshotData.refs) ? Object.keys(snapshotData.refs).length : 0, totalLines: typeof snapshotData.snapshot === "string" ? snapshotData.snapshot.split(/\r?\n/).filter((line) => line.length > 0).length : 0, totalRefs: isRecord(snapshotData.refs) ? Object.keys(snapshotData.refs).length : 0, visibleLines: typeof snapshotData.snapshot === "string" ? snapshotData.snapshot.split(/\r?\n/).filter((line) => line.length > 0).length : 0 } : undefined;
     if (!filtered)
         return undefined;
+    const renderedTextSearch = request.search
+        ? extractRenderedTextSearchResult(await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildRenderedTextSearchEval(request.search) }))
+        : undefined;
+    if (renderedTextSearch)
+        renderedTextSearch.matches = attachRenderedTextMatchRefs(renderedTextSearch.matches, snapshotData);
     const viewport = request.viewport ? await collectScrollPositionSnapshot({ cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }) : undefined;
     const fullSnapshot = extractRefSnapshotFromData(snapshotData);
     const diff = request.diff ? buildSnapshotDiff(options.previousRefSnapshot, fullSnapshot) : undefined;
@@ -126,7 +242,8 @@ export async function trySnapshotFilter(options) {
             : "Snapshot viewport metadata collected.";
     const viewportText = viewport ? `Viewport: ${viewport.innerWidth}×${viewport.innerHeight}, scroll ${viewport.scrollX},${viewport.scrollY}, document ${viewport.scrollWidth}×${viewport.scrollHeight}, sampled scroll containers ${viewport.containers.length}/${viewport.containerCount}.` : undefined;
     const diffText = diff && (request.role || request.search) ? diff.summary : undefined;
-    const prefix = [summary, diffText, viewportText].filter((line) => line !== undefined).join("\n");
+    const renderedTextSearchText = formatRenderedTextSearchMatches(renderedTextSearch);
+    const prefix = [summary, renderedTextSearchText, diffText, viewportText].filter((line) => line !== undefined).join("\n\n");
     if (presentation.content[0]?.type === "text")
         presentation.content[0] = { ...presentation.content[0], text: `${prefix}\n\n${presentation.content[0].text}` };
     return {
@@ -146,7 +263,7 @@ export async function trySnapshotFilter(options) {
                 refSnapshot: fullSnapshot,
                 sessionMode: options.sessionMode,
                 snapshotDiff: diff,
-                snapshotFilter: request.role || request.search ? { cleanArgs: request.cleanArgs, matchedRefs: filtered.matchedRefs, role: request.role, search: request.search, totalLines: filtered.totalLines, totalRefs: filtered.totalRefs, visibleLines: filtered.visibleLines } : undefined,
+                snapshotFilter: request.role || request.search ? { cleanArgs: request.cleanArgs, matchedRefs: filtered.matchedRefs, renderedTextMatches: renderedTextSearch?.matches, renderedTextTotalMatches: renderedTextSearch?.totalMatches, renderedTextTruncated: renderedTextSearch?.truncated, role: request.role, search: request.search, totalLines: filtered.totalLines, totalRefs: filtered.totalRefs, visibleLines: filtered.visibleLines } : undefined,
                 snapshotViewport: viewport,
                 ...buildAgentBrowserResultCategoryDetails({ args: options.effectiveArgs, command: "snapshot", succeeded: true }),
                 ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession, options.namespace, options.managedSessionRestoreDisabled()),

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

@@ -1,7 +1,7 @@
 import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS } from "../../../argv-grammar.js";
 import { isOpenNavigationCommand } from "../../../command-taxonomy.js";
 import { getAgentBrowserProcessTimeoutMs } from "../../../process.js";
-import { parseValidBatchStepEntries } from "../../batch-stdin.js";
+import { getUpstreamEffectiveBatchSteps } from "../../batch-stdin.js";
 const POSITIONAL_VALUE_FLAGS = new Set([...VALUE_FLAGS, "--llms"]);
 const COMMAND_PROCESS_TIMEOUT_GRACE_MS = 5_000;
 function parseMillisecondsToken(token) {
@@ -12,7 +12,8 @@ function parseMillisecondsToken(token) {
     return Number.isSafeInteger(parsed) ? parsed : undefined;
 }
 function findCommandTimeoutMs(commandTokens) {
-    if (commandTokens[0] !== "wait" && commandTokens[0] !== "read")
+    const [command, subcommand] = commandTokens;
+    if (command !== "wait" && command !== "read" && !(command === "webmcp" && ["invoke", "result"].includes(subcommand ?? "")))
         return undefined;
     for (let index = 1; index < commandTokens.length; index += 1) {
         const token = commandTokens[index];
@@ -73,11 +74,11 @@ function findCommandTimeoutBudgetMs(commandTokens, stdin, activePageUrl) {
     const directTimeout = commandTimeoutBudgetMs(commandTokens, activePageUrl);
     if (directTimeout !== undefined)
         return directTimeout;
-    if (commandTokens[0] !== "batch" || stdin === undefined)
+    if (commandTokens[0] !== "batch")
         return undefined;
     let batchTimeoutTotal = 0;
     let batchPageUrl = activePageUrl;
-    for (const { step } of parseValidBatchStepEntries(stdin)) {
+    for (const step of getUpstreamEffectiveBatchSteps(commandTokens, stdin)) {
         batchTimeoutTotal += commandTimeoutBudgetMs(step, batchPageUrl) ?? 0;
         if (isOpenNavigationCommand(step[0]))
             batchPageUrl = findFirstPositionalArgument(step);
@@ -87,10 +88,10 @@ function findCommandTimeoutBudgetMs(commandTokens, stdin, activePageUrl) {
 export function commandTimeoutNeedsActivePageUrl(commandTokens, stdin) {
     if (commandTokens[0] === "read")
         return findCommandTimeoutMs(commandTokens) !== undefined && readUsesActivePageUrl(commandTokens);
-    if (commandTokens[0] !== "batch" || stdin === undefined)
+    if (commandTokens[0] !== "batch")
         return false;
     let hasKnownPageUrl = false;
-    for (const { step } of parseValidBatchStepEntries(stdin)) {
+    for (const step of getUpstreamEffectiveBatchSteps(commandTokens, stdin)) {
         if (isOpenNavigationCommand(step[0]) && findFirstPositionalArgument(step))
             hasKnownPageUrl = true;
         if (!hasKnownPageUrl && findCommandTimeoutMs(step) !== undefined && step[0] === "read" && readUsesActivePageUrl(step))

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

@@ -18,15 +18,15 @@ import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextAction
 import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData } from "../../session-page-state.js";
 import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createFreshSessionName, extractCommandTokens, extractUpstreamCommandTokens, getDefaultHeadlessCompatUserAgent, parseWaitCommandTokens, redactInvocationArgs, } from "../../runtime.js";
-import { buildOwnedManagedSessionRestoreContext, canonicalizeOwnedManagedSessionCloseArgs, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
+import { buildOwnedManagedSessionRestoreContext, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
-import { getCallerOwnedSessionLivePageVerificationRequirement, getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, } from "../../managed-session-state-policy.js";
+import { getExplicitSessionPageVerificationRequirement, getPageTargetValidationError, } from "../../page-target-validation.js";
 import { acquireOwnedManagedSessionDaemonPolicy, getRunningHeadedAutosavePolicyChangeError } from "./managed-session-daemon-policy.js";
 import { applyOpenResultTabCorrection, buildManagedSessionOutcome, buildPinnedBatchPlan, buildSessionDetailFields, buildStaleRefPreflight, getSessionContextKey, extractStringResultField, collectAnySessionTabSelection, collectSessionTabSelection, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
 import { getUpstreamEffectiveBatchSteps, parseBatchStdinJsonArray } from "../batch-stdin.js";
-import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
+import { buildElectronHostFailureResult, formatAgentBrowserNextActionsText, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
 import { prepareClickDispatchProbe } from "./click-dispatch.js";
-import { collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
+import { buildUnsupportedScrollIntoViewRecovery, collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
 import { getScreenshotPathTokenIndex } from "./artifact-paths.js";
 import { findRequestedArtifactCloseViolation } from "./prompt-guards.js";
 export function normalizeRunInput(input) {
@@ -283,10 +283,9 @@ async function collectSamePageRefFreshnessPreflight(options) {
 }
 function getIdleTimeoutMismatch(args, configuredValue) {
     for (let index = 0; index < args.length; index += 1) {
-        const token = args[index];
-        if (token !== "--idle-timeout" && !token.startsWith("--idle-timeout="))
+        if (args[index] !== "--idle-timeout")
             continue;
-        const requestedToken = token.includes("=") ? token.slice(token.indexOf("=") + 1) : args[++index];
+        const requestedToken = args[++index];
         if (!requestedToken || !/^\d+$/.test(requestedToken) || Number(requestedToken) === Number(configuredValue))
             continue;
         return `--idle-timeout ${requestedToken} conflicts with this Pi process's managed-session idle timeout (${configuredValue} ms). Restart Pi with PI_AGENT_BROWSER_IMPLICIT_SESSION_IDLE_TIMEOUT_MS=${requestedToken} and omit --idle-timeout; changing the launch value for one call can restart the upstream browser and discard the active tab.`;
@@ -353,22 +352,20 @@ export async function prepareBrowserRun(options) {
     let electronLaunch;
     const sessionMode = compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto";
     const freshSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1);
-    const rawManagedStateAccessError = getManagedSessionStateAccessValidationError({
+    const rawPageTargetError = getPageTargetValidationError({
         args: runtimeToolArgs,
-        cwd,
-        parentEnv: agentBrowserProcessEnv,
         stdin: runtimeToolStdin,
         trustedFirstBatchTabSelection: true,
     });
-    if (rawManagedStateAccessError) {
+    if (rawPageTargetError) {
         return {
             kind: "early-result",
             result: {
-                content: [{ type: "text", text: rawManagedStateAccessError }],
+                content: [{ type: "text", text: rawPageTargetError }],
                 details: {
                     args: redactedArgs,
-                    ...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, errorText: rawManagedStateAccessError, succeeded: false, validationError: rawManagedStateAccessError }),
-                    validationError: rawManagedStateAccessError,
+                    ...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, errorText: rawPageTargetError, succeeded: false, validationError: rawPageTargetError }),
+                    validationError: rawPageTargetError,
                 },
                 isError: true,
             },
@@ -419,16 +416,14 @@ export async function prepareBrowserRun(options) {
             executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: idleTimeoutMismatch };
         const ownedSessionKey = getSessionContextKey(executionPlan.sessionName, executionPlan.namespace);
         const plannedSessionPageState = sessionPageState.get(ownedSessionKey);
-        const managedStateAccessError = getManagedSessionStateAccessValidationError({
+        const pageTargetError = getPageTargetValidationError({
             args: executionPlan.effectiveArgs,
             currentPageUrl: plannedSessionPageState.tabTarget?.url,
             pageUrlUnknown: plannedSessionPageState.tabTargetUnknown === true,
-            cwd,
-            parentEnv: agentBrowserProcessEnv,
             stdin: runtimeToolStdin,
         });
-        if (!executionPlan.validationError && managedStateAccessError)
-            executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: managedStateAccessError };
+        if (!executionPlan.validationError && pageTargetError)
+            executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: pageTargetError };
         const recordedOwnedSession = ownedSessionKey ? state.ownedManagedSessions.get(ownedSessionKey) : undefined;
         const targetsCurrentManagedSession = state.managedSessionActive
             && ownedSessionKey === getSessionContextKey(state.managedSessionName, state.managedSessionNamespace);
@@ -462,6 +457,7 @@ export async function prepareBrowserRun(options) {
             executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: autosavePolicyChangeError };
         }
         const headedLaunch = getBooleanFlagValue(executionPlan.effectiveArgs, "--headed") ?? isUpstreamEnvFlagEnabled(agentBrowserProcessEnv.AGENT_BROWSER_HEADED);
+        const providerLaunch = executionPlan.startupScopedFlags.some((flag) => flag === "--provider" || flag === "-p") || agentBrowserProcessEnv.AGENT_BROWSER_PROVIDER !== undefined;
         const headedManagedAutosaveDisabled = retainedHeadedAutosaveDisabled || (explicitAutosaveInterval === undefined && headedLaunch);
         const headedManagedAutosaveInterval = retainedHeadedAutosaveInterval ?? (headedLaunch ? explicitAutosaveInterval ?? "0" : undefined);
         const compatibilityUserAgent = executionPlan.compatibilityWorkaround ? getDefaultHeadlessCompatUserAgent() : undefined;
@@ -484,9 +480,6 @@ export async function prepareBrowserRun(options) {
             compatibilityUserAgent: compatibilityUserAgentApplied ? compatibilityUserAgent : undefined,
             wrapperInjectedUserAgent: compatibilityUserAgentApplied,
         });
-        const managedSessionTargetError = getManagedSessionTargetAccessValidationError(executionPlan.effectiveArgs, ownedManagedSession !== undefined, agentBrowserProcessEnv);
-        if (!executionPlan.validationError && managedSessionTargetError)
-            executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: managedSessionTargetError };
         if (!executionPlan.validationError && ownedManagedSession) {
             const closeCommand = isCloseCommand(executionPlan.commandInfo.command);
             const policy = await acquireOwnedManagedSessionDaemonPolicy({
@@ -523,17 +516,6 @@ export async function prepareBrowserRun(options) {
                     effectiveArgs: ["--user-agent", compatibilityUserAgent, ...executionPlan.effectiveArgs],
                 };
             }
-            else if (closeCommand && managedSessionPolicyLock) {
-                executionPlan = {
-                    ...executionPlan,
-                    effectiveArgs: canonicalizeOwnedManagedSessionCloseArgs({
-                        args: executionPlan.effectiveArgs,
-                        cwd,
-                        ownedManagedSession: true,
-                        restoreState: state.managedSessionRestoreState,
-                    }, true),
-                };
-            }
         }
         return await withOwnedManagedSessionContext(ownedManagedSession, async () => {
             const managedSessionRestoreDisabled = () => state.managedSessionRestoreState.isDisabled(executionPlan.sessionName, executionPlan.namespace);
@@ -577,12 +559,10 @@ export async function prepareBrowserRun(options) {
                     executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: request.requirement };
                     return;
                 }
-                const livePageValidationError = getManagedSessionStateAccessValidationError({
+                const livePageValidationError = getPageTargetValidationError({
                     args: request.args,
                     currentPageUrl: liveUrl,
-                    cwd,
                     pageUrlUnknown: false,
-                    parentEnv: agentBrowserProcessEnv,
                     stdin: request.stdin,
                 });
                 if (livePageValidationError) {
@@ -598,7 +578,7 @@ export async function prepareBrowserRun(options) {
             if (!executionPlan.validationError && mayResolveSemanticVisibleRef && requiresLivePageVerification()) {
                 await verifyLivePage({
                     args: ["snapshot", "-i"],
-                    requirement: getCallerOwnedSessionLivePageVerificationRequirement({ args: ["snapshot", "-i"], cwd }),
+                    requirement: getExplicitSessionPageVerificationRequirement({ args: ["snapshot", "-i"] }),
                 });
             }
             if (!executionPlan.validationError && mayResolveSemanticVisibleRef) {
@@ -632,6 +612,13 @@ export async function prepareBrowserRun(options) {
                 });
             }
             const commandTokens = semanticActionVisibleRefResolution ? extractUpstreamCommandTokens(semanticActionVisibleRefResolution.args) : extractUpstreamCommandTokens(preparedArgs.args);
+            const unsupportedScrollIntoViewRecovery = executionPlan.validationError || executionPlan.plainTextInspection
+                ? undefined
+                : [commandTokens, ...getUpstreamEffectiveBatchSteps(commandTokens, runtimeToolStdin)]
+                    .map((tokens) => buildUnsupportedScrollIntoViewRecovery({ commandTokens: tokens, sessionName: executionPlan.sessionName }))
+                    .find((recovery) => recovery !== undefined);
+            if (unsupportedScrollIntoViewRecovery)
+                executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: unsupportedScrollIntoViewRecovery.error };
             const resolvedSemanticActionRefSnapshot = semanticActionVisibleRefResolution?.snapshot
                 ? { ...semanticActionVisibleRefResolution.snapshot, target: semanticActionVisibleRefResolution.snapshot.target ?? priorSessionTabTarget }
                 : undefined;
@@ -648,9 +635,8 @@ export async function prepareBrowserRun(options) {
                 && requiresLivePageVerification();
             const livePageRequirement = livePageAccessEligible
                 && !livePageVerified
-                ? getCallerOwnedSessionLivePageVerificationRequirement({
+                ? getExplicitSessionPageVerificationRequirement({
                     args: executionPlan.effectiveArgs,
-                    cwd,
                     stdin: runtimeToolStdin,
                 })
                 : undefined;
@@ -669,8 +655,10 @@ export async function prepareBrowserRun(options) {
                 freshSessionOrdinal += 1;
             }
             if (executionPlan.validationError) {
+                const nextActions = applyNamespaceToNextActions(unsupportedScrollIntoViewRecovery?.nextActions, executionPlan.namespace);
+                const nextActionsText = formatAgentBrowserNextActionsText(nextActions);
                 return { kind: "early-result", statePatch, result: {
-                        content: [{ type: "text", text: executionPlan.validationError }],
+                        content: [{ type: "text", text: [executionPlan.validationError, nextActionsText].filter((text) => text !== undefined).join("\n\n") }],
                         details: {
                             args: redactedArgs,
                             compiledElectron: redactedCompiledElectron,
@@ -679,6 +667,7 @@ export async function prepareBrowserRun(options) {
                             compiledSourceLookup: redactedCompiledSourceLookup,
                             compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
                             invalidValueFlag: executionPlan.invalidValueFlag,
+                            nextActions,
                             sessionMode,
                             sessionRecoveryHint: redactedRecoveryHint,
                             startupScopedFlags: executionPlan.startupScopedFlags,
@@ -1058,6 +1047,8 @@ export async function prepareBrowserRun(options) {
                 kind: "ready",
                 prepared: {
                     commandTokens,
+                    headedLaunch,
+                    providerLaunch,
                     managedSessionPolicyLock,
                     compiledElectron,
                     compiledJob,