pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -1,128 +1,224 @@
-import { runAgentBrowserProcess, withAttachedBrowserSessionContext, withChromeStartupArgs } from "../../process.js";
+import { runAgentBrowserProcess, withAttachedBrowserSessionContext, withChromeStartupArgs, } from "../../process.js";
 import { isRecord } from "../../parsing.js";
-import { collectNativeWebMcp, getNativeWebMcpCatalog } from "../../webmcp-observation.js";
-import { isPlainTextInspectionArgs, redactSensitiveValue } from "../../runtime.js";
-import { formatWebMcpCatalogUpdate } from "../../results/presentation/common.js";
+import { getAgentBrowserSessionIdentityKey, isBooleanFlagEnabled } from "../../argv-grammar.js";
+import { parseReadConfirmation, suppressConfirmationPageHelpers } from "../../read-confirmation.js";
+import { buildToolPresentation } from "../../results/presentation.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { collectNativeWebMcp } from "../../webmcp-observation.js";
+import { isPlainTextInspectionArgs } from "../../runtime-args-validation.js";
+import { redactSensitiveValue } from "../../runtime-redaction.js";
 import { withOwnedManagedSessionContext } from "../../managed-session-restore.js";
 import { cleanupClickDispatchProbe } from "./click-dispatch.js";
