pi-agent-browser-native 0.2.32 → 0.2.34

package/extensions/agent-browser/lib/results/recovery-actions.ts

@@ -0,0 +1,139 @@
+/**
+ * Purpose: Centralize recovery-oriented nextAction ids and action construction.
+ * Responsibilities: Build tab/about:blank/no-active-page/connected-session follow-ups and rich-input recovery ids.
+ * Scope: Recovery action contracts only; result category classification and artifact follow-ups live elsewhere.
+ * Usage: Imported by shared result action builders and the extension entrypoint.
+ * Invariants/Assumptions: Ids are public machine-readable contracts mirrored by docs and tests.
+ */
+
+import { buildNextToolAction, type AgentBrowserNextAction, withOptionalSessionArgs } from "./next-actions.js";
+
+export type AgentBrowserRecoveryKind = "about-blank" | "connected-session" | "no-active-page" | "tab-drift";
+
+export interface AgentBrowserRecoveryContext {
+	kind: AgentBrowserRecoveryKind;
+	recoveryApplied?: boolean;
+	selectedTab?: string;
+	sessionName?: string;
+	targetTitle?: string;
+	targetUrl?: string;
+}
+
+export const AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS = {
+	aboutBlankListTabs: "list-tabs-for-about-blank-recovery",
+	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",
+} as const;
+
+export const AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS = {
+	click: "click-current-editable-ref",
+	focus: "focus-current-editable-ref",
+} as const;
+
+export type AgentBrowserRichInputRecoveryNextActionKind = keyof typeof AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS;
+
+function getNumberedAgentBrowserNextActionId(baseId: string, index: number, total: number): string {
+	return total > 1 ? `${baseId}-${index + 1}` : baseId;
+}
+
+export function getAgentBrowserRichInputRecoveryNextActionId(kind: AgentBrowserRichInputRecoveryNextActionKind, index: number, candidateCount: number): string {
+	return getNumberedAgentBrowserNextActionId(AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS[kind], index, candidateCount);
+}
+
+export function getAgentBrowserRichInputRecoveryNextActionIds(candidateCount: number): string[] {
+	const ids: string[] = [];
+	for (let index = 0; index < candidateCount; index += 1) {
+		ids.push(
+			getAgentBrowserRichInputRecoveryNextActionId("focus", index, candidateCount),
+			getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount),
+		);
+	}
+	return ids;
+}
+
+function getRecoveryTargetDescription(recovery: AgentBrowserRecoveryContext): string {
+	const target = [recovery.targetTitle, recovery.targetUrl].filter((item): item is string => item !== undefined && item.length > 0).join(" at ");
+	return target.length > 0 ? target : "the intended tab";
+}
+
+function isStableTabId(tab: string | undefined): tab is string {
+	return /^t\d+$/.test(tab ?? "");
+}
+
+function buildTabSnapshotRecoveryAction(options: {
+	id: string;
+	reason: string;
+	recovery: AgentBrowserRecoveryContext;
+	safety: string;
+	sessionArgs: (args: string[]) => string[];
+	tabId: string;
+}): AgentBrowserNextAction {
+	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"]),
+		id: options.id,
+		reason: `${options.reason} The batch selects the stable tab before snapshotting.`,
+		safety: `${options.safety} The snapshot retry is atomic with tab selection, so it does not assume the intended tab is already active.`,
+		stdin: JSON.stringify([["tab", options.tabId], ["snapshot", "-i"]]),
+	});
+}
+
+export function buildRecoveryNextActions(recovery: AgentBrowserRecoveryContext): AgentBrowserNextAction[] {
+	const sessionArgs = (args: string[]) => withOptionalSessionArgs(recovery.sessionName, args);
+	if (recovery.kind === "connected-session") {
+		return [
+			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/extensions/agent-browser/lib/results/recovery-next-actions.ts

@@ -0,0 +1,71 @@
+/**
+ * Purpose: Build session-aware recovery nextActions that combine result category policy with known session/tab context.
+ * Responsibilities: Prefix recovery argv with the active session and adapt tab/about:blank/no-active/stale-ref contexts into stable nextAction lists.
+ * Scope: Recovery nextAction assembly only; diagnostic detection and action-list merge ordering stay in the extension entrypoint.
+ * Usage: Imported by the extension entrypoint when adding recovery nextActions to tool details.
+ * Invariants/Assumptions: Action ids and argv ordering are public contracts; session prefixing must not double-prefix explicit --session args.
+ */
+
+import { buildAgentBrowserNextActions } from "./action-recommendations.js";
+import { type AgentBrowserNextAction, withOptionalSessionArgs } from "./next-actions.js";
+
+export interface TabRecoveryCorrection {
+	selectedTab?: string;
+	targetTitle?: string;
+	targetUrl?: string;
+}
+
+export interface TabRecoveryTarget {
+	title?: string;
+	url?: string;
+}
+
+export function buildConnectedSessionNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
+	if (!sessionName) return [];
+	return buildAgentBrowserNextActions({
+		recovery: { kind: "connected-session", sessionName },
+		resultCategory: "success",
+		successCategory: "completed",
+	}) ?? [];
+}
+
+export function buildNoActivePageNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
+	if (!sessionName) return [];
+	return buildAgentBrowserNextActions({
+		recovery: { kind: "no-active-page", sessionName },
+		resultCategory: "failure",
+	}) ?? [];
+}
+
+export function buildSessionTabRecoveryNextActions(options: {
+	kind: "about-blank" | "tab-drift";
+	recoveryApplied?: boolean;
+	resultCategory?: "failure" | "success";
+	sessionName?: string;
+	tabCorrection?: TabRecoveryCorrection;
+	target?: TabRecoveryTarget;
+}): AgentBrowserNextAction[] {
+	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,
+		},
+		resultCategory,
+		successCategory: resultCategory === "success" ? "completed" : undefined,
+	}) ?? [];
+}
+
+export function buildSessionAwareStaleRefNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
+	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,
+		};
+	});
+}

