pi-agent-browser-native 0.2.32 → 0.2.33

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

@@ -7,158 +7,45 @@
  */
 
 import { isRecord } from "../parsing.js";
+import type { PersistentSessionArtifactStore } from "../temp.js";
+import type {
+	SessionArtifactManifest,
+	ToolPresentation,
+} from "./contracts.js";
+import { isHighValueControlEntry, selectHighValueControlEntries } from "./snapshot-high-value-controls.js";
 import {
-	type PersistentSessionArtifactEviction,
-	type PersistentSessionArtifactStore,
-	writePersistentSessionArtifactFile,
-	writeSecureTempFile,
-} from "../temp.js";
+	buildFallbackSnapshotOutline,
+	buildRefLineOrderMap,
+	buildSegmentPreview,
+	buildSnapshotSegments,
+	canUseStructuredSnapshotPreview,
+	chooseAdditionalSegments,
+	choosePrimarySegment,
+	getMeaningfulSegmentLines,
+	getSnapshotRolePriority,
+	isChromeSectionName,
+	isNoiseName,
+	parseSnapshotLines,
+} from "./snapshot-segments.js";
+import { applySnapshotArtifactManifest, writeSnapshotSpillFile, type SnapshotSpillWriteResult } from "./snapshot-spill.js";
 import {
-	type SessionArtifactManifest,
-	type SessionArtifactManifestEntry,
-	type ToolPresentation,
-	buildEvictedSessionArtifactEntries,
-	compareRefIds,
-	countLines,
-	formatSessionArtifactRetentionSummary,
-	mergeSessionArtifactManifest,
-	normalizeWhitespace,
-	truncateText,
-} from "./shared.js";
+	enrichSnapshotRefEntries,
+	getSnapshotRefEntries,
+	type SnapshotLineRefInfo,
+	type SnapshotRefEntry,
+} from "./snapshot-refs.js";
+import { compareRefIds, countLines, truncateText } from "./text.js";
 
 const SNAPSHOT_INLINE_MAX_CHARS = 6_000;
 const SNAPSHOT_INLINE_MAX_LINES = 80;
 const SNAPSHOT_INLINE_MAX_REFS = 60;
 const SNAPSHOT_PRIMARY_PREVIEW_LINES = 8;
 const SNAPSHOT_SECTION_PREVIEW_LINES = 2;
-const SNAPSHOT_MAX_ADDITIONAL_SECTIONS = 2;
 const SNAPSHOT_KEY_REF_MAX_LINES = 8;
 const SNAPSHOT_OTHER_REF_MAX_LINES = 4;
 const SNAPSHOT_HIGH_VALUE_REF_MAX_LINES = 10;
 const SNAPSHOT_ROLE_COUNT_MAX_ENTRIES = 4;
-const SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES = 12;
 const SNAPSHOT_NAME_MAX_CHARS = 96;