-import { applyBrowserRunStatePatch, getSessionContextKey } from "./session-state.js";
-import { buildScreenshotGeometry, collectScreenshotSample } from "./screenshot-observation.js";
-import { buildJsonVisibleContent, buildMissingBinaryFailureResult } from "./final-result.js";
-import { prepareBrowserRun } from "./prepare.js";
-import { processBrowserOutput } from "./process-output.js";
+import { applyBrowserRunStatePatch, withSessionCommandObservation } from "./session-state.js";
+import { annotateScreenshotImageObservations, collectScreenshotSample, } from "./screenshot-observation.js";
+import { buildJsonVisibleContent } from "./final-result-redaction.js";
+import { buildMissingBinaryFailureResult } from "./final-result-missing-binary.js";
+import { createNativeHelperObserver } from "./native-helper-observation.js";
+import { projectBrowserObservationResult, } from "./browser-observation-result.js";
 export { closeManagedSession } from "./managed-session-daemon-policy.js";
 export { getSessionContextKey } from "./session-state.js";
 export async function runAgentBrowserTool(options) {
-    const observed = await collectNativeWebMcp(() => withChromeStartupArgs(options.input.persistentChromeArgs, () => withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options))));
-    const result = observed.result;
-    let details = isRecord(result.details) ? result.details : undefined;
-    if (observed.catalog) {
-        const catalog = redactSensitiveValue(observed.catalog);
-        details = { ...details, webMcpCatalog: catalog };
-        result.details = details;
-        if (!options.input.toolArgs.includes("--json") && JSON.stringify(getNativeWebMcpCatalog(details.data)) !== JSON.stringify(catalog)) {
-            const notice = formatWebMcpCatalogUpdate(catalog);
-            if (result.content[0]?.type === "text")
-                result.content[0] = { ...result.content[0], text: `${result.content[0].text}\n\n${notice}` };
-            else
-                result.content.push({ type: "text", text: notice });
-        }
-    }
-    if (result.isError && details?.error === undefined) {
-        details = { ...details, error: details?.validationError ?? details?.summary ?? result.content.filter(part => part.type === "text").map(part => part.text).join("\n") };
-        result.details = details;
+    const observed = await collectNativeWebMcp(() => withSessionCommandObservation(createNativeHelperObserver(options.state, options.sessionPageStateUpdate), () => withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options))));
+    return projectBrowserObservationResult({
+        ...observed,
+        args: options.input.toolArgs,
+        modelVisible: options.modelVisible,
+        state: options.state,
+    });
+}
+async function buildHelperConfirmationResult(options, confirmation) {
+    const data = {
+        confirmation_required: true,
+        confirmation_id: confirmation.id,
+        action: confirmation.action ?? "read",
+    };
+    const presentation = await buildToolPresentation({
+        commandInfo: { command: confirmation.command, commandTokens: [confirmation.command ?? "read"] },
+        cwd: options.cwd,
+        envelope: { success: true, data },
+        namespace: confirmation.namespace,
+        sessionName: confirmation.sessionName,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Native helper ${confirmation.command ?? "undefined"} requires confirmation (${confirmation.action ?? "undefined"}). The requested command was not dispatched.`,
+            },
+            ...presentation.content,
+        ],
+        details: {
+            ...options.state.observedBrowserEffects,
+            agentBrowserStarted: false,
+            args: options.input.redactedArgs,
+            data,
+            sessionName: confirmation.sessionName,
+            namespace: confirmation.namespace,
+            sessionTabTargetUnknown: options.state.sessionPageState.get(getAgentBrowserSessionIdentityKey(confirmation.sessionName, confirmation.namespace)).tabTargetUnknown,
+            readConfirmation: confirmation,
+            nextActions: presentation.nextActions,
+            ...buildAgentBrowserResultCategoryDetails({
+                succeeded: false,
+                failureCategory: "confirmation-required",
+            }),
+        },
+        isError: true,
+    };
+}
+function projectEarlyResult(options, result) {
+    if (options.modelVisible === false ||
+        !isBooleanFlagEnabled(options.toolArgs, "--json") ||
+        isPlainTextInspectionArgs(options.toolArgs)) {
+        return result;
     }
-    if (options.modelVisible === false)
-        result.content = [];
-    const sessionKey = getSessionContextKey(typeof details?.sessionName === "string" ? details.sessionName : undefined, typeof details?.namespace === "string" ? details.namespace : undefined);
-    const page = options.state.sessionPageState.get(sessionKey);
-    return page.tabReopenPending === undefined ? result : {
+    const details = isRecord(result.details) ? result.details : {};
+    const summary = result.content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n");
+    return {
         ...result,
-        details: { ...details, sessionTabReopenPending: page.tabReopenPending, ...(page.refSnapshotInvalidation ? { refSnapshotInvalidation: page.refSnapshotInvalidation } : {}) },
+        content: buildJsonVisibleContent({
+            error: result.isError === true ? (details.validationError ?? summary) : null,
+            details,
+            presentation: { content: result.content, data: details.data, summary },
+            succeeded: result.isError !== true,
+        }),
+    };
+}
+async function honorHelperConfirmation(options, prepared) {
+    const confirmation = parseReadConfirmation(options.state.observedBrowserEffects?.readConfirmation);
+    if (confirmation?.state !== "pending") {
+        return prepared;
+    }
+    if (prepared.kind === "ready") {
+        await prepared.prepared.managedSessionPolicyLock?.release();
+    }
+    return {
+        kind: "early-result",
+        result: await buildHelperConfirmationResult(options, confirmation),
     };
 }
 async function runAgentBrowserToolInContext(options) {
-    const preparedResult = await prepareBrowserRun(options);
-    applyBrowserRunStatePatch(options.state, preparedResult.kind === "ready" ? preparedResult.prepared.statePatch : preparedResult.statePatch);
-    if (preparedResult.kind === "early-result") {
-        const result = preparedResult.result;
-        if (options.modelVisible !== false && options.input.toolArgs.includes("--json") && !isPlainTextInspectionArgs(options.input.toolArgs)) {
-            const details = isRecord(result.details) ? result.details : {};
-            const summary = result.content.filter(item => item.type === "text").map(item => item.text).join("\n");
-            result.content = buildJsonVisibleContent({
-                error: result.isError ? details.validationError ?? summary : null,
-                details,
-                presentation: { content: result.content, data: details.data, summary },
-                succeeded: result.isError !== true,
-            });
-        }
+    // Preparation belongs to this call's existing helper/attachment observation context.
+    const { prepareBrowserRun } = await import("./prepare.js");
+    const prepared = await prepareBrowserRun(options);
+    applyBrowserRunStatePatch(options.state, prepared.kind === "ready" ? prepared.prepared.statePatch : prepared.statePatch);
+    const preparation = await honorHelperConfirmation(options, prepared);
+    if (preparation.kind === "early-result") {
+        options.state.confirmationPolicyMayBeEstablished ??= false;
+        return projectEarlyResult({ modelVisible: options.modelVisible, toolArgs: options.input.toolArgs }, preparation.result);
+    }
+    return withOwnedManagedSessionContext(preparation.prepared.ownedManagedSessionContext, () => executePreparedBrowserRun(options, preparation.prepared));
+}
+function geometryProbeOptions(options, prepared, ownedManagedSession) {
+    return {
+        command: prepared.commandTokens,
+        cwd: options.cwd,
+        namespace: prepared.executionPlan.namespace,
+        sessionName: prepared.executionPlan.sessionName,
+        signal: options.signal,
+        env: ownedManagedSession
+            ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs }
+            : undefined,
+    };
+}
+function screenshotCanBeProbed(prepared) {
+    // A cold probe could launch the browser and consume launch-scoped capture flags.
+    return (prepared.commandTokens[0] === "screenshot" &&
+        prepared.priorSessionTabTarget !== undefined &&
+        prepared.priorSessionTabTargetUnknown !== true &&
+        prepared.executionPlan.startupScopedFlags.length === 0);
+}
+function captureSucceeded(result) {
+    return !result.aborted && !result.timedOut && result.exitCode === 0;
+}
+async function captureBrowserExecution(options, prepared) {
+    const geometry = geometryProbeOptions(options, prepared, prepared.ownedManagedSessionContext !== undefined);
+    const probe = screenshotCanBeProbed(prepared);
+    const sample = () => withChromeStartupArgs(prepared.chromeStartupArgs, () => collectScreenshotSample(geometry));
+    const before = probe ? await sample() : undefined;
+    const artifactRunStartedAtMs = Date.now();
+    const processResult = await withChromeStartupArgs(prepared.chromeStartupArgs, () => runAgentBrowserProcess({
+        args: prepared.processArgs,
+        nativeConfirmationDecision: suppressConfirmationPageHelpers(prepared.readConfirmation),
+        cwd: options.cwd,
+        env: geometry.env,
+        managedSessionRestoreState: options.state.managedSessionRestoreState,
+        managedStateCurrentPageUrl: prepared.priorSessionTabTarget?.url,
+        managedStatePageUrlUnknown: prepared.priorSessionTabTargetUnknown === true,
+        ownedManagedSession: prepared.ownedManagedSessionContext !== undefined,
+        signal: options.signal,
+        stdin: prepared.processStdin,
+        timeoutMs: prepared.processTimeoutMs,
+    }));
+    const after = probe && captureSucceeded(processResult) ? await sample() : undefined;
+    return { before, after, artifactRunStartedAtMs, processResult };
+}
+async function missingBinaryResult(options, prepared, processResult) {
+    return buildMissingBinaryFailureResult({
+        compatibilityWorkaround: prepared.compatibilityWorkaround,
+        electronLaunch: prepared.electronLaunch,
+        executionPlan: prepared.executionPlan,
+        implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
+        managedSessionActive: options.state.managedSessionActive,
+        managedSessionName: options.state.managedSessionName,
+        managedSessionNamespace: options.state.managedSessionNamespace,
+        processResult,
+        redactedArgs: prepared.redactedArgs,
+        redactedProcessArgs: prepared.redactedProcessArgs,
+        sessionMode: prepared.sessionMode,
+        sessionTabCorrection: prepared.sessionTabCorrection,
+    });
+}
+function addCaptureGeometry(result, capture, commandTokens) {
+    if (!isRecord(result.details) ||
+        !Array.isArray(result.details.imageObservations) ||
+        commandTokens[0] !== "screenshot") {
         return result;
     }
-    const { prepared } = preparedResult;
-    const ownedManagedSession = prepared.ownedManagedSessionContext;
-    return await withOwnedManagedSessionContext(ownedManagedSession, async () => {
+    return {
+        ...result,
+        details: {
+            ...result.details,
+            imageObservations: redactSensitiveValue(annotateScreenshotImageObservations(result.details.imageObservations, {
+                before: capture.before,
+                after: capture.after,
+            })),
+        },
+    };
+}
+async function executePreparedBrowserRun(options, prepared) {
+    try {
+        const capture = await captureBrowserExecution(options, prepared);
+        const missing = await missingBinaryResult(options, prepared, capture.processResult);
+        if (missing) {
+            options.state.confirmationPolicyMayBeEstablished ??= false;
+            return missing;
+        }
+        // Output presentation is not needed for synchronous registration or failed preparation.
+        // Its static host-peer imports retain Pi's loader mapping when loaded on demand.
+        const { processBrowserOutput } = await import("./process-output.js");
+        const output = await processBrowserOutput({
+            ...options,
+            prepared,
+            artifactRunStartedAtMs: capture.artifactRunStartedAtMs,
+            processResult: capture.processResult,
+        });
+        applyBrowserRunStatePatch(options.state, output.statePatch);
+        return addCaptureGeometry(output.result, capture, prepared.commandTokens);
+    }
+    finally {
         try {
-            const geometryOptions = { command: prepared.commandTokens, cwd: options.cwd, namespace: prepared.executionPlan.namespace, sessionName: prepared.executionPlan.sessionName, signal: options.signal,
-                env: ownedManagedSession ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined };
-            // Do not start a cold browser through a probe or consume launch flags ahead of the requested capture.
-            const probeGeometry = prepared.commandTokens[0] === "screenshot" && !!prepared.priorSessionTabTarget && !prepared.priorSessionTabTargetUnknown && !prepared.executionPlan.startupScopedFlags?.length;
-            const before = probeGeometry ? await withChromeStartupArgs(prepared.chromeStartupArgs, () => collectScreenshotSample(geometryOptions)) : undefined;
-            const artifactRunStartedAtMs = Date.now();
-            const processResult = await withChromeStartupArgs(prepared.chromeStartupArgs, () => runAgentBrowserProcess({
-                args: prepared.processArgs,
-                browserIndependentReadConfirmation: prepared.readConfirmation !== undefined,
+            await cleanupClickDispatchProbe({
                 cwd: options.cwd,
-                env: ownedManagedSession
-                    ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs }
-                    : undefined,
-                managedSessionRestoreState: options.state.managedSessionRestoreState,
-                managedStateCurrentPageUrl: prepared.priorSessionTabTarget?.url,
-                managedStatePageUrlUnknown: prepared.priorSessionTabTargetUnknown === true,
-                ownedManagedSession: ownedManagedSession !== undefined,
-                signal: options.signal,
-                stdin: prepared.processStdin,
-                timeoutMs: prepared.processTimeoutMs,
-            }));
-            const after = probeGeometry && !processResult.aborted && !processResult.timedOut && processResult.exitCode === 0
-                ? await withChromeStartupArgs(prepared.chromeStartupArgs, () => collectScreenshotSample(geometryOptions)) : undefined;
-            const missingBinaryResult = await buildMissingBinaryFailureResult({
-                compatibilityWorkaround: prepared.compatibilityWorkaround,
-                electronLaunch: prepared.electronLaunch,
-                executionPlan: prepared.executionPlan,
-                implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
-                managedSessionActive: options.state.managedSessionActive,
-                managedSessionName: options.state.managedSessionName,
-                managedSessionNamespace: options.state.managedSessionNamespace,
-                processResult,
-                redactedArgs: prepared.redactedArgs,
-                redactedProcessArgs: prepared.redactedProcessArgs,
-                sessionMode: prepared.sessionMode,
-                sessionTabCorrection: prepared.sessionTabCorrection,
+                namespace: prepared.executionPlan.namespace,
+                probe: prepared.clickDispatchProbe,
+                sessionName: prepared.executionPlan.sessionName,
             });
-            if (missingBinaryResult)
-                return missingBinaryResult;
-            const output = await processBrowserOutput({ ...options, artifactRunStartedAtMs, prepared, processResult });
-            applyBrowserRunStatePatch(options.state, output.statePatch);
-            if (isRecord(output.result.details) && Array.isArray(output.result.details.imageObservations) && prepared.commandTokens[0] === "screenshot") {
-                output.result.details.imageObservations = redactSensitiveValue(output.result.details.imageObservations.map(image => {
-                    const rendering = image.rendering ?? before?.rendering ?? after?.rendering;
-                    return { ...image, ...(rendering ? { rendering } : {}), geometry: buildScreenshotGeometry({ rendering, capture: image.capture, pixels: image.pixels, before, after }) };
-                }));
-            }
-            return output.result;
         }
         finally {
-            try {
-                await cleanupClickDispatchProbe({
-                    cwd: options.cwd,
-                    namespace: prepared.executionPlan.namespace,
-                    probe: prepared.clickDispatchProbe,
-                    sessionName: prepared.executionPlan.sessionName,
-                });
-            }
-            finally {
-                await prepared.managedSessionPolicyLock?.release();
-            }
+            await prepared.managedSessionPolicyLock?.release();
         }
-    });
+    }
 }

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

@@ -0,0 +1,290 @@
+import { isRecord } from "../../parsing.js";
+import { withOptionalSessionArgs } from "../../results/next-actions.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { runSessionCommandData } from "./session-state.js";
+import { diagnosticResultRecord, rawNumberField, rawStringField } from "./diagnostic-values.js";
+function isScrollMeasurements(value) {
+    return (isRecord(value) &&
+        ["scrollX", "scrollY", "innerHeight", "innerWidth", "scrollHeight", "scrollWidth"].every((field) => typeof value[field] === "number"));
+}
+function parseScrollContainer(entry, index) {
+    if (!isRecord(entry)) {
+        return [];
+    }
+    const rawId = rawStringField(entry, "id");
+    const id = rawId !== undefined && rawId !== "" && /^\d+:[a-z][a-z0-9-]*(?:\[role=[a-z-]+\])?$/i.test(rawId)
+        ? rawId
+        : `sample-${index}`;
+    const scrollTop = rawNumberField(entry, "scrollTop");
+    const scrollLeft = rawNumberField(entry, "scrollLeft");
+    return scrollTop !== undefined && scrollLeft !== undefined ? [{ id, scrollLeft, scrollTop }] : [];
+}
+function extractScrollPositionSnapshot(data) {
+    const result = diagnosticResultRecord(data);
+    if (!result || !isScrollMeasurements(result)) {
+        return undefined;
+    }
+    const containers = Array.isArray(result.containers)
+        ? result.containers.flatMap(parseScrollContainer)
+        : [];
+    return {
+        containerCount: rawNumberField(result, "containerCount") ?? containers.length,
+        containers,
+        innerHeight: result.innerHeight,
+        innerWidth: result.innerWidth,
+        scrollHeight: result.scrollHeight,
+        scrollWidth: result.scrollWidth,
+        scrollX: result.scrollX,
+        scrollY: result.scrollY,
+    };
+}
+const SCROLL_POSITION_EVAL = `(() => {
+  const viewport = {
+    scrollX: window.scrollX,
+    scrollY: window.scrollY,
+    innerHeight: window.innerHeight,
+    innerWidth: window.innerWidth,
+    scrollHeight: Math.max(document.documentElement?.scrollHeight || 0, document.body?.scrollHeight || 0),
+    scrollWidth: Math.max(document.documentElement?.scrollWidth || 0, document.body?.scrollWidth || 0),
+  };
+  const describe = (element, index) => {
+    const role = element.getAttribute("role") || "";
+    const id = element.tagName.toLowerCase();
+    return { id: String(index) + ":" + id + (role ? "[role=" + role + "]" : ""), scrollTop: element.scrollTop, scrollLeft: element.scrollLeft, area: element.clientWidth * element.clientHeight };
+  };
+  const containers = Array.from(document.querySelectorAll("body *"))
+    .filter((element) => element instanceof HTMLElement && (element.scrollHeight > element.clientHeight + 1 || element.scrollWidth > element.clientWidth + 1))
+    .map(describe)
+    .sort((left, right) => right.area - left.area)
+    .slice(0, 10)
+    .map(({ area, ...entry }) => entry);
+  return { ...viewport, containerCount: containers.length, containers };
+})()`;
+export async function collectScrollPositionSnapshot(options) {
+    return extractScrollPositionSnapshot(await runSessionCommandData({
+        args: ["eval", "--stdin"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+        stdin: SCROLL_POSITION_EVAL,
+    }));
+}
+function sameScrollPositionSnapshot(left, right) {
+    return (left.scrollX === right.scrollX &&
+        left.scrollY === right.scrollY &&
+        left.scrollHeight === right.scrollHeight &&
+        left.scrollWidth === right.scrollWidth &&
+        left.containers.length === right.containers.length &&
+        left.containers.every((container, index) => {
+            const other = right.containers.at(index);
+            return (other !== undefined &&
+                other.id === container.id &&
+                other.scrollTop === container.scrollTop &&
+                other.scrollLeft === container.scrollLeft);
+        }));
+}
+export function buildUnsupportedScrollIntoViewRecovery(options) {
+    if (!["scrollintoview", "scrollinto"].includes(options.commandTokens.at(0) ?? "") ||
+        options.commandTokens.some((token) => token === "--help" || token === "-h")) {
+        return undefined;
+    }
+    const match = /^text=(.+)$/s.exec(options.commandTokens.at(1) ?? "");
+    if (!match) {
+        return undefined;
+    }
+    const text = redactSensitiveText(match[1]);
+    return {
+        error: "scrollintoview accepts a CSS selector, xpath=..., or a current @e… ref; text=... is not supported and can falsely report success without moving the page.",
+        nextActions: [
+            {
+                id: "scroll-semantic-text-target",
+                params: {
+                    args: withOptionalSessionArgs(options.sessionName, ["find", "text", text, "hover"]),
+                },
+                reason: "Use the upstream semantic text locator; hover resolves and scrolls the matched element into view.",
+                safety: "Hover may open a tooltip or menu. Use the snapshot/ref recovery instead when hover state could affect the workflow.",
+                tool: "agent_browser",
+            },
+            {
+                id: "refresh-refs-for-scroll-target",
+                params: { args: withOptionalSessionArgs(options.sessionName, ["snapshot", "-i"]) },
+                reason: "Capture a current element ref, then retry scrollintoview with that @e… ref.",
+                safety: "Read-only snapshot; choose the intended current ref before retrying the scroll.",
+                tool: "agent_browser",
+            },
+        ],
+    };
+}
+export function buildScrollNoopDiagnostic(before, after) {
+    if (!before || !after || !sameScrollPositionSnapshot(before, after)) {
+        return undefined;
+    }
+    return {
+        after,
+        before,
+        message: "Scroll reported success, but the viewport and sampled scrollable containers did not change position.",
+        reason: "no-observed-scroll-position-change",
+        recommendations: [
+            "Run snapshot -i or screenshot to confirm what is visible before choosing the next action.",
+            "On dashboards and panes with nested scrolling, use scrollintoview <@ref> for a visible target or target the actual scrollable region instead of repeating page scrolls.",
+        ],
+    };
+}
+export function buildScrollNoopNextActions(sessionName) {
+    return [
+        {
+            id: "inspect-after-noop-scroll",
+            params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) },
+            reason: "Refresh interactive refs and inspect whether the intended target is inside a nested scroll container.",
+            safety: "Do not assume repeated page scrolls will move dashboard panels or nested panes.",
+            tool: "agent_browser",
+        },
+        {
+            id: "verify-noop-scroll-visually",
+            params: { args: withOptionalSessionArgs(sessionName, ["screenshot"]) },
+            reason: "Capture the current viewport to verify whether the scroll actually changed visible content.",
+            safety: "Use screenshot evidence before concluding a dense dashboard did or did not move.",
+            tool: "agent_browser",
+        },
+    ];
+}
+export function formatScrollNoopDiagnosticText(diagnostic) {
+    if (!diagnostic) {
+        return undefined;
+    }
+    return [
+        "Scroll diagnostic: no observed scroll movement.",
+        `Reason: ${diagnostic.message}`,
+        `Sampled scrollable containers: ${diagnostic.after.containers.length}/${diagnostic.after.containerCount}.`,
+        ...diagnostic.recommendations.map((recommendation) => `- ${recommendation}`),
+    ].join("\n");
+}
+const COMBOBOX_FOCUS_EVAL = `(() => {
+  const isVisible = (element) => {
+    if (!(element instanceof HTMLElement)) return false;
+    const style = window.getComputedStyle(element);
+    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
+    return element.getClientRects().length > 0;
+  };
+  const active = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const role = active?.getAttribute("role") || undefined;
+  const hasPopup = active?.getAttribute("aria-haspopup") || undefined;
+  const expanded = active?.getAttribute("aria-expanded") || undefined;
+  const tagName = active?.tagName.toLowerCase();
+  const name = (active?.getAttribute("aria-label") || active?.getAttribute("placeholder") || active?.getAttribute("title") || active?.textContent || "").trim().slice(0, 80) || undefined;
+  const visibleListboxCount = Array.from(document.querySelectorAll('[role="listbox"], [role="menu"]')).filter(isVisible).length;
+  const visibleOptionCount = Array.from(document.querySelectorAll('[role="option"], option, [role="menuitem"]')).filter(isVisible).length;
+  const comboboxLike = role === "combobox" || hasPopup === "listbox" || hasPopup === "menu" || tagName === "select" || active?.getAttribute("aria-autocomplete") !== null;
+  return { activeElement: active ? { expanded, hasPopup, name, role, tagName } : undefined, comboboxLike, visibleListboxCount, visibleOptionCount };
+})()`;
+function comboboxActiveElement(result, expanded) {
+    const name = rawStringField(result, "name");
+    return {
+        expanded,
+        hasPopup: rawStringField(result, "hasPopup"),
+        name: name === undefined ? undefined : redactSensitiveText(name),
+        role: rawStringField(result, "role"),
+        tagName: rawStringField(result, "tagName"),
+    };
+}
+function extractComboboxFocusDiagnostic(data) {
+    const result = diagnosticResultRecord(data);
+    if (!result || result.comboboxLike !== true || !isRecord(result.activeElement)) {
+        return undefined;
+    }
+    const visibleListboxCount = rawNumberField(result, "visibleListboxCount") ?? 0;
+    const visibleOptionCount = rawNumberField(result, "visibleOptionCount") ?? 0;
+    const expanded = rawStringField(result.activeElement, "expanded");
+    if ((expanded !== "false" && expanded !== "true") ||
+        visibleListboxCount > 0 ||
+        visibleOptionCount > 0) {
+        return undefined;
+    }
+    return {
+        activeElement: comboboxActiveElement(result.activeElement, expanded),
+        message: "A combobox-like control is focused, but no listbox or option elements are visibly open.",
+        reason: "focused-combobox-without-visible-options",
+        recommendations: [
+            "Run snapshot -i to inspect whether options appeared under a different role or portal.",
+            "Try ArrowDown or Enter to open the option list before selecting, or use select/visible option refs when available.",
+        ],
+        visibleListboxCount,
+        visibleOptionCount,
+    };
+}
+function isComboboxFocusDiagnosticCommand(command, commandTokens) {
+    if (!commandTokens.some((token) => /^(?:combobox|listbox)$/i.test(token))) {
+        return false;
+    }
+    if (command === "click" || command === "fill") {
+        return true;
+    }
+    return command === "find" && commandTokens.some((token) => ["click", "fill"].includes(token));
+}
+function getCompiledSemanticActionRoleValue(compiled) {
+    if (compiled.locator !== "role") {
+        return undefined;
+    }
+    const findIndex = compiled.args.indexOf("find");
+    if (findIndex < 0 || compiled.args[findIndex + 1] !== "role") {
+        return undefined;
+    }
+    return compiled.args[findIndex + 2];
+}
+function isComboboxFocusDiagnosticSemanticAction(compiled) {
+    return (compiled !== undefined &&
+        ["click", "fill"].includes(compiled.action) &&
+        /^(?:combobox|listbox)$/i.test(getCompiledSemanticActionRoleValue(compiled) ?? ""));
+}
+export async function collectComboboxFocusDiagnostic(options) {
+    if (!isComboboxFocusDiagnosticCommand(options.command, options.commandTokens) &&
+        !isComboboxFocusDiagnosticSemanticAction(options.semanticAction)) {
+        return undefined;
+    }
+    return extractComboboxFocusDiagnostic(await runSessionCommandData({
+        args: ["eval", "--stdin"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+        stdin: COMBOBOX_FOCUS_EVAL,
+    }));
+}
+export function buildComboboxFocusNextActions(sessionName) {
+    return [
+        {
+            id: "inspect-focused-combobox",
+            params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) },
+            reason: "Inspect the focused combobox and any portal/listbox refs before choosing an option.",
+            safety: "Prefer visible option refs or select when a native/selectable option list is exposed.",
+            tool: "agent_browser",
+        },
+        {
+            id: "try-open-combobox-with-arrow",
+            params: { args: withOptionalSessionArgs(sessionName, ["press", "ArrowDown"]) },
+            reason: "Many searchable comboboxes open their option list with ArrowDown after focus.",
+            safety: "Use only when the focused combobox is still the intended control, then re-snapshot before selecting.",
+            tool: "agent_browser",
+        },
+        {
+            id: "try-open-combobox-with-enter",
+            params: { args: withOptionalSessionArgs(sessionName, ["press", "Enter"]) },
+            reason: "Some comboboxes open or confirm their option list with Enter after focus.",
+            safety: "Enter may select a highlighted/default option; prefer ArrowDown first unless Enter is the app's expected opener.",
+            tool: "agent_browser",
+        },
+    ];
+}
+export function formatComboboxFocusDiagnosticText(diagnostic) {
+    if (!diagnostic) {
+        return undefined;
+    }
+    const name = diagnostic.activeElement.name;
+    const label = name !== undefined && name !== "" ? ` (${name})` : "";
+    return [
+        `Combobox diagnostic: focused combobox did not expose visible options${label}.`,
+        `Reason: ${diagnostic.message}`,
+        ...diagnostic.recommendations.map((recommendation) => `- ${recommendation}`),
+    ].join("\n");
+}