pi-agent-browser-native 0.9.4 → 0.9.6

package/dist/extensions/agent-browser/lib/results/recording.js

@@ -1,88 +0,0 @@
-import { isRecord } from "../parsing.js";
-const RECORDING_QUALITY_WARNING = "Capture quality warning: repaint-driven capture, held/repeated or static frames, and late/final-state-only frames cannot establish UI smoothness. Output FPS is not captured-frame rate; inspect the recording and capture window before judging motion.";
-function getRecordingOutcome(value, outcome) {
-    if (typeof value === "boolean" || value === null) {
-        return value;
-    }
-    return outcome ?? null;
-}
-function formatRecordingOutcome(receipt) {
-    let outcome = "pending/unknown";
-    if (receipt.success !== null) {
-        outcome = receipt.success ? "succeeded" : "failed";
-    }
-    const error = receipt.error !== null && receipt.error.length > 0 ? ` — ${receipt.error}` : "";
-    return `Native recording outcome: ${outcome}${error}`;
-}
-function recordOrEmpty(value) {
-    return isRecord(value) ? value : {};
-}
-function number(value) {
-    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
-}
-function text(value) {
-    return typeof value === "string" && value.length > 0 ? value : null;
-}
-export function getRecordingReceipt(value, outcome) {
-    if (!isRecord(value) || typeof value.path !== "string" || value.path.length === 0) {
-        return undefined;
-    }
-    const capture = recordOrEmpty(value.capture);
-    const output = recordOrEmpty(value.output);
-    const file = recordOrEmpty(value.file);
-    return {
-        warning: RECORDING_QUALITY_WARNING,
-        recordingId: text(value.recordingId),
-        path: value.path,
-        success: getRecordingOutcome(value.success, outcome),
-        error: text(value.error),
-        frames: number(value.frames),
-        capturedFrames: number(value.capturedFrames),
-        fps: number(value.fps),
-        capture: {
-            startedAt: text(capture.startedAt),
-            endedAt: text(capture.endedAt),
-            durationMs: number(capture.durationMs),
-            firstFrameAt: text(capture.firstFrameAt),
-            lastFrameAt: text(capture.lastFrameAt),
-            firstFrameAfterMs: number(capture.firstFrameAfterMs),
-            lastFrameAfterMs: number(capture.lastFrameAfterMs),
-            averageFps: number(capture.averageFps),
-            maxFrameGapMs: number(capture.maxFrameGapMs),
-            timestampSource: text(capture.timestampSource),
-        },
-        output: {
-            frames: number(output.frames ?? value.frames),
-            fps: number(output.fps ?? value.fps),
-            encodedFrames: number(output.encodedFrames),
-            durationMs: number(output.durationMs),
-            durationSource: text(output.durationSource),
-            heldFrames: number(output.heldFrames),
-            droppedFrames: number(output.droppedFrames),
-            skippedFrames: number(output.skippedFrames),
-            encoderSucceeded: typeof output.encoderSucceeded === "boolean" ? output.encoderSucceeded : null,
-        },
-        file: {
-            exists: typeof file.exists === "boolean" ? file.exists : null,
-            sizeBytes: number(file.sizeBytes),
-        },
-    };
-}
-export function formatRecordingReceipt(receipt) {
-    const metric = (value, unit = "") => value === null ? "unknown" : `${value}${unit}`;
-    return [
-        `Recording ID: ${metric(receipt.recordingId)}`,
-        formatRecordingOutcome(receipt),
-        `Capture started: ${metric(receipt.capture.startedAt)}; ended: ${metric(receipt.capture.endedAt)}`,
-        `Wall-clock capture duration: ${metric(receipt.capture.durationMs, " ms")}`,
-        `Captured frames (received, not pixel-unique): ${metric(receipt.capturedFrames)}`,
-        `Captured-frame rate: ${metric(receipt.capture.averageFps, " fps")}`,
-        `First frame: ${metric(receipt.capture.firstFrameAt)}; after start: ${metric(receipt.capture.firstFrameAfterMs, " ms")}`,
-        `Last frame: ${metric(receipt.capture.lastFrameAt)}; after start: ${metric(receipt.capture.lastFrameAfterMs, " ms")}`,
-        `Maximum frame gap: ${metric(receipt.capture.maxFrameGapMs, " ms")}; timestamp source: ${metric(receipt.capture.timestampSource)}`,
-        `Written frames: ${metric(receipt.output.frames)}; Encoded frames: ${metric(receipt.output.encodedFrames)}`,
-        `Held frames: ${metric(receipt.output.heldFrames)}; dropped frames: ${metric(receipt.output.droppedFrames)}; skipped frames: ${metric(receipt.output.skippedFrames)}`,
-        `Nominal/output FPS: ${metric(receipt.output.fps)}; output duration (encoded frames/fps): ${metric(receipt.output.durationMs, " ms")}`,
-        receipt.warning,
-    ].join("\n");
-}

