pi-agent-browser-native 0.9.5 → 0.9.7

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

@@ -1,406 +0,0 @@
-import { isRecord, parseRefId } from "../../parsing.js";
-import { redactSensitiveText } from "../../runtime-redaction.js";
-import { withOptionalSessionArgs, } from "../../results/next-actions.js";
-import { runSessionCommandData } from "./session-state.js";
-import { getAgentBrowserProcessTimeoutMs } from "../../process.js";
-import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
-const CLICK_DISPATCH_MARKER_PREFIX = "__piAgentBrowserClickDispatchProbe_";
-const CLICK_DISPATCH_CLEANUP_TIMEOUT_MS = 2_000;
-const ACCESSIBLE_REF_CLICK_DISPATCH_ROLES = new Set([
-    "button",
-    "checkbox",
-    "menuitem",
-    "radio",
-    "switch",
-    "tab",
-]);
-function normalizeAccessibleName(name) {
-    return name.replace(/\s+/g, " ").trim().toLowerCase();
-}
-function getClickDispatchProbeTarget(commandTokens, refSnapshot) {
-    if (commandTokens[0] !== "click" || commandTokens.includes("--new-tab")) {
-        return undefined;
-    }
-    const selector = commandTokens.slice(1).find((token) => token !== "--human");
-    if (selector === undefined || selector === "" || selector.startsWith("-")) {
-        return undefined;
-    }
-    const refId = parseRefId(selector);
-    if (refId !== undefined && refId !== "") {
-        return getAccessibleProbeTarget(refId, refSnapshot);
-    }
-    if (selector.startsWith("xpath=")) {
-        return { kind: "xpath", selector: selector.slice("xpath=".length) };
-    }
-    return undefined;
-}
-function getAccessibleProbeTarget(refId, refSnapshot) {
-    const refs = refSnapshot?.refs ?? {};
-    const ref = refs[refId];
-    if (!ref || !ACCESSIBLE_REF_CLICK_DISPATCH_ROLES.has(ref.role)) {
-        return undefined;
-    }
-    const matchingRefs = Object.values(refs).filter((candidate) => candidate !== undefined &&
-        candidate.role.toLowerCase() === ref.role.toLowerCase() &&
-        normalizeAccessibleName(candidate.name) === normalizeAccessibleName(ref.name));
-    return matchingRefs.length === 1
-        ? { kind: "accessible", name: ref.name, refId, role: ref.role }
-        : undefined;
-}
-function getEvalResultRecord(data) {
-    return isRecord(data) && isRecord(data.result) ? data.result : undefined;
-}
-function getClickDispatchIdentityAttribute(probe) {
-    return `data-pi-click-dispatch-${probe.marker.toLowerCase()}`;
-}
-function buildClickTargetResolutionScript(target) {
-    if (target.kind === "selector") {
-        return `(() => { try { return document.querySelector(${JSON.stringify(target.selector)}); } catch { return null; } })()`;
-    }
-    if (target.kind === "xpath") {
-        return `(() => { try { return document.evaluate(${JSON.stringify(target.selector)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue; } catch { return null; } })()`;
-    }
-    return `(() => {
-  const normalize = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
-  const expectedRole = ${JSON.stringify(target.role)};
-  const expectedName = normalize(${JSON.stringify(target.name)});
-  const inferRole = (element) => {
-    const explicit = element.getAttribute("role");
-    if (explicit) return explicit;
-    const tagName = element.tagName.toLowerCase();
-    if (tagName === "button" || tagName === "select" || tagName === "textarea") return tagName;
-    if (tagName === "a" && element.hasAttribute("href")) return "link";
-    if (tagName === "input") {
-      const type = (element.getAttribute("type") || "text").toLowerCase();
-      if (["button", "submit", "reset", "image"].includes(type)) return "button";
-      if (type === "checkbox") return "checkbox";
-      if (type === "radio") return "radio";
-      return "textbox";
-    }
-    return "";
-  };
-  const inferName = (element) => normalize(element.getAttribute("aria-label") || element.getAttribute("title") || element.value || element.textContent || "");
-  const isVisible = (element) => {
-    const style = window.getComputedStyle(element);
-    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
-    return element.getClientRects().length > 0;
-  };
-  const candidates = Array.from(document.querySelectorAll("button,a[href],input,select,textarea,summary,[role],[onclick],[tabindex]")).filter((element) => inferRole(element) === expectedRole && inferName(element) === expectedName && isVisible(element));
-  return candidates.length === 1 ? candidates[0] : null;
-})()`;
-}
-function buildClickDispatchProbeInstallScript(probe, timeoutMs) {
-    return `(() => {
-const marker = ${JSON.stringify(probe.marker)};
-const element = ${buildClickTargetResolutionScript(probe.target)};
-if (!element) return { status: "target-not-found", marker };
-const cssEscape = (value) => {
-  if (window.CSS && typeof window.CSS.escape === "function") return window.CSS.escape(value);
-  return String(value).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
-};
-const getSelector = (node) => {
-  if (!(node instanceof Element)) return undefined;
-  if (node.id) return "#" + cssEscape(node.id);
-  const testId = node.getAttribute("data-testid") || node.getAttribute("data-test-id");
-  if (testId) return '[data-testid="' + cssEscape(testId) + '"]';
-  const parts = [];
-  let current = node;
-  while (current && current !== document.body && parts.length < 4) {
-    const tag = current.tagName.toLowerCase();
-    const parent = current.parentElement;
-    if (!parent) break;
-    const siblings = Array.from(parent.children).filter((child) => child.tagName === current.tagName);
-    const index = siblings.indexOf(current) + 1;
-    parts.unshift(siblings.length > 1 ? tag + ':nth-of-type(' + index + ')' : tag);
-    current = parent;
-  }
-  return parts.length > 0 ? parts.join(" > ") : undefined;
-};
-const rectInfo = (rect) => ({ bottom: rect.bottom, left: rect.left, right: rect.right, top: rect.top });
-const targetRect = element ? element.getBoundingClientRect() : undefined;
-const targetOutsideViewport = targetRect ? targetRect.bottom < 0 || targetRect.right < 0 || targetRect.top > window.innerHeight || targetRect.left > window.innerWidth : undefined;
-let nearestScrollContainer;
-if (element && targetRect) {
-  for (let current = element.parentElement; current && current !== document.body; current = current.parentElement) {
-    if (current.scrollHeight > current.clientHeight + 1 || current.scrollWidth > current.clientWidth + 1) {
-      const containerRect = current.getBoundingClientRect();
-      nearestScrollContainer = {
-        selector: getSelector(current),
-        tagName: current.tagName.toLowerCase(),
-        targetOutsideContainer: targetRect.bottom < containerRect.top || targetRect.top > containerRect.bottom || targetRect.right < containerRect.left || targetRect.left > containerRect.right,
-        targetOutsideViewport,
-        rect: rectInfo(containerRect),
-        scrollLeft: current.scrollLeft,
-        scrollTop: current.scrollTop,
-      };
-      break;
-    }
-  }
-}
-const state = { events: [], target: { tagName: element.tagName.toLowerCase(), nearestScrollContainer, rect: rectInfo(targetRect), targetOutsideViewport } };
-const eventTypes = ["pointerdown", "mousedown", "pointerup", "mouseup", "click"];
-const listeners = eventTypes.map((type) => {
-  const listener = (event) => {
-    const path = typeof event.composedPath === "function" ? event.composedPath() : [];
-    const eventTarget = event.target;
-    const targetMatched = path.includes(element) || eventTarget === element || (eventTarget instanceof Node && element.contains(eventTarget));
-    state.events.push({ type: event.type, isTrusted: event.isTrusted === true, targetMatched });
-  };
-  document.addEventListener(type, listener, true);
-  return [type, listener];
-});
-const identityAttribute = ${JSON.stringify(getClickDispatchIdentityAttribute(probe))};
-state.removeIdentityMarker = () => element.removeAttribute(identityAttribute);
-let cleanupTimer;
-state.cleanup = () => {
-  clearTimeout(cleanupTimer);
-  state.removeIdentityMarker();
-  listeners.forEach(([type, listener]) => document.removeEventListener(type, listener, true));
-  try { delete window[marker]; } catch {}
-};
-// A native pending decision can forbid cleanup eval; expire without another command.
-cleanupTimer = setTimeout(state.cleanup, ${timeoutMs + CLICK_DISPATCH_CLEANUP_TIMEOUT_MS});
-window[marker] = state;
-element.setAttribute(identityAttribute, marker);
-return { status: "installed", marker, target: state.target };
-})()`;
-}
-function buildClickDispatchProbeCheckScript(probe) {
-    return `(() => {
-const marker = ${JSON.stringify(probe.marker)};
-const state = window[marker];
-const finish = (payload) => {
-  if (state && typeof state.cleanup === "function") state.cleanup();
-  try { delete window[marker]; } catch {}
-  return payload;
-};
-if (!state || !Array.isArray(state.events)) return finish({ status: "probe-missing", nativeEventCount: 0 });
-const nativeEventCount = state.events.filter((event) => event && event.isTrusted === true && event.targetMatched === true).length;
-if (nativeEventCount > 0) return finish({ status: "native-event-observed", nativeEventCount, target: state.target });
-return finish({ status: "no-native-event-observed", nativeEventCount, target: state.target });
-})()`;
-}
-function buildClickDispatchProbeCleanupScript(probe) {
-    return `(() => {
-const marker = ${JSON.stringify(probe.marker)};
-const state = window[marker];
-if (state && typeof state.cleanup === "function") state.cleanup();
-try { delete window[marker]; } catch {}
-return { status: "cleaned-up" };
-})()`;
-}
-function redactClickDispatchTarget(target) {
-    if (target.kind === "selector" || target.kind === "xpath") {
-        return { ...target, selector: redactSensitiveText(target.selector) };
-    }
-    return { ...target, name: redactSensitiveText(target.name) };
-}
-export function formatClickDispatchDiagnosticText(diagnostic) {
-    return `Click dispatch diagnostic: ${diagnostic.summary}`;
-}
-export function buildClickDispatchNextActions(options) {
-    const retryArgs = options.commandTokens[0] === "click" || options.commandTokens[0] === "find"
-        ? options.commandTokens
-        : ["click", ...options.commandTokens];
-    const actions = [
-        {
-            id: "inspect-click-dispatch-miss",
-            params: { args: withOptionalSessionArgs(options.sessionName, ["snapshot", "-i"]) },
-            reason: "Refresh interactive refs and verify the intended click target before retrying upstream click.",
-            safety: "Read-only snapshot; the wrapper does not replay clicks in-page when upstream reports success without DOM events.",
-            tool: "agent_browser",
-        },
-    ];
-    if (options.diagnostic?.scrollContainer) {
-        actions.push({
-            id: "scroll-target-into-view-after-dispatch-miss",
-            params: {
-                args: withOptionalSessionArgs(options.sessionName, ["scrollintoview", retryArgs.at(1)].filter((item) => typeof item === "string")),
-            },
-            reason: options.diagnostic.scrollContainer.selector !== undefined &&
-                options.diagnostic.scrollContainer.selector !== ""
-                ? `The target may be outside nested scroll container ${options.diagnostic.scrollContainer.selector}; scroll the target into view before retrying the click.`
-                : "The target may be inside an offscreen nested scroll container; scroll the target into view before retrying the click.",
-            safety: "Use only for the same current page and target; run snapshot -i again if the page rerendered.",
-            tool: "agent_browser",
-        });
-    }
-    actions.push({
-        id: "retry-click-after-dispatch-miss",
-        params: { args: withOptionalSessionArgs(options.sessionName, retryArgs) },
-        reason: "Retry the same upstream click after confirming the target is visible; do not assume the prior success mutated the page.",
-        safety: "Only retry when the target is still intended; use page-change evidence or a fresh snapshot before continuing the workflow.",
-        tool: "agent_browser",
-    });
-    return actions;
-}
-function nativeProbeSelector(target) {
-    if (target.kind === "accessible") {
-        return `@${target.refId}`;
-    }
-    return target.kind === "xpath" ? `xpath=${target.selector}` : target.selector;
-}
-async function verifyClickDispatchProbeIdentity(options, probe) {
-    const identity = await runSessionCommandData({
-        args: [
-            "get",
-            "attr",
-            nativeProbeSelector(probe.target),
-            getClickDispatchIdentityAttribute(probe),
-        ],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-    });
-    if (!isRecord(identity) || identity.value !== probe.marker) {
-        return false;
-    }
-    const removed = await runSessionCommandData({
-        args: ["eval", "--stdin"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-        stdin: `(() => {
-const state = window[${JSON.stringify(probe.marker)}];
-if (!state || typeof state.removeIdentityMarker !== "function") return { status: "probe-missing" };
-state.removeIdentityMarker();
-return { status: "identity-marker-removed" };
-})()`,
-    });
-    return getEvalResultRecord(removed)?.status === "identity-marker-removed";
-}
-function canPrepareClickDispatchProbe(options) {
-    if ((options.sessionName ?? "") === "" ||
-        options.commandTokens[0] !== "click" ||
-        options.commandTokens.includes("--new-tab")) {
-        return false;
-    }
-    // This optional diagnostic must not require approving a fresh eval on every click retry.
-    if (getAgentBrowserProcessEnvironment()
-        .AGENT_BROWSER_CONFIRM_ACTIONS?.split(",")
-        .some((action) => action.trim().toLowerCase() === "evaluate") === true) {
-        return false;
-    }
-    return true;
-}
-export async function prepareClickDispatchProbe(options) {
-    if (!canPrepareClickDispatchProbe(options)) {
-        return undefined;
-    }
-    const target = getClickDispatchProbeTarget(options.commandTokens, options.refSnapshot);
-    if (!target) {
-        return undefined;
-    }
-    const probe = {
-        marker: `${CLICK_DISPATCH_MARKER_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`,
-        target,
-    };
-    let prepared = false;
-    try {
-        const installData = await runSessionCommandData({
-            args: ["eval", "--stdin"],
-            cwd: options.cwd,
-            namespace: options.namespace,
-            sessionName: options.sessionName,
-            signal: options.signal,
-            stdin: buildClickDispatchProbeInstallScript(probe, options.timeoutMs ?? getAgentBrowserProcessTimeoutMs()),
-        });
-        if (getEvalResultRecord(installData)?.status !== "installed") {
-            return undefined;
-        }
-        // Name matching and in-page XPath only find candidates. Native resolution
-        // must prove identity, including frame scope, before missing events mean failure.
-        if (!(await verifyClickDispatchProbeIdentity(options, probe))) {
-            return undefined;
-        }
-        prepared = options.signal?.aborted !== true;
-        return prepared ? probe : undefined;
-    }
-    finally {
-        // Even a lost/aborted install response may have left listeners in-page.
-        if (!prepared) {
-            await cleanupClickDispatchProbe({ ...options, probe });
-        }
-    }
-}
-function optionalBoolean(value, key) {
-    return typeof value?.[key] === "boolean" ? value[key] : undefined;
-}
-function nearestScrollContainer(target) {
-    return isRecord(target?.nearestScrollContainer) ? target.nearestScrollContainer : undefined;
-}
-function getClickDispatchScrollContainerDiagnostic(result) {
-    const target = isRecord(result.target) ? result.target : undefined;
-    const scrollContainer = nearestScrollContainer(target);
-    const targetOutsideViewport = optionalBoolean(target, "targetOutsideViewport");
-    const targetOutsideContainer = optionalBoolean(scrollContainer, "targetOutsideContainer");
-    if (!scrollContainer && targetOutsideViewport !== true) {
-        return undefined;
-    }
-    if (targetOutsideContainer !== true && targetOutsideViewport !== true) {
-        return undefined;
-    }
-    const selector = typeof scrollContainer?.selector === "string"
-        ? redactSensitiveText(scrollContainer.selector)
-        : undefined;
-    const summary = describeClickScrollContainer(selector);
-    return { selector, summary, targetOutsideContainer, targetOutsideViewport };
-}
-function describeClickScrollContainer(selector) {
-    return selector !== undefined && selector !== ""
-        ? `Target appears outside nested scroll container ${selector}; use scrollintoview on the target or scroll that container before retrying.`
-        : "Target appears outside the viewport or a nested scroll container; use scrollintoview on the target before retrying.";
-}
-export async function collectClickDispatchDiagnostic(options) {
-    if (!options.probe || (options.sessionName ?? "") === "") {
-        return undefined;
-    }
-    const data = await runSessionCommandData({
-        args: ["eval", "--stdin"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-        stdin: buildClickDispatchProbeCheckScript(options.probe),
-    });
-    const result = getEvalResultRecord(data);
-    if (!result) {
-        return undefined;
-    }
-    options.probe.cleaned = true;
-    const status = typeof result.status === "string" ? result.status : undefined;
-    if (status !== "no-native-event-observed") {
-        return undefined;
-    }
-    const nativeEventCount = typeof result.nativeEventCount === "number" ? result.nativeEventCount : 0;
-    const scrollContainer = getClickDispatchScrollContainerDiagnostic(result);
-    const targetLabel = "no trusted DOM event reached the selected element";
-    const summary = scrollContainer
-        ? `Upstream click reported success but ${targetLabel}. ${scrollContainer.summary}`
-        : `Upstream click reported success but ${targetLabel}. Gather evidence with snapshot or page-change checks, then retry upstream click or report the workflow issue; the wrapper does not replay clicks in-page.`;
-    return {
-        nativeEventCount,
-        reason: "native-click-produced-no-target-dom-event",
-        ...(scrollContainer ? { scrollContainer } : {}),
-        status,
-        summary,
-        target: redactClickDispatchTarget(options.probe.target),
-    };
-}
-export async function cleanupClickDispatchProbe(options) {
-    if (!options.probe || options.probe.cleaned === true || (options.sessionName ?? "") === "") {
-        return;
-    }
-    await runSessionCommandData({
-        args: ["eval", "--stdin"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        stdin: buildClickDispatchProbeCleanupScript(options.probe),
-        timeoutMs: CLICK_DISPATCH_CLEANUP_TIMEOUT_MS,
-    }).catch(() => {
-        // Probe expiry also removes listeners; cleanup failure must not replace the caller's result.
-    });
-}

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

@@ -1,31 +0,0 @@
-import { isRecord } from "../../parsing.js";
-import { stringifyUnknown } from "../../results/text.js";
-export function diagnosticResultRecord(data) {
-    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
-    return isRecord(result) ? result : undefined;
-}
-export function rawStringField(data, field) {
-    const value = data[field];
-    return typeof value === "string" ? value : undefined;
-}
-export function rawNumberField(data, field) {
-    const value = data[field];
-    return typeof value === "number" ? value : undefined;
-}
-export function diagnosticErrorText(error) {
-    if (error instanceof Error) {
-        return error.message;
-    }
-    switch (typeof error) {
-        case "object":
-            return error === null ? "null" : stringifyUnknown(error);
-        case "string":
-        case "number":
-        case "bigint":
-        case "boolean":
-        case "undefined":
-        case "symbol":
-        case "function":
-            return String(error);
-    }
-}

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

@@ -1,240 +0,0 @@
-import { stat } from "node:fs/promises";
-import { setTimeout as sleepMs } from "node:timers/promises";
-import { isAbsolute, resolve } from "node:path";
-import { isCloseCommand } from "../../command-taxonomy.js";
-import { executableExistsOnPath } from "../../executable-path.js";
-import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
-import { buildVisibleRefFallbackDiagnosticFromSnapshot, getVisibleRefFallbackTarget, } from "../../results/selector-recovery.js";
-import { isAboutBlankUrl, normalizeComparableUrl, } from "../../session-page-state.js";
-import { isRecord } from "../../parsing.js";
-import { extractNavigationSummaryFromData, extractStringResultField, runSessionCommandData, } from "./session-state.js";
-export { redactTimeoutPartialProgress } from "./timeout-progress.js";
-export { sleepMs };
-function comparePriorNavigationUrl(priorUrl, url) {
-    return priorUrl !== undefined && priorUrl !== ""
-        ? normalizeComparableUrl(priorUrl) !== normalizeComparableUrl(url)
-        : undefined;
-}
-function reusableNavigationTitle(options, url) {
-    const prior = options.priorTarget;
-    return options.reusePriorTitle !== false &&
-        prior !== undefined &&
-        prior.title !== undefined &&
-        prior.title !== "" &&
-        normalizeComparableUrl(prior.url) === normalizeComparableUrl(url)
-        ? prior.title
-        : undefined;
-}
-export async function collectNavigationSummary(options) {
-    const url = extractStringResultField(await runSessionCommandData({
-        args: ["get", "url"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-    }), "url");
-    if (url === undefined || url === "" || !/^[a-z][a-z0-9+.-]*:/i.test(url)) {
-        return undefined;
-    }
-    const urlChanged = comparePriorNavigationUrl(options.priorTarget?.url, url);
-    if (isAboutBlankUrl(url)) {
-        return { url, ...(urlChanged !== undefined ? { urlChanged } : {}) };
-    }
-    // Reuse the title already observed for this exact URL instead of spending a second probe. Titles can
-    // change without a URL change on SPAs, but this summary is only a "last observed" page label; the URL
-    // stays live-probed on every call.
-    const priorTitle = reusableNavigationTitle(options, url);
-    if (priorTitle !== undefined) {
-        return { title: priorTitle, url, urlChanged: false };
-    }
-    const title = extractStringResultField(await runSessionCommandData({
-        args: ["get", "title"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-    }), "title");
-    return { title, url, ...(urlChanged !== undefined ? { urlChanged } : {}) };
-}
-export { collectScrollPositionSnapshot, buildUnsupportedScrollIntoViewRecovery, buildScrollNoopDiagnostic, buildScrollNoopNextActions, formatScrollNoopDiagnosticText, collectComboboxFocusDiagnostic, buildComboboxFocusNextActions, formatComboboxFocusDiagnosticText, } from "./interaction-diagnostics.js";
-function getRecordStartLikeCommand(command, commandTokens) {
-    if (command !== "record") {
-        return undefined;
-    }
-    const subcommand = commandTokens[1]?.toLowerCase();
-    if (subcommand === "start") {
-        return "record start";
-    }
-    if (subcommand === "restart") {
-        return "record restart";
-    }
-    return undefined;
-}
-export async function collectRecordingDependencyWarning(options) {
-    if (!options.succeeded) {
-        return undefined;
-    }
-    const recordCommand = getRecordStartLikeCommand(options.command, options.commandTokens);
-    if (recordCommand === undefined) {
-        return undefined;
-    }
-    if (await executableExistsOnPath("ffmpeg")) {
-        return undefined;
-    }
-    return {
-        command: recordCommand,
-        dependency: "ffmpeg",
-        message: `${recordCommand} reported a pending recording, but ffmpeg is not on PATH. Its output is unverified; install ffmpeg before starting a new recording.`,
-        reason: "ffmpeg-missing-for-recording",
-        recommendations: [
-            "Install ffmpeg before recording; on macOS with Homebrew, brew install ffmpeg or brew install ffmpeg-full.",
-            "Stop this recording, check the result, and start a new recording after ensuring Pi can find ffmpeg on PATH.",
-        ],
-    };
-}
-export function formatRecordingDependencyWarningText(warning) {
-    if (!warning) {
-        return undefined;
-    }
-    return [
-        "Recording dependency warning: ffmpeg not found on PATH.",
-        `Reason: ${warning.message}`,
-        ...warning.recommendations.map((recommendation) => `- ${recommendation}`),
-    ].join("\n");
-}
-export { formatOverlayBlockerText, buildOverlayBlockerNextActions, collectSnapshotOverlayBlockerDiagnostic, collectOverlayBlockerDiagnostic, } from "./overlay-diagnostics.js";
-export { collectSelectorTextVisibilityDiagnostics, formatSelectorTextVisibilityText, buildSelectorTextVisibilityNextActions, } from "./text-visibility-diagnostics.js";
-export { getSourceLookupElectronContext, buildSourceLookupElectronNextActions, collectElectronBroadGetTextScopeDiagnostics, formatElectronBroadGetTextScopeText, buildElectronBroadGetTextScopeNextActions, } from "./electron-text-diagnostics.js";
-function looksLikeFunctionEvalStdin(stdin) {
-    const trimmed = stdin?.trim();
-    if (trimmed === undefined || trimmed === "") {
-        return false;
-    }
-    return (/^(?:async\s+)?function\b/.test(trimmed) ||
-        /^(?:async\s*)?\([^)]*\)\s*=>/.test(trimmed) ||
-        /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed));
-}
-function isPlainEmptyObject(value) {
-    if (!isRecord(value) || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return (prototype === Object.prototype || prototype === null) && Object.keys(value).length === 0;
-}
-export function getEvalStdinHint(options) {
-    if (options.command !== "eval" ||
-        !looksLikeFunctionEvalStdin(options.stdin) ||
-        !isRecord(options.data)) {
-        return;
-    }
-    const result = options.data.result;
-    if (!isPlainEmptyObject(result)) {
-        return;
-    }
-    return {
-        reason: "eval --stdin received a function-shaped snippet and the upstream JSON result was an empty object, which often means the function itself was returned or serialized instead of invoked.",
-        suggestion: "Pass a plain expression such as `({ title: document.title })`, or invoke the function explicitly, for example `(() => ({ title: document.title }))()`.",
-    };
-}
-export function formatEvalStdinHintText(hint) {
-    return hint ? `Eval stdin hint: ${hint.reason} ${hint.suggestion}` : undefined;
-}
-function localEvalPageUrl(options) {
-    const pageUrl = options.pageUrl?.trim() ??
-        options.navigationSummary?.url?.trim() ??
-        extractNavigationSummaryFromData(options.data)?.url;
-    return pageUrl !== undefined && pageUrl !== "" && /^file:/i.test(pageUrl) ? pageUrl : undefined;
-}
-export function getEvalResultWarning(options) {
-    const trimmed = options.stdin?.trim();
-    if (options.command !== "eval" ||
-        trimmed === undefined ||
-        trimmed === "" ||
-        !isRecord(options.data) ||
-        options.data.result !== null ||
-        /^(?:null|undefined)$/i.test(trimmed) ||
-        localEvalPageUrl(options) === undefined) {
-        return;
-    }
-    return {
-        reason: "eval --stdin returned null on a file:// page; upstream may not expose full DOM semantics for local fixtures.",
-        suggestion: "Treat this as inconclusive verification. Use snapshot -i, get text on current @refs, screenshot evidence, or a reachable http(s) fixture before concluding DOM state.",
-    };
-}
-export function formatEvalResultWarningText(warning) {
-    return warning ? `Eval result warning: ${warning.reason} ${warning.suggestion}` : undefined;
-}
-async function collectExistingExplicitArtifactPaths(entries, cwd) {
-    const explicitArtifactPaths = [];
-    const seenPaths = new Set();
-    for (const entry of entries) {
-        if (explicitArtifactPaths.length >= 10) {
-            break;
-        }
-        const displayPath = entry.path;
-        if (seenPaths.has(displayPath)) {
-            continue;
-        }
-        const absolutePath = entry.absolutePath ?? (isAbsolute(entry.path) ? entry.path : resolve(cwd, entry.path));
-        try {
-            // The first ten existing distinct display paths are selected in manifest order.
-            // oxlint-disable-next-line no-await-in-loop
-            await stat(absolutePath);
-        }
-        catch {
-            continue;
-        }
-        seenPaths.add(displayPath);
-        explicitArtifactPaths.push(displayPath);
-    }
-    return explicitArtifactPaths;
-}
-export async function getArtifactCleanupGuidance(options) {
-    if (!options.succeeded || !isCloseCommand(options.command) || !options.manifest) {
-        return undefined;
-    }
-    const explicitEntries = options.manifest.entries.filter((entry) => entry.storageScope === "explicit-path");
-    if (explicitEntries.length === 0) {
-        return undefined;
-    }
-    const explicitArtifactPaths = await collectExistingExplicitArtifactPaths(explicitEntries, options.cwd);
-    if (explicitArtifactPaths.length === 0) {
-        return undefined;
-    }
-    return {
-        explicitArtifactPaths,
-        note: "Closing the browser session does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; clean existing paths with host file tools when no longer needed.",
-        owner: "host-file-tools",
-        summary: formatSessionArtifactRetentionSummary(options.manifest),
-    };
-}
-export function formatArtifactCleanupGuidanceText(guidance) {
-    if (!guidance || guidance.explicitArtifactPaths.length === 0) {
-        return undefined;
-    }
-    const explicitCount = guidance.explicitArtifactPaths.length;
-    return `Artifact lifecycle: ${explicitCount} explicit artifact${explicitCount === 1 ? "" : "s"} remain${explicitCount === 1 ? "s" : ""}; expand or inspect details.artifactCleanup.explicitArtifactPaths for paths. Browser close does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; use host file tools for cleanup.`;
-}
-export { collectElectronManagedSessionTarget, collectQaAttachedTarget, formatQaAttachedTargetText, validateQaAttachedPrecondition, collectElectronHandoff, } from "./electron-observation.js";
-export { collectFillVerificationDiagnostic, buildFillVerificationNextActions, formatFillVerificationText, } from "./fill-diagnostics.js";
-export async function collectVisibleRefFallbackDiagnostic(options) {
-    if (options.sessionName === undefined || options.sessionName === "") {
-        return undefined;
-    }
-    const target = getVisibleRefFallbackTarget({
-        commandTokens: options.commandTokens,
-        compiledSemanticAction: options.compiledSemanticAction,
-    });
-    if (!target) {
-        return undefined;
-    }
-    const snapshotData = await runSessionCommandData({
-        args: ["snapshot", "-i"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-    });
-    return buildVisibleRefFallbackDiagnosticFromSnapshot({ snapshotData, target });
-}
-export { collectTimeoutPartialProgress, formatTimeoutPartialProgressText, } from "./timeout-diagnostics.js";