-const SNAPSHOT_LINE_MAX_CHARS = 140;
-const SNAPSHOT_SPILL_FILE_PREFIX = "pi-agent-browser-snapshot";
-const SNAPSHOT_SIGNAL_ROLES = new Set([
-	"article",
-	"banner",
-	"button",
-	"checkbox",
-	"combobox",
-	"dialog",
-	"gridcell",
-	"heading",
-	"link",
-	"listitem",
-	"main",
-	"menu",
-	"menuitem",
-	"navigation",
-	"option",
-	"radio",
-	"region",
-	"row",
-	"searchbox",
-	"tab",
-	"textbox",
-]);
-const SNAPSHOT_SEGMENT_ROOT_ROLES = new Set(["article", "dialog", "heading", "main", "menu", "region"]);
-const SNAPSHOT_ROLE_PRIORITY: Record<string, number> = {
-	article: 0,
-	main: 1,
-	dialog: 2,
-	menu: 3,
-	region: 4,
-	heading: 5,
-	searchbox: 6,
-	textbox: 7,
-	combobox: 8,
-	button: 9,
-	checkbox: 10,
-	radio: 11,
-	tab: 12,
-	option: 13,
-	link: 14,
-	listitem: 14,
-	row: 15,
-	gridcell: 16,
-	navigation: 17,
-	generic: 99,
-	unknown: 100,
-};
-const SNAPSHOT_NOISE_NAME_PATTERNS = [
-	/^skip to /i,
-	/^ad$/i,
-	/^don't want to see ads\??$/i,
-	/keyboard shortcuts/i,
-	/\bpromoted\b/i,
-	/\bsponsored\b/i,
-];
-const SNAPSHOT_CHROME_SECTION_PATTERNS = [
-	/^primary$/i,
-	/^footer$/i,
-	/^navigation$/i,
-	/\bwhat['’]?s happening\b/i,
-	/\brelevant people\b/i,
-	/\btrending\b/i,
-	/\brelated\b/i,
-	/\brecommended\b/i,
-	/\bsuggested\b/i,
-];
-const SNAPSHOT_HIGH_VALUE_CONTROL_ROLES = new Set([
-	"button",
-	"checkbox",
-	"combobox",
-	"menuitem",
-	"option",
-	"radio",
-	"searchbox",
-	"tab",
-	"textbox",
-]);
-const SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY: Record<string, number> = {
-	searchbox: 0,
-	textbox: 1,
-	combobox: 2,
-	button: 3,
-	tab: 4,
-	checkbox: 5,
-	radio: 6,
-	option: 7,
-	menuitem: 8,
-};
-
-interface SnapshotRefEntry {
-	id: string;
-	name: string;
-	role: string;
-}
-
-interface SnapshotLine {
-	depth: number;
-	headingLevel?: number;
-	index: number;
-	name: string;
-	raw: string;
-	ref?: string;
-	role: string;
-}
-
-interface SnapshotSegment {
-	endIndexExclusive: number;
-	lines: SnapshotLine[];
-	root: SnapshotLine;
-	score: number;
-	startIndex: number;
-}
-
-interface SnapshotPreview {
-	omittedCount: number;
-	refIds: string[];
-	lines: string[];
-}
-
 function getSnapshotText(data: Record<string, unknown>): string | undefined {
 	return typeof data.snapshot === "string" ? data.snapshot : undefined;
 }
@@ -167,32 +54,6 @@ function getSnapshotOrigin(data: Record<string, unknown>): string {
 	return typeof data.origin === "string" ? data.origin : "(unknown origin)";
 }
 
-function formatPreviewLine(line: SnapshotLine, baseDepth: number): string {
-	const leadingWhitespace = (line.raw.match(/^\s*/) ?? [""])[0].length;
-	const stripChars = Math.min(leadingWhitespace, Math.max(0, baseDepth) * 2);
-	return truncateText(line.raw.slice(stripChars), SNAPSHOT_LINE_MAX_CHARS);
-}
-
-function getRolePriority(role: string): number {
-	return SNAPSHOT_ROLE_PRIORITY[role] ?? 50;
-}
-
-function getSnapshotRefEntries(data: Record<string, unknown>): SnapshotRefEntry[] {
-	const refs = isRecord(data.refs) ? data.refs : undefined;
-	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";
-			return { id, name, role } satisfies SnapshotRefEntry;
-		})
-		.sort((a, b) => compareRefIds(a.id, b.id));
-}
-
 function getSnapshotRoleCounts(refEntries: SnapshotRefEntry[]): Record<string, number> {
 	const counts: Record<string, number> = {};
 	for (const entry of refEntries) {
@@ -207,7 +68,7 @@ function formatRoleCounts(roleCounts: Record<string, number>): string | undefine
 
 	const ordered = entries.sort((left, right) => {
 		if (right[1] !== left[1]) return right[1] - left[1];
-		return getRolePriority(left[0]) - getRolePriority(right[0]);
+		return getSnapshotRolePriority(left[0]) - getSnapshotRolePriority(right[0]);
 	});
 	const visibleEntries = ordered.slice(0, SNAPSHOT_ROLE_COUNT_MAX_ENTRIES).map(([role, count]) => `${role} ${count}`);
 	const omittedEntries = Math.max(0, ordered.length - visibleEntries.length);
@@ -217,241 +78,6 @@ function formatRoleCounts(roleCounts: Record<string, number>): string | undefine
 	return visibleEntries.join(", ");
 }
 
-function parseSnapshotLines(snapshot: string): SnapshotLine[] {
-	return snapshot
-		.split("\n")
-		.filter((line) => line.length > 0)
-		.map((raw, index) => {
-			const trimmed = raw.trimStart();
-			const depth = Math.floor(((raw.match(/^\s*/) ?? [""])[0].length ?? 0) / 2);
-			const role = trimmed.match(/^[-*]\s+([^\s"]+)/)?.[1] ?? "unknown";
-			const name = normalizeWhitespace(trimmed.match(/"([^"]*)"/)?.[1] ?? "");
-			const ref = trimmed.match(/\bref=([^,\]\s]+)/)?.[1];
-			const headingLevel = trimmed.match(/\blevel=(\d+)/)?.[1];
-			return {
-				depth,
-				headingLevel: headingLevel ? Number(headingLevel) : undefined,
-				index,
-				name,
-				raw,
-				ref,
-				role,
-			} satisfies SnapshotLine;
-		});
-}
-
-function isNoiseName(name: string): boolean {
-	return SNAPSHOT_NOISE_NAME_PATTERNS.some((pattern) => pattern.test(name));
-}
-
-function isChromeSectionName(name: string): boolean {
-	return SNAPSHOT_CHROME_SECTION_PATTERNS.some((pattern) => pattern.test(name));
-}
-
-function isNoiseSnapshotLine(line: SnapshotLine): boolean {
-	if (line.name.length > 0 && isNoiseName(line.name)) return true;
-	const loweredRaw = line.raw.toLowerCase();
-	return loweredRaw.includes("promoted") || loweredRaw.includes("sponsored");
-}
-
-function isPotentialSegmentRootLine(line: SnapshotLine): boolean {
-	if (!SNAPSHOT_SEGMENT_ROOT_ROLES.has(line.role)) return false;
-	if (isNoiseSnapshotLine(line)) return false;
-	if (line.role === "heading") {
-		return line.name.length > 0 && (line.headingLevel ?? 99) <= 3;
-	}
-	if (line.role === "region") {
-		return line.name.length > 0;
-	}
-	return true;
-}
-
-function scoreSegment(segment: SnapshotSegment): number {
-	const { root } = segment;
-	const distinctRefs = new Set(segment.lines.flatMap((line) => (line.ref ? [line.ref] : []))).size;
-	let score = 0;
-
-	score += 120 - getRolePriority(root.role) * 8;
-	score += Math.min(distinctRefs, 16);
-	score += Math.min(segment.lines.length, 12);
-	score -= Math.min(root.index, 60) / 3;
-	score -= root.depth * 6;
-
-	if (root.role === "heading") {
-		if (root.headingLevel === 1) score += 40;
-		else if (root.headingLevel === 2) score += 22;
-		else if (root.headingLevel === 3) score += 12;
-	}
-	if (root.name.length > 0) score += 10;
-	if (root.name.length <= 2) score -= 18;
-	if (isChromeSectionName(root.name)) score -= 45;
-	if (isNoiseName(root.name)) score -= 1000;
-	return score;
-}
-
-function buildSnapshotSegments(snapshotLines: SnapshotLine[]): SnapshotSegment[] {
-	const roots: SnapshotLine[] = [];
-	const stack: SnapshotLine[] = [];
-
-	for (const line of snapshotLines) {
-		stack.length = line.depth;
-		if (isPotentialSegmentRootLine(line)) {
-			const normalizedName = normalizeWhitespace(line.name.toLowerCase());
-			let duplicateAncestor: SnapshotLine | undefined;
-			for (let index = stack.length - 1; index >= 0; index -= 1) {
-				const ancestor = stack[index];
-				if (
-					normalizedName.length > 0 &&
-					normalizeWhitespace(ancestor.name.toLowerCase()) === normalizedName &&
-					SNAPSHOT_SEGMENT_ROOT_ROLES.has(ancestor.role)
-				) {
-					duplicateAncestor = ancestor;
-					break;
-				}
-			}
-			if (!duplicateAncestor) {
-				roots.push(line);
-			}
-		}
-		stack[line.depth] = line;
-	}
-
-	return roots.map((root, index) => {
-		let endIndexExclusive = snapshotLines.length;
-		for (let nextIndex = index + 1; nextIndex < roots.length; nextIndex += 1) {
-			const candidate = roots[nextIndex];
-			if (candidate.depth <= root.depth) {
-				endIndexExclusive = candidate.index;
-				break;
-			}
-		}
-		const lines = snapshotLines.slice(root.index, endIndexExclusive);
-		const segment: SnapshotSegment = {
-			endIndexExclusive,
-			lines,
-			root,
-			score: 0,
-			startIndex: root.index,
-		};
-		segment.score = scoreSegment(segment);
-		return segment;
-	});
-}
-
-function choosePrimarySegment(segments: SnapshotSegment[]): SnapshotSegment | undefined {
-	if (segments.length === 0) return undefined;
-	return (
-		segments.find((segment) => segment.root.role === "main" || segment.root.role === "article") ??
-		segments.find((segment) => segment.root.role === "heading" && segment.root.headingLevel === 1) ??
-		segments.find((segment) => segment.score >= 90) ??
-		[...segments].sort((left, right) => right.score - left.score || left.startIndex - right.startIndex)[0]
-	);
-}
-
-function chooseAdditionalSegments(segments: SnapshotSegment[], primary: SnapshotSegment | undefined): SnapshotSegment[] {
-	if (!primary) return [];
-
-	const seenNames = new Set<string>([normalizeWhitespace(primary.root.name.toLowerCase())]);
-	const rankedCandidates = segments
-		.filter((segment) => segment !== primary && segment.score >= 45)
-		.sort((left, right) => {
-			const leftDistance = Math.abs(left.startIndex - primary.startIndex);
-			const rightDistance = Math.abs(right.startIndex - primary.startIndex);
-			if (leftDistance !== rightDistance) return leftDistance - rightDistance;
-			if (right.score !== left.score) return right.score - left.score;
-			return left.startIndex - right.startIndex;
-		});
-
-	const chosen: SnapshotSegment[] = [];
-	for (const segment of rankedCandidates) {
-		if (chosen.length >= SNAPSHOT_MAX_ADDITIONAL_SECTIONS) break;
-		if (isChromeSectionName(segment.root.name)) continue;
-		if (segment.root.role === "heading" && segment.root.name.length <= 2) continue;
-		const nameKey = normalizeWhitespace(segment.root.name.toLowerCase());
-		if (nameKey && seenNames.has(nameKey)) continue;
-		chosen.push(segment);
-		if (nameKey) seenNames.add(nameKey);
-	}
-
-	return chosen.sort((left, right) => left.startIndex - right.startIndex);
-}
-
-function getMeaningfulSegmentLines(segment: SnapshotSegment): SnapshotLine[] {
-	return segment.lines.filter((line) => {
-		if (isNoiseSnapshotLine(line)) return false;
-		if (line.role === "generic" && !line.ref && line.name.length === 0) return false;
-		if (line.role === "link" && line.name.length === 0) return false;
-		return true;
-	});
-}
-
-function buildSegmentPreview(segment: SnapshotSegment, maxLines: number): SnapshotPreview {
-	const meaningfulLines = getMeaningfulSegmentLines(segment);
-	if (meaningfulLines.length === 0) {
-		return { omittedCount: 0, refIds: [], lines: [] };
-	}
-
-	const previewLines: SnapshotLine[] = [];
-	const previewRefIds = new Set<string>();
-	const seenPreviewKeys = new Set<string>();
-	const rootDepth = segment.root.depth;
-
-	for (const line of meaningfulLines) {
-		if (previewLines.length >= maxLines) break;
-		if (line !== segment.root) {
-			const relativeDepth = line.depth - rootDepth;
-			if (segment.root.role !== "heading" && relativeDepth > 2) continue;
-			if (segment.root.name.length > 0 && line.name === segment.root.name && (line.role === "heading" || line.role === "link")) {
-				continue;
-			}
-		}
-
-		const key = `${line.role}:${line.name}:${line.ref ?? ""}:${line.depth}`;
-		if (seenPreviewKeys.has(key)) continue;
-		seenPreviewKeys.add(key);
-		previewLines.push(line);
-		if (line.ref) previewRefIds.add(line.ref);
-	}
-
-	return {
-		omittedCount: Math.max(0, meaningfulLines.length - previewLines.length),
-		refIds: [...previewRefIds],
-		lines: previewLines.map((line) => formatPreviewLine(line, rootDepth)),
-	};
-}
-
-function buildFallbackSnapshotOutline(snapshotLines: SnapshotLine[]): SnapshotPreview {
-	const selected = new Set<number>();
-	for (let index = 0; index < snapshotLines.length && selected.size < 4; index += 1) {
-		if (!isNoiseSnapshotLine(snapshotLines[index])) selected.add(index);
-	}
-	for (let index = 0; index < snapshotLines.length && selected.size < SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES; index += 1) {
-		const line = snapshotLines[index];
-		if (isNoiseSnapshotLine(line)) continue;
-		if (SNAPSHOT_SIGNAL_ROLES.has(line.role) || line.ref || line.name.length > 0) {
-			selected.add(index);
-		}
-	}
-	const chosenLines = [...selected]
-		.sort((left, right) => left - right)
-		.slice(0, SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES)
-		.map((index) => snapshotLines[index]);
-	return {
-		omittedCount: Math.max(0, snapshotLines.length - chosenLines.length),
-		refIds: chosenLines.flatMap((line) => (line.ref ? [line.ref] : [])),
-		lines: chosenLines.map((line) => truncateText(line.raw, SNAPSHOT_LINE_MAX_CHARS)),
-	};
-}
-
-function buildRefLineOrderMap(snapshotLines: SnapshotLine[]): Map<string, number> {
-	const map = new Map<string, number>();
-	for (const line of snapshotLines) {
-		if (!line.ref || map.has(line.ref)) continue;
-		map.set(line.ref, line.index);
-	}
-	return map;
-}
-
 function rankRefEntries(
 	refEntries: SnapshotRefEntry[],
 	previewRefIds: Set<string>,
@@ -463,7 +89,7 @@ function rankRefEntries(
 		const rightBucket = previewRefIds.has(right.id) ? 0 : focusRefIds.has(right.id) ? 1 : 2;
 		if (leftBucket !== rightBucket) return leftBucket - rightBucket;
 
-		const rolePriority = getRolePriority(left.role) - getRolePriority(right.role);
+		const rolePriority = getSnapshotRolePriority(left.role) - getSnapshotRolePriority(right.role);
 		if (rolePriority !== 0) return rolePriority;
 
 		const leftHasName = left.name.length > 0 ? 0 : 1;
@@ -483,25 +109,6 @@ function formatCompactRef(entry: SnapshotRefEntry): string {
 	return `- ${entry.id} ${entry.role}${suffix}`;
 }
 
-function isHighValueControlRef(entry: SnapshotRefEntry): boolean {
-	if (!SNAPSHOT_HIGH_VALUE_CONTROL_ROLES.has(entry.role)) return false;
-	if (isNoiseName(entry.name) || isChromeSectionName(entry.name)) return false;
-	return entry.name.length > 0 || entry.role === "searchbox" || entry.role === "textbox" || entry.role === "combobox";
-}
-
-function rankHighValueControlRefs(left: SnapshotRefEntry, right: SnapshotRefEntry): number {
-	const rolePriority =
-		(SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY[left.role] ?? 50) -
-		(SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY[right.role] ?? 50);
-	if (rolePriority !== 0) return rolePriority;
-
-	const leftHasName = left.name.length > 0 ? 0 : 1;
-	const rightHasName = right.name.length > 0 ? 0 : 1;
-	if (leftHasName !== rightHasName) return leftHasName - rightHasName;
-
-	return compareRefIds(left.id, right.id);
-}
-
 function shouldCompactSnapshot(rawText: string, data: Record<string, unknown>): boolean {
 	const snapshot = getSnapshotText(data) ?? "";
 	const refEntries = getSnapshotRefEntries(data);
@@ -512,63 +119,6 @@ function shouldCompactSnapshot(rawText: string, data: Record<string, unknown>):
 	);
 }
 
-function canUseStructuredSnapshotPreview(snapshotLines: SnapshotLine[], refEntries: SnapshotRefEntry[]): boolean {
-	if (snapshotLines.length === 0) return false;
-	const linesWithRecognizedRoles = snapshotLines.filter((line) => line.role !== "unknown").length;
-	const linesWithNames = snapshotLines.filter((line) => line.name.length > 0).length;
-	const parsedRefIds = new Set(snapshotLines.flatMap((line) => (line.ref ? [line.ref] : [])));
-	return (
-		linesWithRecognizedRoles >= Math.min(snapshotLines.length, 3) ||
-		linesWithNames >= Math.min(snapshotLines.length, 3) ||
-		parsedRefIds.size >= Math.min(refEntries.length, 3)
-	);
-}
-
-interface SnapshotSpillWriteResult {
-	evictedArtifacts: PersistentSessionArtifactEviction[];
-	path: string;
-	storageScope: "persistent-session" | "process-temp";
-}
-
-async function writeSnapshotSpillFile(
-	data: Record<string, unknown>,
-	persistentArtifactStore: PersistentSessionArtifactStore | undefined,
-): Promise<SnapshotSpillWriteResult> {
-	const options = {
-		content: JSON.stringify(data, null, 2),
-		prefix: SNAPSHOT_SPILL_FILE_PREFIX,
-		suffix: ".json",
-	};
-	if (persistentArtifactStore) {
-		const result = await writePersistentSessionArtifactFile({ ...options, store: persistentArtifactStore });
-		return { ...result, storageScope: "persistent-session" };
-	}
-	return { evictedArtifacts: [], path: await writeSecureTempFile(options), storageScope: "process-temp" };
-}
-
-function applySnapshotArtifactManifest(options: {
-	baseManifest?: SessionArtifactManifest;
-	command?: string;
-	fullOutputPath?: string;
-	spill?: SnapshotSpillWriteResult;
-}): { artifactManifest?: SessionArtifactManifest; artifactRetentionSummary?: string } {
-	if (!options.fullOutputPath || !options.spill) return {};
-	const nowMs = Date.now();
-	const entries: SessionArtifactManifestEntry[] = [
-		{
-			command: options.command,
-			createdAtMs: nowMs,
-			kind: "spill",
-			path: options.fullOutputPath,
-			retentionState: options.spill.storageScope === "persistent-session" ? "live" : "ephemeral",
-			storageScope: options.spill.storageScope,
-		},
-		...buildEvictedSessionArtifactEntries(options.spill.evictedArtifacts, nowMs),
-	];
-	const artifactManifest = mergeSessionArtifactManifest({ base: options.baseManifest, entries, nowMs });
-	return artifactManifest ? { artifactManifest, artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest) } : {};
-}
-
 export function formatSnapshotSummary(data: Record<string, unknown>): string {
 	const origin = typeof data.origin === "string" ? data.origin : "page";
 	const refs = isRecord(data.refs) ? Object.keys(data.refs).length : 0;
@@ -610,11 +160,11 @@ export async function buildSnapshotPresentation(
 		spillErrorText = error instanceof Error ? error.message : String(error);
 	}
 
-	const refEntries = getSnapshotRefEntries(data);
-	const roleCounts = getSnapshotRoleCounts(refEntries);
-	const roleCountsText = formatRoleCounts(roleCounts);
 	const snapshot = getSnapshotText(data) ?? "(no interactive elements)";
 	const snapshotLines = parseSnapshotLines(snapshot);
+	const refEntries = enrichSnapshotRefEntries(getSnapshotRefEntries(data), snapshotLines);
+	const roleCounts = getSnapshotRoleCounts(refEntries);
+	const roleCountsText = formatRoleCounts(roleCounts);
 	const useStructuredPreview = canUseStructuredSnapshotPreview(snapshotLines, refEntries);
 	const snapshotSegments = useStructuredPreview ? buildSnapshotSegments(snapshotLines) : [];
 	const primarySegment = useStructuredPreview ? choosePrimarySegment(snapshotSegments) : undefined;
@@ -656,15 +206,13 @@ export async function buildSnapshotPresentation(
 		.filter((entry) => !keyRefIdSet.has(entry.id))
 		.slice(0, SNAPSHOT_OTHER_REF_MAX_LINES);
 	const displayedRefIdSet = new Set([...keyRefEntries, ...otherRefEntries].map((entry) => entry.id));
-	const omittedHighValueControlEntries = visibleRankedRefEntries
-		.filter((entry) => !displayedRefIdSet.has(entry.id) && isHighValueControlRef(entry))
-		.sort(rankHighValueControlRefs);
-	const visibleHighValueControlEntries = omittedHighValueControlEntries.slice(0, SNAPSHOT_HIGH_VALUE_REF_MAX_LINES);
-	const omittedHighValueControls = Math.max(0, omittedHighValueControlEntries.length - visibleHighValueControlEntries.length);
-	const omittedNonHighlightedRefs = Math.max(
-		0,
-		visibleRankedRefEntries.length - keyRefEntries.length - otherRefEntries.length - omittedHighValueControlEntries.length,
+	const omittedRefEntries = visibleRankedRefEntries.filter((entry) => !displayedRefIdSet.has(entry.id));
+	const highValueControlEntries = omittedRefEntries.filter(
+		(entry) => isHighValueControlEntry(entry) && !isNoiseName(entry.name) && !isChromeSectionName(entry.name),
 	);
+	const visibleHighValueControlEntries = selectHighValueControlEntries(highValueControlEntries, SNAPSHOT_HIGH_VALUE_REF_MAX_LINES);
+	const omittedHighValueControls = Math.max(0, highValueControlEntries.length - visibleHighValueControlEntries.length);
+	const omittedNonHighlightedRefs = Math.max(0, omittedRefEntries.length - highValueControlEntries.length);
 	const origin = getSnapshotOrigin(data);
 
 	const lines: string[] = [

package/extensions/agent-browser/lib/results/text.ts

@@ -0,0 +1,40 @@
+/**
+ * Purpose: Hold tiny text and ref-id helpers shared by result renderers.
+ * Responsibilities: Convert unknown values to text, count lines, normalize whitespace, truncate labels, and sort ref ids naturally.
+ * Scope: Generic pure utilities only; no agent-browser command policy belongs here.
+ * Usage: Imported by envelope, presentation, snapshot, and diagnostic helpers.
+ * Invariants/Assumptions: Helpers are deterministic and side-effect free.
+ */
+
+export function stringifyUnknown(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (value === null || value === undefined) return "";
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+
+export function countLines(text: string): number {
+	return text.length === 0 ? 0 : text.split("\n").length;
+}
+
+export function normalizeWhitespace(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+export function truncateText(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, Math.max(1, maxChars - 1))}…`;
+}
+
+export function compareRefIds(left: string, right: string): number {
+	const leftMatch = left.match(/^(?:[a-zA-Z]+)?(\d+)$/);
+	const rightMatch = right.match(/^(?:[a-zA-Z]+)?(\d+)$/);
+	if (leftMatch && rightMatch) {
+		return Number(leftMatch[1]) - Number(rightMatch[1]);
+	}
+	return left.localeCompare(right);
+}

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

@@ -9,22 +9,33 @@
 export { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "./results/envelope.js";
 export { buildToolPresentation } from "./results/presentation.js";
 export {
-	buildAgentBrowserNextActions,
 	buildAgentBrowserResultCategoryDetails,
 	classifyAgentBrowserFailureCategory,
 	classifyAgentBrowserSuccessCategory,
-	compareRefIds,
-} from "./results/shared.js";
+} from "./results/categories.js";
+export { buildAgentBrowserNextActions } from "./results/action-recommendations.js";
+export { compareRefIds } from "./results/text.js";
+export {
+	AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS,
+	AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS,
+	getAgentBrowserRichInputRecoveryNextActionId,
+	getAgentBrowserRichInputRecoveryNextActionIds,
+} from "./results/recovery-actions.js";
 export type {
 	AgentBrowserBatchResult,
 	AgentBrowserEnvelope,
 	AgentBrowserFailureCategory,
-	AgentBrowserResultCategory,
 	AgentBrowserNextAction,
 	AgentBrowserPageChangeSummary,
+	AgentBrowserResultCategory,
 	AgentBrowserResultCategoryDetails,
 	AgentBrowserSuccessCategory,
 	FileArtifactKind,
 	FileArtifactMetadata,
 	ToolPresentation,
-} from "./results/shared.js";
+} from "./results/contracts.js";
+export type {
+	AgentBrowserRecoveryContext,
+	AgentBrowserRecoveryKind,
+	AgentBrowserRichInputRecoveryNextActionKind,
+} from "./results/recovery-actions.js";