package/dist/extensions/agent-browser/lib/results/recovery-actions.js

@@ -1,118 +0,0 @@
-import { buildNextToolAction, withOptionalSessionArgs, } from "./next-actions.js";
-export const AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS = {
-    aboutBlankListTabs: "list-tabs-for-about-blank-recovery",
-    connectedSessionGetUrl: "verify-connected-session-url",
-    connectedSessionListTabs: "list-connected-session-tabs",
-    genericTabDriftListTabs: "list-tabs-for-recovery",
-    noActivePageListTabs: "list-tabs-after-no-active-page",
-    selectIntendedTabAfterDrift: "select-intended-tab-after-drift",
-    snapshotAfterTabRecovery: "snapshot-after-tab-recovery",
-    tabDriftListTabs: "list-tabs-for-tab-drift-recovery",
-    tabGoneListTabs: "list-tabs-after-tab-gone",
-    tabGoneNewTab: "open-tab-after-tab-gone",
-};
-export const AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS = {
-    click: "click-current-editable-ref",
-    focus: "focus-current-editable-ref",
-};
-function getNumberedAgentBrowserNextActionId(baseId, index, total) {
-    return total > 1 ? `${baseId}-${index + 1}` : baseId;
-}
-export function getAgentBrowserRichInputRecoveryNextActionId(kind, index, candidateCount) {
-    return getNumberedAgentBrowserNextActionId(AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS[kind], index, candidateCount);
-}
-export function getAgentBrowserRichInputRecoveryNextActionIds(candidateCount) {
-    const ids = [];
-    for (let index = 0; index < candidateCount; index += 1) {
-        ids.push(getAgentBrowserRichInputRecoveryNextActionId("focus", index, candidateCount), getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount));
-    }
-    return ids;
-}
-function getRecoveryTargetDescription(recovery) {
-    const target = [recovery.targetTitle, recovery.targetUrl]
-        .filter((item) => item !== undefined && item.length > 0)
-        .join(" at ");
-    return target.length > 0 ? target : "the intended tab";
-}
-function isStableTabId(tab) {
-    return /^t\d+$/.test(tab ?? "");
-}
-function buildTabSnapshotRecoveryAction(options) {
-    if (options.recovery.recoveryApplied === true) {
-        return buildNextToolAction({
-            args: options.sessionArgs(["snapshot", "-i"]),
-            id: options.id,
-            reason: options.reason,
-            safety: options.safety,
-        });
-    }
-    return buildNextToolAction({
-        args: options.sessionArgs(["batch", "--bail"]),
-        id: options.id,
-        reason: `${options.reason} The batch selects and verifies the stable tab before snapshotting.`,
-        safety: `${options.safety} A failed tab selection or URL check stops before the snapshot.`,
-        stdin: JSON.stringify([
-            ["tab", options.tabId],
-            ["get", "url"],
-            ["snapshot", "-i"],
-        ]),
-    });
-}
-export function buildRecoveryNextActions(recovery) {
-    const sessionArgs = (args) => withOptionalSessionArgs(recovery.sessionName, args);
-    if (recovery.kind === "connected-session") {
-        return [
-            buildNextToolAction({
-                args: sessionArgs(["get", "url"]),
-                id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.connectedSessionGetUrl,
-                reason: "Verify the attached page URL before any page-content inspection.",
-                safety: "Read-only URL lookup. The wrapper keeps page inspection blocked if the active target URL cannot be verified.",
-            }),
-            buildNextToolAction({
-                args: sessionArgs(["tab", "list"]),
-                id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.connectedSessionListTabs,
-                reason: "Inspect tabs exposed by the connected CDP endpoint before assuming the app surface is active.",
-                safety: "Read-only. Raw connect can succeed before the desktop app has an active rendered page.",
-            }),
-        ];
-    }
-    if (recovery.kind === "no-active-page") {
-        return [
-            buildNextToolAction({
-                args: sessionArgs(["tab", "list"]),
-                id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.noActivePageListTabs,
-                reason: "The snapshot found no active page; inspect the session tabs before retrying refs.",
-                safety: "Read-only tab listing for the same connected session.",
-            }),
-        ];
-    }
-    const targetDescription = getRecoveryTargetDescription(recovery);
-    const listAction = buildNextToolAction({
-        args: sessionArgs(["tab", "list"]),
-        id: recovery.kind === "about-blank"
-            ? AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.aboutBlankListTabs
-            : AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabDriftListTabs,
-        reason: `Inspect tabs for ${targetDescription} before continuing after tab drift.`,
-        safety: "Read-only tab listing; prefer stable tN tab ids over positional tab guesses.",
-    });
-    if (!isStableTabId(recovery.selectedTab)) {
-        return [listAction];
-    }
-    return [
-        listAction,
-        buildNextToolAction({
-            args: sessionArgs(["tab", recovery.selectedTab]),
-            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.selectIntendedTabAfterDrift,
-            reason: `Re-select ${targetDescription} with the stable tab id already observed by the wrapper.`,
-            safety: "Switches only the active tab in this browser session; it does not mutate page content.",
-        }),
-        buildTabSnapshotRecoveryAction({
-            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.snapshotAfterTabRecovery,
-            reason: "Refresh interactive refs on the recovered tab before using @e refs again.",
-            recovery,
-            safety: "Read-only snapshot. Treat previous refs as stale until this succeeds.",
-            sessionArgs,
-            tabId: recovery.selectedTab,
-        }),
-    ];
-}

