pi-agent-browser-native 0.2.48 → 0.2.49

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

@@ -1,320 +0,0 @@
-/**
- * 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: Public fill recovery must never echo or auto-submit the user-provided fill text; guarded semanticAction fill pre-resolution may execute only one exact current editable ref.
- */
-
-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: {
-	allowFill?: boolean;
-	compiledAction: SelectorRecoveryCompiledAction;
-	snapshotData: unknown;
-}): VisibleRefActionResolution | undefined {
-	const target = getFindVisibleRefFallbackTarget(options.compiledAction.args, { allowLeadingDashFillText: true });
-	if (!target || target.action === "select") return undefined;
-	const snapshot = extractRefSnapshotFromData(options.snapshotData);
-	if (!snapshot) return undefined;
-	const candidates = getVisibleRefFallbackCandidates(target, options.snapshotData);
-	if (target.action === "fill") {
-		if (!options.allowFill || candidates.length !== 1 || target.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, target.text], snapshot };
-	}
-	const candidate = candidates.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();
-}

package/extensions/agent-browser/lib/results/snapshot-high-value-controls.ts

@@ -1,273 +0,0 @@
-/**
- * Purpose: Select the omitted snapshot refs most likely to be actionable controls.
- * Responsibilities: Classify editable, surface, primary-action, and role-based control refs with deterministic diversity and top-up rules.
- * Scope: High-value control ranking only; snapshot parsing, noise filtering, and presentation text live in neighboring modules.
- * Usage: Snapshot presentation passes already-visible, non-noise omitted refs and receives the bounded high-value subset to surface.
- * Invariants/Assumptions: Ranking must preserve scarce control categories before filling dominant buckets so dense desktop hosts stay navigable.
- */
-
-import type { SnapshotRefEntry } from "./snapshot-refs.js";
-import { compareRefIds } from "./text.js";
-
-const SNAPSHOT_HIGH_VALUE_EDITABLE_REF_FILL_TARGET_LINES = 4;
-const SNAPSHOT_HIGH_VALUE_SURFACE_REF_FILL_TARGET_LINES = 3;
-const SNAPSHOT_HIGH_VALUE_PRIMARY_ACTION_REF_FILL_TARGET_LINES = 3;
-
-const SNAPSHOT_HIGH_VALUE_CONTROL_ROLES = new Set([
-	"button",
-	"checkbox",
-	"combobox",
-	"link",
-	"menuitem",
-	"option",
-	"radio",
-	"searchbox",
-	"tab",
-	"textbox",
-]);
-
-const SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY: Record<string, number> = {
-	searchbox: 0,
-	textbox: 1,
-	combobox: 2,
-	button: 3,
-	link: 4,
-	tab: 5,
-	checkbox: 6,
-	radio: 7,
-	option: 8,
-	menuitem: 9,
-};
-
-const SNAPSHOT_SURFACE_CONTROL_NAME_PATTERNS = [
-	/\b(?:agents?|browser|canvas|chat|editor|panel|pane|preview|surface|tab|terminal|thread|view|window|workspace)\b/i,
-];
-
-const SNAPSHOT_PRIMARY_ACTION_BUTTON_NAME_PATTERNS = [
-	/^(?:add|apply|ask|attach|choose|confirm|connect|continue|create|deploy|done|download|go|insert|launch|log in|new|next|ok|open|publish|refresh|retry|run|save|search|select|send|sign in|sign up|start|submit|upload)$/i,
-	/^(?:add|apply|ask|confirm|connect|continue|create|launch|new|open|refresh|retry|run|save|search|send|start|submit)\b/i,
-];
-
-const SNAPSHOT_HIGH_VALUE_LINK_NAME_PATTERNS = [
-	/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/i,
-];
-
-function getHighValueControlRole(entry: SnapshotRefEntry): string {
-	return entry.isEditable === true && (entry.role === "unknown" || entry.role === "generic") ? "textbox" : entry.role;
-}
-
-function isEditableControlRef(entry: SnapshotRefEntry): boolean {
-	if (entry.isEditable === false) return false;
-	const role = getHighValueControlRole(entry);
-	return entry.isEditable === true || role === "searchbox" || role === "textbox" || role === "combobox";
-}
-
-function isNamedSurfaceControlRef(entry: SnapshotRefEntry): boolean {
-	if (entry.name.length === 0) return false;
-	const role = getHighValueControlRole(entry);
-	if (role === "tab") return true;
-	if (role !== "button" && role !== "menuitem" && role !== "option") return false;
-	return SNAPSHOT_SURFACE_CONTROL_NAME_PATTERNS.some((pattern) => pattern.test(entry.name));
-}
-
-function isPrimaryActionButtonRef(entry: SnapshotRefEntry): boolean {
-	return (
-		getHighValueControlRole(entry) === "button" &&
-		entry.name.length > 0 &&
-		SNAPSHOT_PRIMARY_ACTION_BUTTON_NAME_PATTERNS.some((pattern) => pattern.test(entry.name))
-	);
-}
-
-type HighValueControlCategory = "editable" | "named-surface" | "primary-action" | "role";
-
-interface HighValueControlCategoryRule {
-	bucketKey(entry: SnapshotRefEntry, role: string): string;
-	fillTarget?: number;
-	id: HighValueControlCategory;
-	matches(entry: SnapshotRefEntry, role: string): boolean;
-	priority: number;
-}
-
-interface HighValueControlScore {
-	category: HighValueControlCategory;
-	categoryPriority: number;
-	diversityBucketKey: string;
-	lineIndex: number;
-	namePriority: 0 | 1;
-	refId: string;
-	role: string;
-	rolePriority: number;
-	roundRobinBucketKey: string;
-}
-
-interface HighValueControlCandidate {
-	entry: SnapshotRefEntry;
-	score: HighValueControlScore;
-}
-
-const SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES: readonly HighValueControlCategoryRule[] = [
-	{
-		bucketKey: () => "editable",
-		fillTarget: SNAPSHOT_HIGH_VALUE_EDITABLE_REF_FILL_TARGET_LINES,
-		id: "editable",
-		matches: (entry) => isEditableControlRef(entry),
-		priority: 0,
-	},
-	{
-		bucketKey: () => "named-surface",
-		fillTarget: SNAPSHOT_HIGH_VALUE_SURFACE_REF_FILL_TARGET_LINES,
-		id: "named-surface",
-		matches: (entry) => isNamedSurfaceControlRef(entry),
-		priority: 1,
-	},
-	{
-		bucketKey: () => "primary-action",
-		fillTarget: SNAPSHOT_HIGH_VALUE_PRIMARY_ACTION_REF_FILL_TARGET_LINES,
-		id: "primary-action",
-		matches: (entry) => isPrimaryActionButtonRef(entry),
-		priority: 2,
-	},
-	{
-		bucketKey: (_entry, role) => role,
-		id: "role",
-		matches: () => true,
-		priority: 3,
-	},
-] as const;
-
-function isHighValueLinkRef(entry: SnapshotRefEntry): boolean {
-	return entry.name.length > 0 && SNAPSHOT_HIGH_VALUE_LINK_NAME_PATTERNS.some((pattern) => pattern.test(entry.name));
-}
-
-export function isHighValueControlEntry(entry: SnapshotRefEntry): boolean {
-	const role = getHighValueControlRole(entry);
-	if (!SNAPSHOT_HIGH_VALUE_CONTROL_ROLES.has(role)) return false;
-	if (role === "link") return isHighValueLinkRef(entry);
-	if (entry.isEditable === false && (role === "searchbox" || role === "textbox" || role === "combobox")) return false;
-	return entry.name.length > 0 || isEditableControlRef(entry);
-}
-
-function getHighValueControlCategoryRule(entry: SnapshotRefEntry, role: string): HighValueControlCategoryRule | undefined {
-	return SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES.find((rule) => rule.matches(entry, role));
-}
-
-function classifyHighValueControlRef(entry: SnapshotRefEntry): HighValueControlCandidate | undefined {
-	if (!isHighValueControlEntry(entry)) return undefined;
-	const role = getHighValueControlRole(entry);
-	const rule = getHighValueControlCategoryRule(entry, role);
-	if (!rule) return undefined;
-
-	return {
-		entry,
-		score: {
-			category: rule.id,
-			categoryPriority: rule.priority,
-			diversityBucketKey: `${rule.priority}:${rule.bucketKey(entry, role)}`,
-			lineIndex: entry.lineIndex ?? Number.MAX_SAFE_INTEGER,
-			namePriority: entry.name.length > 0 ? 0 : 1,
-			refId: entry.id,
-			role,
-			rolePriority: SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY[role] ?? 50,
-			roundRobinBucketKey: `${rule.priority}:${role}`,
-		},
-	};
-}
-
-function compareHighValueControlCandidates(left: HighValueControlCandidate, right: HighValueControlCandidate): number {
-	return (
-		left.score.categoryPriority - right.score.categoryPriority ||
-		left.score.rolePriority - right.score.rolePriority ||
-		left.score.namePriority - right.score.namePriority ||
-		left.score.lineIndex - right.score.lineIndex ||
-		compareRefIds(left.score.refId, right.score.refId)
-	);
-}
-
-function takeHighValueCandidate(
-	candidate: HighValueControlCandidate,
-	selected: HighValueControlCandidate[],
-	selectedIds: Set<string>,
-): void {
-	selected.push(candidate);
-	selectedIds.add(candidate.entry.id);
-}
-
-function takeFirstPerDiversityBucket(
-	candidates: HighValueControlCandidate[],
-	selected: HighValueControlCandidate[],
-	selectedIds: Set<string>,
-	limit: number,
-): void {
-	const seenBuckets = new Set<string>();
-	for (const candidate of candidates) {
-		if (selected.length >= limit) break;
-		if (seenBuckets.has(candidate.score.diversityBucketKey)) continue;
-		seenBuckets.add(candidate.score.diversityBucketKey);
-		takeHighValueCandidate(candidate, selected, selectedIds);
-	}
-}
-
-function topUpHighValueCategory(
-	candidates: HighValueControlCandidate[],
-	selected: HighValueControlCandidate[],
-	selectedIds: Set<string>,
-	category: HighValueControlCategory,
-	target: number,
-	limit: number,
-): void {
-	let count = selected.filter((candidate) => candidate.score.category === category).length;
-	for (const candidate of candidates) {
-		if (selected.length >= limit || count >= target) break;
-		if (selectedIds.has(candidate.entry.id) || candidate.score.category !== category) continue;
-		takeHighValueCandidate(candidate, selected, selectedIds);
-		count += 1;
-	}
-}
-
-function buildRemainingHighValueBuckets(
-	candidates: HighValueControlCandidate[],
-	selectedIds: Set<string>,
-): HighValueControlCandidate[][] {
-	const buckets = new Map<string, HighValueControlCandidate[]>();
-	for (const candidate of candidates) {
-		if (selectedIds.has(candidate.entry.id)) continue;
-		const bucket = buckets.get(candidate.score.roundRobinBucketKey);
-		if (bucket) bucket.push(candidate);
-		else buckets.set(candidate.score.roundRobinBucketKey, [candidate]);
-	}
-	return [...buckets.values()].sort((left, right) => compareHighValueControlCandidates(left[0], right[0]));
-}
-
-function roundRobinHighValueBuckets(
-	buckets: HighValueControlCandidate[][],
-	selected: HighValueControlCandidate[],
-	selectedIds: Set<string>,
-	limit: number,
-): void {
-	let bucketIndex = 0;
-	while (selected.length < limit && buckets.some((bucket) => bucket.length > 0)) {
-		const bucket = buckets[bucketIndex % buckets.length];
-		const candidate = bucket.shift();
-		if (candidate) takeHighValueCandidate(candidate, selected, selectedIds);
-		bucketIndex += 1;
-	}
-}
-
-export function selectHighValueControlEntries(entries: SnapshotRefEntry[], limit: number): SnapshotRefEntry[] {
-	const candidates = entries
-		.map(classifyHighValueControlRef)
-		.filter((candidate): candidate is HighValueControlCandidate => Boolean(candidate))
-		.sort(compareHighValueControlCandidates);
-	const selected: HighValueControlCandidate[] = [];
-	const selectedIds = new Set<string>();
-
-	takeFirstPerDiversityBucket(candidates, selected, selectedIds, limit);
-
-	for (const rule of SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES) {
-		if (rule.fillTarget === undefined) continue;
-		topUpHighValueCategory(candidates, selected, selectedIds, rule.id, rule.fillTarget, limit);
-	}
-
-	roundRobinHighValueBuckets(buildRemainingHighValueBuckets(candidates, selectedIds), selected, selectedIds, limit);
-	return selected.map((candidate) => candidate.entry);
-}

