pi-agent-browser-native 0.9.3 → 0.9.4

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

@@ -1,5 +1,22 @@
 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;
 }
@@ -7,34 +24,55 @@ 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)
+    if (!isRecord(value) || typeof value.path !== "string" || value.path.length === 0) {
         return undefined;
-    const capture = isRecord(value.capture) ? value.capture : {};
-    const output = isRecord(value.output) ? value.output : {};
-    const file = isRecord(value.file) ? value.file : {};
+    }
+    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: typeof value.success === "boolean" ? value.success : value.success === null ? null : outcome ?? null,
-        error: text(value.error), frames: number(value.frames), capturedFrames: number(value.capturedFrames), fps: number(value.fps),
+        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),
+            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),
+            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) },
+        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)}`,
-        `Native recording outcome: ${receipt.success === true ? "succeeded" : receipt.success === false ? "failed" : "pending/unknown"}${receipt.error ? ` — ${receipt.error}` : ""}`,
+        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)}`,

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

@@ -1,4 +1,4 @@
-import { buildNextToolAction, withOptionalSessionArgs } from "./next-actions.js";
+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",
@@ -29,7 +29,9 @@ export function getAgentBrowserRichInputRecoveryNextActionIds(candidateCount) {
     return ids;
 }
 function getRecoveryTargetDescription(recovery) {
-    const target = [recovery.targetTitle, recovery.targetUrl].filter((item) => item !== undefined && item.length > 0).join(" at ");
+    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) {
@@ -49,7 +51,11 @@ function buildTabSnapshotRecoveryAction(options) {
         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"]]),
+        stdin: JSON.stringify([
+            ["tab", options.tabId],
+            ["get", "url"],
+            ["snapshot", "-i"],
+        ]),
     });
 }
 export function buildRecoveryNextActions(recovery) {
@@ -83,12 +89,15 @@ export function buildRecoveryNextActions(recovery) {
     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,
+        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))
+    if (!isStableTabId(recovery.selectedTab)) {
         return [listAction];
+    }
     return [
         listAction,
         buildNextToolAction({

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

@@ -1,52 +1,60 @@
 import { buildAgentBrowserNextActions } from "./action-recommendations.js";
 import { withOptionalSessionArgs } from "./next-actions.js";
 export function buildConnectedSessionNextActions(sessionName) {
-    if (!sessionName)
+    if ((sessionName ?? "") === "") {
         return [];
-    return buildAgentBrowserNextActions({
+    }
+    return (buildAgentBrowserNextActions({
         recovery: { kind: "connected-session", sessionName },
         resultCategory: "success",
         successCategory: "completed",
-    }) ?? [];
+    }) ?? []);
 }
 export function buildNoActivePageNextActions(sessionName) {
-    if (!sessionName)
+    if ((sessionName ?? "") === "") {
         return [];
-    return buildAgentBrowserNextActions({
+    }
+    return (buildAgentBrowserNextActions({
         recovery: { kind: "no-active-page", sessionName },
         resultCategory: "failure",
-    }) ?? [];
+    }) ?? []);
 }
 export function buildPendingWebMcpNextActions(sessionName) {
-    return [{
+    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: {
-            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,
-        },
+    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 {
-            ...action,
-            params: action.params && actionArgs ? { ...action.params, args: withOptionalSessionArgs(sessionName, actionArgs) } : action.params,
-        };
+        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

@@ -0,0 +1,83 @@
+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,105 +1,70 @@
 import { isRecord } from "../parsing.js";
-import { extractRefSnapshotFromData } from "../session-page-state.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";
-const SELECTOR_RECOVERY_ACTION_NAMES = new Set(["check", "click", "fill", "select", "uncheck"]);
+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.";
-function isSelectorRecoveryActionName(action) {
-    return SELECTOR_RECOVERY_ACTION_NAMES.has(action);
-}
-function getFindNameFlagValue(args, startIndex) {
-    const nameFlagIndex = args.indexOf("--name", startIndex);
-    const name = nameFlagIndex >= 0 ? args[nameFlagIndex + 1] : undefined;
-    return typeof name === "string" && name.length > 0 ? name : undefined;
-}
-function collectFindTrailingValues(args, startIndex) {
-    const values = [];
-    for (let index = startIndex; index < args.length; index += 1) {
-        const token = args[index];
-        if (!token || token.startsWith("-"))
-            break;
-        values.push(token);
-    }
-    return values;
+export function getVisibleRefFallbackTarget(options) {
+    return (getFindVisibleRefFallbackTarget(options.commandTokens) ??
+        (options.compiledSemanticAction
+            ? getFindVisibleRefFallbackTarget(options.compiledSemanticAction.args)
+            : undefined));
 }
-function getFindVisibleRefFallbackTarget(args, options = {}) {
-    const findIndex = args[0] === "--session" ? 2 : 0;
-    if (args[findIndex] !== "find")
+function getDirectRefFallbackArgs(target, ref) {
+    if (target.action === "fill") {
         return undefined;
-    const locator = args[findIndex + 1];
-    const value = args[findIndex + 2];
-    const action = args[findIndex + 3];
-    if (!locator || !value || !isSelectorRecoveryActionName(action))
-        return undefined;
-    if (action === "select") {
-        const optionValues = collectFindTrailingValues(args, findIndex + 4);
-        if (locator === "role") {
-            if (!/^(?:combobox|listbox)$/i.test(value))
-                return undefined;
-            const targetName = getFindNameFlagValue(args, findIndex + 4);
-            return targetName ? { action, optionValues, roles: [value.toLowerCase()], targetName } : undefined;
-        }
-        if (locator === "label") {
-            return { action, optionValues, roles: ["combobox", "listbox"], targetName: value };
-        }
-        return undefined;
-    }
-    const text = action === "fill" ? args[findIndex + 4] : undefined;
-    if (action === "fill" && (!text || (!options.allowLeadingDashFillText && text.startsWith("-"))))
-        return undefined;
-    if (locator === "role") {
-        const targetName = getFindNameFlagValue(args, findIndex + 4);
-        return targetName ? { action, roles: [value], targetName, text } : undefined;
-    }
-    if (locator === "text" && action === "click") {
-        return { action, roles: ["button", "link"], targetName: value };
-    }
-    if (locator === "text" && action === "fill") {
-        return { action, roles: ["searchbox", "textbox"], targetName: value, text };
-    }
-    if (locator === "label" && action === "fill") {
-        return { action, roles: ["textbox"], targetName: value, text };
     }
-    if (locator === "placeholder" && action === "fill") {
-        return { action, roles: ["searchbox", "textbox"], targetName: value, text };
+    if (target.action === "select") {
+        return target.optionValues && target.optionValues.length > 0
+            ? ["select", `@${ref}`, ...target.optionValues]
+            : undefined;
     }
-    return undefined;
+    return [target.action, `@${ref}`];
 }
-export function getVisibleRefFallbackTarget(options) {
-    return getFindVisibleRefFallbackTarget(options.commandTokens, { allowLeadingDashFillText: true }) ?? (options.compiledSemanticAction ? getFindVisibleRefFallbackTarget(options.compiledSemanticAction.args, { allowLeadingDashFillText: true }) : undefined);
+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)
+    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))
+        if (!/^e\d+$/.test(ref) || !isRecord(entry)) {
             return [];
+        }
         const snapshotLine = snapshotLineByRef.get(ref);
-        const editableEvidence = refSnapshot ? refSnapshot.refs?.[ref]?.isEditable : getEditableRefEvidence({ ref: entry, text: snapshotLine });
+        const editableEvidence = getCandidateEditableEvidence(refSnapshot, ref, entry, snapshotLine);
         const role = getSnapshotRefRole(entry, editableEvidence);
         const name = typeof entry.name === "string" ? entry.name : undefined;
-        if (!role || !name || !roleOrder.includes(role.toLowerCase()) || normalizeSemanticActionAccessibleName(name) !== targetName)
+        if (!matchesFallbackName(name, targetName) || !roleOrder.includes(role.toLowerCase())) {
             return [];
-        if (target.action === "fill" && editableEvidence === false && EDITABLE_CONTROL_ROLES.has(role.toLowerCase()))
+        }
+        if (isDisallowedEditableFill(target.action, editableEvidence, role)) {
             return [];
-        const directRefArgs = target.action === "fill"
-            ? undefined
-            : target.action === "select" && target.optionValues && target.optionValues.length > 0
-                ? ["select", `@${ref}`, ...target.optionValues]
-                : target.action === "select"
-                    ? undefined
-                    : [target.action, `@${ref}`];
-        return [{
+        }
+        const directRefArgs = getDirectRefFallbackArgs(target, ref);
+        return [
+            {
                 action: target.action,
                 ...(directRefArgs ? { args: directRefArgs } : {}),
                 name,
@@ -107,34 +72,74 @@ function getVisibleRefFallbackCandidates(target, snapshotData, refSnapshot) {
                 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));
     });
-    candidates.sort((left, right) => roleOrder.indexOf(left.role.toLowerCase()) - roleOrder.indexOf(right.role.toLowerCase()) || 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)
+    if (!snapshot) {
         return undefined;
+    }
     const candidates = getVisibleRefFallbackCandidates(options.target, options.snapshotData);
-    if (candidates.length === 0)
+    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 },
+        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, { allowLeadingDashFillText: true });
-    if (!target)
+    const target = getFindVisibleRefFallbackTarget(options.compiledAction.args);
+    if (!target) {
         return undefined;
+    }
     const snapshot = options.refSnapshot ?? extractRefSnapshotFromData(options.snapshotData);
-    if (!snapshot)
+    if (!snapshot) {
         return undefined;
+    }
     const selectOptionValues = options.compiledAction.values && options.compiledAction.values.length > 0
         ? options.compiledAction.values
         : target.optionValues;
@@ -142,45 +147,32 @@ export function resolveVisibleRefActionFromSnapshot(options) {
         ? { ...target, optionValues: selectOptionValues }
         : target;
     const candidates = getVisibleRefFallbackCandidates(effectiveTarget, options.snapshotData, options.refSnapshot);
-    if (effectiveTarget.action === "fill") {
-        if (!options.allowFill || candidates.length !== 1 || effectiveTarget.text === undefined)
-            return undefined;
-        const [candidate] = candidates;
-        if (!candidate || candidate.editableEvidence === false || !EDITABLE_CONTROL_ROLES.has(candidate.role.toLowerCase()))
-            return undefined;
-        return { args: ["fill", candidate.ref, effectiveTarget.text], snapshot };
-    }
-    if (effectiveTarget.action === "select") {
-        if (candidates.length !== 1 || !selectOptionValues || selectOptionValues.length === 0)
-            return undefined;
-        const [candidate] = candidates;
-        if (!candidate)
-            return undefined;
-        return { args: ["select", candidate.ref, ...selectOptionValues], snapshot };
-    }
-    const candidate = candidates.find((item) => item.args !== undefined);
-    if (!candidate?.args)
-        return undefined;
-    return { args: candidate.args, snapshot };
+    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",
-        }] : []);
+    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)
+    if (!diagnostic) {
         return undefined;
+    }
     return [
         "Current snapshot ref fallback:",
-        ...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role ? ` ${candidate.role}` : ""} ${JSON.stringify(candidate.name)}: ${candidate.reason}`),
+        ...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role.length > 0 ? ` ${candidate.role}` : ""} ${JSON.stringify(candidate.name)}: ${candidate.reason}`),
     ].join("\n");
 }
 export function sanitizeVisibleRefFallbackDiagnostic(diagnostic) {
@@ -192,12 +184,17 @@ export function sanitizeVisibleRefFallbackDiagnostic(diagnostic) {
     };
 }
 function isRichInputRecoveryCandidate(candidate) {
-    return candidate.action === "fill" && candidate.editableEvidence !== false && RICH_INPUT_RECOVERY_EDITABLE_ROLES.has(candidate.role.toLowerCase());
+    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")
+    if (!diagnostic || diagnostic.target.action !== "fill") {
         return undefined;
-    const candidates = diagnostic.candidates.filter(isRichInputRecoveryCandidate).map((candidate) => ({
+    }
+    const candidates = diagnostic.candidates
+        .filter(isRichInputRecoveryCandidate)
+        .map((candidate) => ({
         clickArgs: ["click", candidate.ref],
         focusArgs: ["focus", candidate.ref],
         name: candidate.name,
@@ -205,8 +202,9 @@ export function buildRichInputRecoveryDiagnostic(diagnostic) {
         ref: candidate.ref,
         role: candidate.role,
     }));
-    if (candidates.length === 0)
+    if (candidates.length === 0) {
         return undefined;
+    }
     return {
         candidates,
         inputMethodHint: RICH_INPUT_RECOVERY_HINT,
@@ -245,13 +243,15 @@ export function buildRichInputRecoveryNextActions(options) {
     });
 }
 export function formatRichInputRecoveryText(diagnostic) {
-    if (!diagnostic)
+    if (!diagnostic) {
         return undefined;
+    }
     return [
         "Rich input recovery:",
         ...diagnostic.candidates.map((candidate, index) => {
-            const [focusId, clickId] = diagnostic.nextActionIds.slice(index * 2, index * 2 + 2);
-            return `- ${candidate.ref} ${candidate.role} ${JSON.stringify(candidate.name)}: use ${focusId} or ${clickId}; then use keyboard type for framework-controlled editors, or paste-like keyboard inserttext only with separate application-state verification.`;
+            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");