package/extensions/agent-browser/lib/results/selector-recovery.ts

@@ -0,0 +1,312 @@
+/**
+ * Purpose: Own pure selector-miss recovery diagnostics for visible refs and rich editable inputs.
+ * Responsibilities: Parse find/semantic action targets, match current snapshot refs, build public diagnostics, text, and safe nextActions.
+ * Scope: Selector recovery policy only; subprocess snapshot probing and result orchestration stay in the extension entrypoint.
+ * Usage: The extension entrypoint supplies command tokens plus snapshot data after a selector-not-found failure.
+ * Invariants/Assumptions: Fill recovery must never echo or auto-submit the user-provided fill text; keyboard insertion remains a separate explicit action.
+ */
+
+import { isRecord } from "../parsing.js";
+import { extractRefSnapshotFromData, type SessionRefSnapshot } from "../session-page-state.js";
+import { getEditableRefEvidence } from "./editable-ref-evidence.js";
+import { type AgentBrowserNextAction, 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";
+
+export type SelectorRecoveryActionName = "check" | "click" | "fill" | "select" | "uncheck";
+
+export interface SelectorRecoveryCompiledAction {
+	action: SelectorRecoveryActionName;
+	args: string[];
+	locator?: string;
+	selector?: string;
+	values?: string[];
+}
+
+export interface VisibleRefFallbackCandidate {
+	action: SelectorRecoveryActionName;
+	args?: string[];
+	editableEvidence?: boolean;
+	name: string;
+	reason: string;
+	ref: string;
+	role: string;
+}
+
+export interface VisibleRefFallbackDiagnostic {
+	candidates: VisibleRefFallbackCandidate[];
+	snapshot: SessionRefSnapshot;
+	summary: string;
+	target: {
+		action: SelectorRecoveryActionName;
+		roles: string[];
+		targetName: string;
+	};
+}
+
+export interface PublicVisibleRefFallbackCandidate {
+	action: SelectorRecoveryActionName;
+	args?: string[];
+	name: string;
+	reason: string;
+	ref: string;
+	role: string;
+}
+
+export interface PublicVisibleRefFallbackDiagnostic {
+	candidates: PublicVisibleRefFallbackCandidate[];
+	snapshot: SessionRefSnapshot;
+	summary: string;
+	target: VisibleRefFallbackDiagnostic["target"];
+}
+
+export interface VisibleRefFallbackTarget {
+	action: SelectorRecoveryActionName;
+	roles: string[];
+	text?: string;
+	targetName: string;
+}
+
+export interface RichInputRecoveryCandidate {
+	clickArgs: string[];
+	focusArgs: string[];
+	name: string;
+	reason: string;
+	ref: string;
+	role: string;
+}
+
+export interface RichInputRecoveryDiagnostic {
+	candidates: RichInputRecoveryCandidate[];
+	inputMethodHint: string;
+	nextActionIds: string[];
+	summary: string;
+	target: {
+		roles: string[];
+		targetName: string;
+	};
+}
+
+const SELECTOR_RECOVERY_ACTION_NAMES = new Set<SelectorRecoveryActionName>(["check", "click", "fill", "select", "uncheck"]);
+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 inserttext or keyboard type with the intended text in a separate call, and do not press Enter or otherwise submit unless the user flow explicitly calls for it.";
+
+function isSelectorRecoveryActionName(action: string): action is SelectorRecoveryActionName {
+	return SELECTOR_RECOVERY_ACTION_NAMES.has(action as SelectorRecoveryActionName);
+}
+
+function getFindNameFlagValue(args: string[], startIndex: number): string | undefined {
+	const nameFlagIndex = args.indexOf("--name", startIndex);
+	const name = nameFlagIndex >= 0 ? args[nameFlagIndex + 1] : undefined;
+	return name && !name.startsWith("-") ? name : undefined;
+}
+
+function getFindVisibleRefFallbackTarget(args: string[], options: { allowLeadingDashFillText?: boolean } = {}): VisibleRefFallbackTarget | undefined {
+	const findIndex = args[0] === "--session" ? 2 : 0;
+	if (args[findIndex] !== "find") return undefined;
+	const locator = args[findIndex + 1];
+	const value = args[findIndex + 2];
+	const action = args[findIndex + 3];
+	if (!locator || !value || !isSelectorRecoveryActionName(action) || action === "select") 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 };
+	}
+	return undefined;
+}
+
+export function getVisibleRefFallbackTarget(options: {
+	commandTokens: string[];
+	compiledSemanticAction?: SelectorRecoveryCompiledAction;
+}): VisibleRefFallbackTarget | undefined {
+	return getFindVisibleRefFallbackTarget(options.commandTokens, { allowLeadingDashFillText: true }) ?? (options.compiledSemanticAction ? getFindVisibleRefFallbackTarget(options.compiledSemanticAction.args, { allowLeadingDashFillText: true }) : undefined);
+}
+
+function getVisibleRefFallbackCandidates(target: VisibleRefFallbackTarget, snapshotData: unknown): VisibleRefFallbackCandidate[] {
+	const 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]): VisibleRefFallbackCandidate[] => {
+		if (!/^e\d+$/.test(ref) || !isRecord(entry)) return [];
+		const snapshotLine = snapshotLineByRef.get(ref);
+		const editableEvidence = getEditableRefEvidence({ ref: entry, text: 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) return [];
+		if (target.action === "fill" && editableEvidence === false && EDITABLE_CONTROL_ROLES.has(role.toLowerCase())) return [];
+		const directRefArgs = target.action === "fill" ? undefined : [target.action, `@${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) => 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: {
+	snapshotData: unknown;
+	target: VisibleRefFallbackTarget;
+}): VisibleRefFallbackDiagnostic | undefined {
+	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 },
+	};
+}
+
+export interface VisibleRefActionResolution {
+	args: string[];
+	snapshot: SessionRefSnapshot;
+}
+
+export function resolveVisibleRefActionFromSnapshot(options: {
+	compiledAction: SelectorRecoveryCompiledAction;
+	snapshotData: unknown;
+}): VisibleRefActionResolution | undefined {
+	const target = getFindVisibleRefFallbackTarget(options.compiledAction.args, { allowLeadingDashFillText: true });
+	if (!target || target.action === "fill" || target.action === "select") return undefined;
+	const snapshot = extractRefSnapshotFromData(options.snapshotData);
+	if (!snapshot) return undefined;
+	const candidate = getVisibleRefFallbackCandidates(target, options.snapshotData).find((item) => item.args !== undefined);
+	if (!candidate?.args) return undefined;
+	return { args: candidate.args, snapshot };
+}
+
+export function buildVisibleRefFallbackNextActions(options: { diagnostic: VisibleRefFallbackDiagnostic; sessionName?: string }): AgentBrowserNextAction[] {
+	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" as const,
+	}] : []);
+}
+
+export function formatVisibleRefFallbackText(diagnostic: VisibleRefFallbackDiagnostic | undefined): string | undefined {
+	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}`),
+	].join("\n");
+}
+
+export function sanitizeVisibleRefFallbackDiagnostic(diagnostic: VisibleRefFallbackDiagnostic): PublicVisibleRefFallbackDiagnostic {
+	return {
+		candidates: diagnostic.candidates.map(({ editableEvidence: _editableEvidence, ...candidate }) => candidate),
+		snapshot: diagnostic.snapshot,
+		summary: diagnostic.summary,
+		target: diagnostic.target,
+	};
+}
+
+function isRichInputRecoveryCandidate(candidate: VisibleRefFallbackCandidate): boolean {
+	return candidate.action === "fill" && candidate.editableEvidence !== false && RICH_INPUT_RECOVERY_EDITABLE_ROLES.has(candidate.role.toLowerCase());
+}
+
+export function buildRichInputRecoveryDiagnostic(diagnostic: VisibleRefFallbackDiagnostic | undefined): RichInputRecoveryDiagnostic | undefined {
+	if (!diagnostic || diagnostic.target.action !== "fill") return undefined;
+	const candidates = diagnostic.candidates.filter(isRichInputRecoveryCandidate).map((candidate): RichInputRecoveryCandidate => ({
+		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: { diagnostic: RichInputRecoveryDiagnostic; sessionName?: string }): AgentBrowserNextAction[] {
+	const candidateCount = options.diagnostic.candidates.length;
+	const ambiguous = candidateCount > 1;
+	return options.diagnostic.candidates.flatMap((candidate, index): AgentBrowserNextAction[] => {
+		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 inserttext or keyboard type with the intended text only if this is the right input.";
+		return [
+			{
+				id: focusId,
+				params: { args: withOptionalSessionArgs(options.sessionName, candidate.focusArgs) },
+				reason: candidate.reason,
+				safety,
+				tool: "agent_browser" as const,
+			},
+			{
+				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" as const,
+			},
+		];
+	});
+}
+
+export function formatRichInputRecoveryText(diagnostic: RichInputRecoveryDiagnostic | undefined): string | undefined {
+	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 inserttext/type with the intended text.`;
+		}),
+		`- ${diagnostic.inputMethodHint}`,
+	].join("\n");
+}
+
+export function normalizeSemanticActionAccessibleName(name: string): string {
+	return name.replace(/\s+/g, " ").trim().toLowerCase();
+}