package/dist/extensions/agent-browser/lib/results/recovery-next-actions.js

@@ -1,60 +0,0 @@
-import { buildAgentBrowserNextActions } from "./action-recommendations.js";
-import { withOptionalSessionArgs } from "./next-actions.js";
-export function buildConnectedSessionNextActions(sessionName) {
-    if ((sessionName ?? "") === "") {
-        return [];
-    }
-    return (buildAgentBrowserNextActions({
-        recovery: { kind: "connected-session", sessionName },
-        resultCategory: "success",
-        successCategory: "completed",
-    }) ?? []);
-}
-export function buildNoActivePageNextActions(sessionName) {
-    if ((sessionName ?? "") === "") {
-        return [];
-    }
-    return (buildAgentBrowserNextActions({
-        recovery: { kind: "no-active-page", sessionName },
-        resultCategory: "failure",
-    }) ?? []);
-}
-export function buildPendingWebMcpNextActions(sessionName) {
-    return [
-        {
-            id: "verify-page-target-after-pending-webmcp",
-            params: { args: withOptionalSessionArgs(sessionName, ["get", "url"]) },
-            reason: "Verify the current page target before taking a fresh snapshot; use webmcp result or cancel to settle the detached invocation.",
-            safety: "Read-only URL inspection. It does not settle the pending page tool, which may still mutate or navigate later.",
-            tool: "agent_browser",
-        },
-    ];
-}
-function getSessionTabRecoveryContext(options) {
-    return {
-        kind: options.kind,
-        recoveryApplied: options.recoveryApplied,
-        selectedTab: options.tabCorrection?.selectedTab,
-        sessionName: options.sessionName,
-        targetTitle: options.tabCorrection?.targetTitle ?? options.target?.title,
-        targetUrl: options.tabCorrection?.targetUrl ?? options.target?.url,
-    };
-}
-export function buildSessionTabRecoveryNextActions(options) {
-    const resultCategory = options.resultCategory ?? "success";
-    return (buildAgentBrowserNextActions({
-        recovery: getSessionTabRecoveryContext(options),
-        resultCategory,
-        successCategory: resultCategory === "success" ? "completed" : undefined,
-    }) ?? []);
-}
-export function buildSessionAwareStaleRefNextActions(sessionName) {
-    return (buildAgentBrowserNextActions({ failureCategory: "stale-ref", resultCategory: "failure" }) ?? []).map((action) => {
-        const actionArgs = action.params?.args;
-        return Object.assign({}, action, {
-            params: action.params && actionArgs
-                ? { ...action.params, args: withOptionalSessionArgs(sessionName, actionArgs) }
-                : action.params,
-        });
-    });
-}