package/extensions/agent-browser/lib/results/snapshot-refs.ts

@@ -1,100 +0,0 @@
-/**
- * Purpose: Own canonical parsing and enrichment of refs from agent-browser snapshot payloads.
- * Responsibilities: Read structured refs, correlate them with raw snapshot lines, and infer editable/ref role evidence once for consumers.
- * Scope: Snapshot ref metadata only; section preview, high-value ranking, and presentation assembly live in neighboring modules.
- * Usage: Imported by snapshot presentation and recovery diagnostics that need consistent ref/name/role/editable evidence.
- * Invariants/Assumptions: Snapshot text parsing is best-effort and must tolerate upstream formatting changes by preserving structured ref data when line parsing fails.
- */
-
-import { isRecord } from "../parsing.js";
-import { getEditableRefEvidence } from "./editable-ref-evidence.js";
-import { compareRefIds, normalizeWhitespace } from "./text.js";
-
-export interface SnapshotRefEntry {
-	id: string;
-	isEditable?: boolean;
-	lineIndex?: number;
-	name: string;
-	refData?: Record<string, unknown>;
-	role: string;
-}
-
-export interface SnapshotLineRefInfo {
-	index: number;
-	name: string;
-	raw: string;
-	ref?: string;
-	role: string;
-}
-
-export function getSnapshotRefRecord(data: unknown): Record<string, unknown> | undefined {
-	return isRecord(data) && isRecord(data.refs) ? data.refs : undefined;
-}
-
-export function getSnapshotLineTextByRef(data: unknown): Map<string, string> {
-	const snapshot = isRecord(data) && typeof data.snapshot === "string" ? data.snapshot : "";
-	const lineByRef = new Map<string, string>();
-	for (const line of snapshot.split("\n")) {
-		const ref = line.match(/\bref=([^,\]\s]+)/)?.[1];
-		if (!ref || lineByRef.has(ref)) continue;
-		lineByRef.set(ref, line);
-	}
-	return lineByRef;
-}
-
-export function getSnapshotRefEntries(data: Record<string, unknown>): SnapshotRefEntry[] {
-	const refs = getSnapshotRefRecord(data);
-	if (!refs) return [];
-
-	return Object.entries(refs)
-		.map(([id, value]) => {
-			if (!isRecord(value)) {
-				return { id, name: "", role: "unknown" } satisfies SnapshotRefEntry;
-			}
-			const name = typeof value.name === "string" ? normalizeWhitespace(value.name) : "";
-			const role = typeof value.role === "string" && value.role.length > 0 ? value.role : "unknown";
-			const isEditable = getEditableRefEvidence({ ref: value });
-			return { id, isEditable, name, refData: value, role } satisfies SnapshotRefEntry;
-		})
-		.sort((a, b) => compareRefIds(a.id, b.id));
-}
-
-function isEditableSnapshotLine(line: SnapshotLineRefInfo): boolean | undefined {
-	const editableEvidence = getEditableRefEvidence({ text: line.raw });
-	if (editableEvidence !== undefined) return editableEvidence;
-	return line.role === "searchbox" || line.role === "textbox" || line.role === "combobox" ? true : undefined;
-}
-
-export function getSnapshotRefRole(entry: { role?: unknown }, editableEvidence: boolean | undefined): string {
-	const rawRole = typeof entry.role === "string" && entry.role.length > 0 ? entry.role : "unknown";
-	const normalizedRole = rawRole.toLowerCase();
-	if ((normalizedRole === "generic" || normalizedRole === "unknown") && editableEvidence === true) {
-		return "textbox";
-	}
-	return rawRole;
-}
-
-export function enrichSnapshotRefEntries(refEntries: SnapshotRefEntry[], snapshotLines: SnapshotLineRefInfo[]): SnapshotRefEntry[] {
-	const lineByRef = new Map<string, SnapshotLineRefInfo>();
-	for (const line of snapshotLines) {
-		if (!line.ref || lineByRef.has(line.ref)) continue;
-		lineByRef.set(line.ref, line);
-	}
-
-	return refEntries.map((entry) => {
-		const line = lineByRef.get(entry.id);
-		const lineRole = line && line.role !== "unknown" ? line.role : undefined;
-		const editableEvidence = getEditableRefEvidence({ ref: entry.refData, text: line?.raw });
-		const hasEditableRole = line ? isEditableSnapshotLine(line) === true && !["unknown", "generic"].includes(line.role) : false;
-		const isEditable = editableEvidence === true || (editableEvidence !== false && hasEditableRole);
-		const roleFromRefOrLine = entry.role !== "unknown" && entry.role !== "generic" ? entry.role : lineRole ?? entry.role;
-		const role = getSnapshotRefRole({ role: roleFromRefOrLine }, isEditable);
-		return {
-			...entry,
-			isEditable,
-			lineIndex: line?.index,
-			name: entry.name.length > 0 ? entry.name : (line?.name ?? ""),
-			role,
-		} satisfies SnapshotRefEntry;
-	});
-}