package/dist/extensions/agent-browser/lib/results/selector-recovery-target.js

@@ -1,83 +0,0 @@
-const SELECTOR_RECOVERY_ACTION_NAMES = [
-    "check",
-    "click",
-    "fill",
-    "select",
-    "uncheck",
-];
-function isSelectorRecoveryActionName(action) {
-    return SELECTOR_RECOVERY_ACTION_NAMES.some((name) => name === action);
-}
-function getFindNameFlagValue(args, startIndex) {
-    const index = args.indexOf("--name", startIndex);
-    const name = index >= 0 ? args.at(index + 1) : undefined;
-    return name !== undefined && name.length > 0 ? name : undefined;
-}
-function collectFindTrailingValues(args, startIndex) {
-    const values = [];
-    for (const token of args.slice(startIndex)) {
-        if (token.length === 0 || token.startsWith("-")) {
-            break;
-        }
-        values.push(token);
-    }
-    return values;
-}
-function getSelectTarget(args, index, locator, value) {
-    const optionValues = collectFindTrailingValues(args, index + 4);
-    if (locator === "role") {
-        if (!/^(?:combobox|listbox)$/i.test(value)) {
-            return undefined;
-        }
-        const targetName = getFindNameFlagValue(args, index + 4);
-        return targetName !== undefined
-            ? { action: "select", optionValues, roles: [value.toLowerCase()], targetName }
-            : undefined;
-    }
-    return locator === "label"
-        ? { action: "select", optionValues, roles: ["combobox", "listbox"], targetName: value }
-        : undefined;
-}
-function getTextTarget(action, locator, targetName, text) {
-    if (locator === "text" && action === "click") {
-        return { action, roles: ["button", "link"], targetName };
-    }
-    if ((locator === "text" || locator === "placeholder") && action === "fill") {
-        return { action, roles: ["searchbox", "textbox"], targetName, text };
-    }
-    return locator === "label" && action === "fill"
-        ? { action, roles: ["textbox"], targetName, text }
-        : undefined;
-}
-export function getFindVisibleRefFallbackTarget(args) {
-    const index = args[0] === "--session" ? 2 : 0;
-    if (args[index] !== "find") {
-        return undefined;
-    }
-    const locator = args.at(index + 1);
-    const value = args.at(index + 2);
-    const action = args.at(index + 3);
-    if (locator === undefined ||
-        locator.length === 0 ||
-        value === undefined ||
-        value.length === 0 ||
-        !isSelectorRecoveryActionName(action)) {
-        return undefined;
-    }
-    return getFindActionTarget(args, { index, locator, value, action });
-}
-function getFindActionTarget(args, command) {
-    const { index, locator, value, action } = command;
-    if (action === "select") {
-        return getSelectTarget(args, index, locator, value);
-    }
-    const text = action === "fill" ? args.at(index + 4) : undefined;
-    if (action === "fill" && (text === undefined || text.length === 0)) {
-        return undefined;
-    }
-    if (locator === "role") {
-        const targetName = getFindNameFlagValue(args, index + 4);
-        return targetName !== undefined ? { action, roles: [value], targetName, text } : undefined;
-    }
-    return getTextTarget(action, locator, value, text);
-}

package/dist/extensions/agent-browser/lib/results/selector-recovery.js

@@ -1,261 +0,0 @@
-import { isRecord } from "../parsing.js";
-import { extractRefSnapshotFromData } from "../session-page-observation.js";
-import { getEditableRefEvidence } from "./editable-ref-evidence.js";
-import { withOptionalSessionArgs } from "./next-actions.js";
-import { getAgentBrowserRichInputRecoveryNextActionId, getAgentBrowserRichInputRecoveryNextActionIds, } from "./recovery-actions.js";
-import { getSnapshotLineTextByRef, getSnapshotRefRecord, getSnapshotRefRole, } from "./snapshot-refs.js";
-import { compareRefIds } from "./text.js";
-import { getFindVisibleRefFallbackTarget, } from "./selector-recovery-target.js";
-const VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT = 3;
-const EDITABLE_CONTROL_ROLES = new Set(["combobox", "searchbox", "textbox"]);
-const RICH_INPUT_RECOVERY_EDITABLE_ROLES = new Set(["searchbox", "textbox"]);
-const RICH_INPUT_RECOVERY_HINT = "After the editable ref is focused, use keyboard type when a framework-controlled editor requires real key events. keyboard inserttext is paste-like and needs separate application-state verification. Do not press Enter or otherwise submit unless the user flow explicitly calls for it.";
-export function getVisibleRefFallbackTarget(options) {
-    return (getFindVisibleRefFallbackTarget(options.commandTokens) ??
-        (options.compiledSemanticAction
-            ? getFindVisibleRefFallbackTarget(options.compiledSemanticAction.args)
-            : undefined));
-}
-function getDirectRefFallbackArgs(target, ref) {
-    if (target.action === "fill") {
-        return undefined;
-    }
-    if (target.action === "select") {
-        return target.optionValues && target.optionValues.length > 0
-            ? ["select", `@${ref}`, ...target.optionValues]
-            : undefined;
-    }
-    return [target.action, `@${ref}`];
-}
-function getCandidateEditableEvidence(snapshot, ref, entry, line) {
-    return snapshot
-        ? snapshot.refs?.[ref]?.isEditable
-        : getEditableRefEvidence({ ref: entry, text: line });
-}
-function matchesFallbackName(name, targetName) {
-    return (name !== undefined &&
-        name.length > 0 &&
-        normalizeSemanticActionAccessibleName(name) === targetName);
-}
-function isDisallowedEditableFill(action, evidence, role) {
-    return action === "fill" && evidence === false && EDITABLE_CONTROL_ROLES.has(role.toLowerCase());
-}
-function getVisibleRefFallbackCandidates(target, snapshotData, refSnapshot) {
-    const refs = refSnapshot?.refs ?? getSnapshotRefRecord(snapshotData);
-    if (!refs) {
-        return [];
-    }
-    const snapshotLineByRef = getSnapshotLineTextByRef(snapshotData);
-    const roleOrder = target.roles.map((role) => role.toLowerCase());
-    const targetName = normalizeSemanticActionAccessibleName(target.targetName);
-    const candidates = Object.entries(refs).flatMap(([ref, entry]) => {
-        if (!/^e\d+$/.test(ref) || !isRecord(entry)) {
-            return [];
-        }
-        const snapshotLine = snapshotLineByRef.get(ref);
-        const editableEvidence = getCandidateEditableEvidence(refSnapshot, ref, entry, snapshotLine);
-        const role = getSnapshotRefRole(entry, editableEvidence);
-        const name = typeof entry.name === "string" ? entry.name : undefined;
-        if (!matchesFallbackName(name, targetName) || !roleOrder.includes(role.toLowerCase())) {
-            return [];
-        }
-        if (isDisallowedEditableFill(target.action, editableEvidence, role)) {
-            return [];
-        }
-        const directRefArgs = getDirectRefFallbackArgs(target, ref);
-        return [
-            {
-                action: target.action,
-                ...(directRefArgs ? { args: directRefArgs } : {}),
-                name,
-                reason: `Current snapshot shows ${role} ${JSON.stringify(name)} at @${ref}, matching the failed ${target.action} locator exactly.`,
-                ref: `@${ref}`,
-                role,
-                ...(editableEvidence !== undefined ? { editableEvidence } : {}),
-            },
-        ];
-    });
-    candidates.sort((left, right) => {
-        const difference = roleOrder.indexOf(left.role.toLowerCase()) - roleOrder.indexOf(right.role.toLowerCase());
-        return difference !== 0 ? difference : compareRefIds(left.ref.slice(1), right.ref.slice(1));
-    });
-    return candidates.slice(0, VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT);
-}
-export function buildVisibleRefFallbackDiagnosticFromSnapshot(options) {
-    const snapshot = extractRefSnapshotFromData(options.snapshotData);
-    if (!snapshot) {
-        return undefined;
-    }
-    const candidates = getVisibleRefFallbackCandidates(options.target, options.snapshotData);
-    if (candidates.length === 0) {
-        return undefined;
-    }
-    return {
-        candidates,
-        snapshot,
-        summary: candidates.length === 1
-            ? `Current snapshot has one exact visible ref match for ${options.target.action} ${JSON.stringify(options.target.targetName)}.`
-            : `Current snapshot has ${candidates.length} exact visible ref matches for ${options.target.action} ${JSON.stringify(options.target.targetName)}; choose only if the intended control is unambiguous.`,
-        target: {
-            action: options.target.action,
-            roles: options.target.roles,
-            targetName: options.target.targetName,
-        },
-    };
-}
-function resolveFillCandidateArgs(candidates, text, allowFill) {
-    if (allowFill !== true || candidates.length !== 1 || text === undefined) {
-        return undefined;
-    }
-    const candidate = candidates.at(0);
-    if (!candidate ||
-        candidate.editableEvidence === false ||
-        !EDITABLE_CONTROL_ROLES.has(candidate.role.toLowerCase())) {
-        return undefined;
-    }
-    return ["fill", candidate.ref, text];
-}
-function resolveSelectCandidateArgs(candidates, values) {
-    if (candidates.length !== 1 || !values || values.length === 0) {
-        return undefined;
-    }
-    const candidate = candidates.at(0);
-    return candidate ? ["select", candidate.ref, ...values] : undefined;
-}
-function resolveCandidateArgs(target, candidates, allowFill, selectValues) {
-    if (target.action === "fill") {
-        return resolveFillCandidateArgs(candidates, target.text, allowFill);
-    }
-    if (target.action === "select") {
-        return resolveSelectCandidateArgs(candidates, selectValues);
-    }
-    return candidates.find((candidate) => candidate.args !== undefined)?.args;
-}
-export function resolveVisibleRefActionFromSnapshot(options) {
-    const target = getFindVisibleRefFallbackTarget(options.compiledAction.args);
-    if (!target) {
-        return undefined;
-    }
-    const snapshot = options.refSnapshot ?? extractRefSnapshotFromData(options.snapshotData);
-    if (!snapshot) {
-        return undefined;
-    }
-    const selectOptionValues = options.compiledAction.values && options.compiledAction.values.length > 0
-        ? options.compiledAction.values
-        : target.optionValues;
-    const effectiveTarget = target.action === "select" && selectOptionValues
-        ? { ...target, optionValues: selectOptionValues }
-        : target;
-    const candidates = getVisibleRefFallbackCandidates(effectiveTarget, options.snapshotData, options.refSnapshot);
-    const args = resolveCandidateArgs(effectiveTarget, candidates, options.allowFill, selectOptionValues);
-    return args ? { args, snapshot } : undefined;
-}
-export function buildVisibleRefFallbackNextActions(options) {
-    const ambiguous = options.diagnostic.candidates.length > 1;
-    return options.diagnostic.candidates.flatMap((candidate, index) => candidate.args
-        ? [
-            {
-                id: ambiguous ? `try-current-visible-ref-${index + 1}` : "try-current-visible-ref",
-                params: { args: withOptionalSessionArgs(options.sessionName, candidate.args) },
-                reason: candidate.reason,
-                safety: ambiguous
-                    ? "Several current refs share the same exact role/name. Inspect the snapshot and use only the ref that clearly matches the intended target."
-                    : "Use only while this current snapshot still represents the page; refresh refs first if the page changed.",
-                tool: "agent_browser",
-            },
-        ]
-        : []);
-}
-export function formatVisibleRefFallbackText(diagnostic) {
-    if (!diagnostic) {
-        return undefined;
-    }
-    return [
-        "Current snapshot ref fallback:",
-        ...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role.length > 0 ? ` ${candidate.role}` : ""} ${JSON.stringify(candidate.name)}: ${candidate.reason}`),
-    ].join("\n");
-}
-export function sanitizeVisibleRefFallbackDiagnostic(diagnostic) {
-    return {
-        candidates: diagnostic.candidates.map(({ editableEvidence: _editableEvidence, ...candidate }) => candidate),
-        snapshot: diagnostic.snapshot,
-        summary: diagnostic.summary,
-        target: diagnostic.target,
-    };
-}
-function isRichInputRecoveryCandidate(candidate) {
-    return (candidate.action === "fill" &&
-        candidate.editableEvidence !== false &&
-        RICH_INPUT_RECOVERY_EDITABLE_ROLES.has(candidate.role.toLowerCase()));
-}
-export function buildRichInputRecoveryDiagnostic(diagnostic) {
-    if (!diagnostic || diagnostic.target.action !== "fill") {
-        return undefined;
-    }
-    const candidates = diagnostic.candidates
-        .filter(isRichInputRecoveryCandidate)
-        .map((candidate) => ({
-        clickArgs: ["click", candidate.ref],
-        focusArgs: ["focus", candidate.ref],
-        name: candidate.name,
-        reason: `Current snapshot shows editable ${candidate.role} ${JSON.stringify(candidate.name)} at ${candidate.ref}; focus or click it before keyboard insertion instead of retrying fill with copied text.`,
-        ref: candidate.ref,
-        role: candidate.role,
-    }));
-    if (candidates.length === 0) {
-        return undefined;
-    }
-    return {
-        candidates,
-        inputMethodHint: RICH_INPUT_RECOVERY_HINT,
-        nextActionIds: getAgentBrowserRichInputRecoveryNextActionIds(candidates.length),
-        summary: candidates.length === 1
-            ? "Fill locator missed, but the current snapshot has one exact editable ref candidate for safe keyboard-based recovery."
-            : `Fill locator missed, but the current snapshot has ${candidates.length} exact editable ref candidates; choose only if the intended input is unambiguous.`,
-        target: { roles: diagnostic.target.roles, targetName: diagnostic.target.targetName },
-    };
-}
-export function buildRichInputRecoveryNextActions(options) {
-    const candidateCount = options.diagnostic.candidates.length;
-    const ambiguous = candidateCount > 1;
-    return options.diagnostic.candidates.flatMap((candidate, index) => {
-        const focusId = getAgentBrowserRichInputRecoveryNextActionId("focus", index, candidateCount);
-        const clickId = getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount);
-        const safety = ambiguous
-            ? `Several editable refs share the same exact name. Inspect the current snapshot and use only the ${candidate.ref} ${candidate.role} if it is clearly the intended input. No fill text or submit key is included.`
-            : "Does not include fill text or submit the form. After focus/click succeeds, use keyboard type for framework-controlled editors; use keyboard inserttext only with separate application-state verification.";
-        return [
-            {
-                id: focusId,
-                params: { args: withOptionalSessionArgs(options.sessionName, candidate.focusArgs) },
-                reason: candidate.reason,
-                safety,
-                tool: "agent_browser",
-            },
-            {
-                id: clickId,
-                params: { args: withOptionalSessionArgs(options.sessionName, candidate.clickArgs) },
-                reason: `Click ${candidate.ref} to focus the editable ${candidate.role} before keyboard insertion when focus alone is insufficient.`,
-                safety: `${safety} A click may run normal focus/click handlers, but this action does not press Enter or auto-submit.`,
-                tool: "agent_browser",
-            },
-        ];
-    });
-}
-export function formatRichInputRecoveryText(diagnostic) {
-    if (!diagnostic) {
-        return undefined;
-    }
-    return [
-        "Rich input recovery:",
-        ...diagnostic.candidates.map((candidate, index) => {
-            const focusId = diagnostic.nextActionIds.at(index * 2);
-            const clickId = diagnostic.nextActionIds.at(index * 2 + 1);
-            return `- ${candidate.ref} ${candidate.role} ${JSON.stringify(candidate.name)}: use ${focusId ?? "undefined"} or ${clickId ?? "undefined"}; then use keyboard type for framework-controlled editors, or paste-like keyboard inserttext only with separate application-state verification.`;
-        }),
-        `- ${diagnostic.inputMethodHint}`,
-    ].join("\n");
-}
-function normalizeSemanticActionAccessibleName(name) {
-    return name.replace(/\s+/g, " ").trim().toLowerCase();
-}