pi-agent-browser-native 0.2.24 → 0.2.26

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

@@ -19,6 +19,55 @@ export interface AgentBrowserBatchResult {
 	success?: boolean;
 }
 
+export type AgentBrowserResultCategory = "failure" | "success";
+
+export type AgentBrowserSuccessCategory = "artifact-saved" | "artifact-unverified" | "completed" | "inspection";
+
+export type AgentBrowserFailureCategory =
+	| "aborted"
+	| "confirmation-required"
+	| "download-not-verified"
+	| "missing-binary"
+	| "parse-failure"
+	| "qa-failure"
+	| "selector-not-found"
+	| "selector-unsupported"
+	| "stale-ref"
+	| "tab-drift"
+	| "timeout"
+	| "upstream-error"
+	| "validation-error";
+
+export interface AgentBrowserResultCategoryDetails {
+	failureCategory?: AgentBrowserFailureCategory;
+	resultCategory: AgentBrowserResultCategory;
+	successCategory?: AgentBrowserSuccessCategory;
+}
+
+export interface AgentBrowserPageChangeSummary {
+	artifactCount?: number;
+	changeType: "artifact" | "confirmation" | "mutation" | "navigation";
+	command?: string;
+	nextActionIds?: string[];
+	savedFilePath?: string;
+	summary: string;
+	title?: string;
+	url?: string;
+}
+
+export interface AgentBrowserNextAction {
+	artifactPath?: string;
+	id: string;
+	params?: {
+		args: string[];
+		sessionMode?: "auto" | "fresh";
+		stdin?: string;
+	};
+	reason: string;
+	safety?: string;
+	tool: "agent_browser";
+}
+
 export type FileArtifactKind = "download" | "file" | "har" | "image" | "pdf" | "profile" | "trace" | "video";
 
 export type FileArtifactStatus = "missing" | "repaired-from-temp" | "saved" | "upstream-temp-only";
@@ -41,6 +90,32 @@ export interface FileArtifactMetadata {
 	tempPath?: string;
 }
 
+export type ArtifactVerificationState = "missing" | "pending" | "unverified" | "verified";
+
+export interface ArtifactVerificationEntry {
+	absolutePath?: string;
+	exists?: boolean;
+	kind: FileArtifactKind | "spill";
+	limitation?: string;
+	mediaType?: string;
+	path: string;
+	requestedPath?: string;
+	retentionState?: ArtifactRetentionState;
+	sizeBytes?: number;
+	state: ArtifactVerificationState;
+	status?: FileArtifactStatus;
+	storageScope?: ArtifactStorageScope;
+}
+
+export interface ArtifactVerificationSummary {
+	artifacts: ArtifactVerificationEntry[];
+	missingCount: number;
+	pendingCount: number;
+	unverifiedCount: number;
+	verified: boolean;
+	verifiedCount: number;
+}
+
 export interface SavedFilePresentationDetails {
 	command: "download" | "pdf" | "wait";
 	kind: "download" | "pdf";
@@ -187,18 +262,24 @@ export function mergeSessionArtifactManifest(options: {
 }
 
 export interface BatchStepPresentationDetails {
+	artifactVerification?: ArtifactVerificationSummary;
 	artifacts?: FileArtifactMetadata[];
 	command?: string[];
 	commandText: string;
 	data?: unknown;
+	failureCategory?: AgentBrowserFailureCategory;
+	nextActions?: AgentBrowserNextAction[];
+	pageChangeSummary?: AgentBrowserPageChangeSummary;
 	fullOutputPath?: string;
 	fullOutputPaths?: string[];
 	imagePath?: string;
 	imagePaths?: string[];
 	index: number;
+	resultCategory: AgentBrowserResultCategory;
 	savedFile?: SavedFilePresentationDetails;
 	savedFilePath?: string;
 	success: boolean;
+	successCategory?: AgentBrowserSuccessCategory;
 	summary: string;
 	text: string;
 }
@@ -213,20 +294,376 @@ export interface BatchFailurePresentationDetails {
 export interface ToolPresentation {
 	artifactManifest?: SessionArtifactManifest;
 	artifactRetentionSummary?: string;
+	artifactVerification?: ArtifactVerificationSummary;
 	artifacts?: FileArtifactMetadata[];
 	batchFailure?: BatchFailurePresentationDetails;
 	batchSteps?: BatchStepPresentationDetails[];
 	content: Array<{ text: string; type: "text" } | { data: string; mimeType: string; type: "image" }>;
 	data?: unknown;
+	failureCategory?: AgentBrowserFailureCategory;
 	fullOutputPath?: string;
 	fullOutputPaths?: string[];
 	imagePath?: string;
 	imagePaths?: string[];
+	nextActions?: AgentBrowserNextAction[];
+	pageChangeSummary?: AgentBrowserPageChangeSummary;
+	resultCategory?: AgentBrowserResultCategory;
 	savedFile?: SavedFilePresentationDetails;
 	savedFilePath?: string;
+	successCategory?: AgentBrowserSuccessCategory;
 	summary: string;
 }
 
+function isPendingFileArtifact(artifact: FileArtifactMetadata): boolean {
+	return artifact.command === "record" && artifact.subcommand === "start" && artifact.kind === "video";
+}
+
+function hasUnverifiedFileArtifact(artifacts: FileArtifactMetadata[] | undefined): boolean {
+	return (artifacts ?? []).some((artifact) => !isPendingFileArtifact(artifact) && artifact.exists !== true);
+}
+
+export function classifyAgentBrowserSuccessCategory(options: {
+	artifacts?: FileArtifactMetadata[];
+	inspection?: boolean;
+	savedFile?: SavedFilePresentationDetails;
+}): AgentBrowserSuccessCategory {
+	if (options.inspection) return "inspection";
+	if ((options.artifacts ?? []).length > 0) return hasUnverifiedFileArtifact(options.artifacts) ? "artifact-unverified" : "artifact-saved";
+	if (options.savedFile) return "artifact-saved";
+	return "completed";
+}
+
+export function classifyAgentBrowserFailureCategory(options: {
+	args?: string[];
+	command?: string;
+	confirmationRequired?: boolean;
+	errorText?: string;
+	parseError?: string;
+	spawnError?: string;
+	stderr?: string;
+	tabDrift?: boolean;
+	timedOut?: boolean;
+	validationError?: string;
+}): AgentBrowserFailureCategory {
+	const text = [options.errorText, options.validationError, options.parseError, options.spawnError, options.stderr].filter(Boolean).join("\n");
+	const command = options.command ?? "";
+	const usedRef = options.args?.some((arg) => /^@e\d+\b/.test(arg)) ?? false;
+	if (options.confirmationRequired || /confirmation required|pending confirmation|requires confirmation/i.test(text)) return "confirmation-required";
+	if (options.timedOut || /timeout|timed out|watchdog|IPC read timeout|must stay under its 30s IPC read timeout/i.test(text)) return "timeout";
+	if (/ENOENT|not found on PATH|could not find.*agent-browser|agent-browser is required but was not found/i.test(text)) return "missing-binary";
+	if (options.parseError || /invalid JSON|missing boolean success|success field must be boolean|returned no JSON output/i.test(text)) return "parse-failure";
+	if (/aborted/i.test(text)) return "aborted";
+	if (options.tabDrift || /could not re-select the intended tab|about:blank|selected tab looks wrong|tab drift|tab.*wrong/i.test(text)) return "tab-drift";
+	if (/\bUnknown ref\b|\bstale ref\b|@ref may be stale|\bref\b.*\b(?:not found|missing|expired)\b/i.test(text)) return "stale-ref";
+	if (usedRef && /could not locate element|element not found|no element/i.test(text)) return "stale-ref";
+	const mentionsPlaywrightSelectorDialect = /(?:\btext=|:has-text\(|\bgetByRole\b|\bgetByText\b)/i.test(text);
+	const reportsSelectorMatchFailure =
+		/\b(?:no elements? found|failed to find|could not find|unable to find)\b.*\b(?:selector|locator)\b/i.test(text) ||
+		/\b(?:selector|locator)\b.*\b(?:no elements? found|not found|missing|failed to find|could not find|unable to find)\b/i.test(text);
+	if (
+		/\b(?:unsupported|unknown|invalid)\s+(?:selector|locator)\b/i.test(text) ||
+		/\bfailed to parse selector\b/i.test(text) ||
+		/\bselector\b.*\b(?:parse|syntax|unsupported|invalid)\b/i.test(text) ||
+		(mentionsPlaywrightSelectorDialect && reportsSelectorMatchFailure)
+	) {
+		return "selector-unsupported";
+	}
+	if (command === "find" && /could not locate element|element not found|no elements? found|unable to find/i.test(text)) return "selector-not-found";
+	if (reportsSelectorMatchFailure) return "selector-not-found";
+	if ((command === "download" || text.includes("wait --download") || /\bdownload\b/i.test(text)) && /missing|not verified|not found|failed|timeout|timed out/i.test(text)) {
+		return "download-not-verified";
+	}
+	if (options.validationError) return "validation-error";
+	return "upstream-error";
+}
+
+function buildNextToolAction(options: {
+	args: string[];
+	id: string;
+	reason: string;
+	safety?: string;
+	sessionMode?: "auto" | "fresh";
+	stdin?: string;
+}): AgentBrowserNextAction {
+	return {
+		id: options.id,
+		params: {
+			args: options.args,
+			...(options.sessionMode ? { sessionMode: options.sessionMode } : {}),
+			...(options.stdin ? { stdin: options.stdin } : {}),
+		},
+		reason: options.reason,
+		...(options.safety ? { safety: options.safety } : {}),
+		tool: "agent_browser",
+	};
+}
+
+function buildArtifactAction(path: string): AgentBrowserNextAction {
+	return {
+		artifactPath: path,
+		id: "use-saved-artifact",
+		reason: "Use the saved artifact path from the structured result instead of scraping it from text.",
+		safety: "Verify artifact metadata such as exists/status before treating the file as durable.",
+		tool: "agent_browser",
+	};
+}
+
+function buildArtifactVerificationAction(artifact: FileArtifactMetadata): AgentBrowserNextAction {
+	return {
+		artifactPath: artifact.path,
+		id: "verify-artifact-path",
+		reason: "The wrapper has artifact metadata but did not verify this file as present on disk.",
+		safety: "Check details.artifactVerification and the filesystem before treating the artifact as durable.",
+		tool: "agent_browser",
+	};
+}
+
+const MUTATING_COMMANDS = new Set([
+	"back",
+	"check",
+	"click",
+	"dblclick",
+	"dialog",
+	"fill",
+	"forward",
+	"hover",
+	"press",
+	"pushstate",
+	"reload",
+	"scroll",
+	"scrollintoview",
+	"select",
+	"swipe",
+	"tap",
+	"type",
+	"uncheck",
+]);
+
+function getDownloadRetryPath(args: string[] | undefined, fallback: string | undefined): string | undefined {
+	if (fallback) return fallback;
+	if (!args || args.length === 0) return undefined;
+	const downloadFlagIndex = args.indexOf("--download");
+	if (downloadFlagIndex >= 0) {
+		const candidate = args[downloadFlagIndex + 1];
+		return candidate && !candidate.startsWith("-") ? candidate : undefined;
+	}
+	const downloadCommandIndex = args.indexOf("download");
+	if (downloadCommandIndex >= 0 && args.length > downloadCommandIndex + 2) {
+		return args[args.length - 1];
+	}
+	return undefined;
+}
+
+export function buildAgentBrowserNextActions(options: {
+	artifacts?: FileArtifactMetadata[];
+	args?: string[];
+	command?: string;
+	confirmationId?: string;
+	failureCategory?: AgentBrowserFailureCategory;
+	resultCategory: AgentBrowserResultCategory;
+	savedFilePath?: string;
+	successCategory?: AgentBrowserSuccessCategory;
+}): AgentBrowserNextAction[] | undefined {
+	const actions: AgentBrowserNextAction[] = [];
+	if (options.resultCategory === "success") {
+		if (options.command === "open") {
+			actions.push(buildNextToolAction({
+				args: ["snapshot", "-i"],
+				id: "inspect-opened-page",
+				reason: "Inspect the opened page before choosing interactive refs.",
+			}));
+		} else if (options.command && MUTATING_COMMANDS.has(options.command)) {
+			actions.push(buildNextToolAction({
+				args: ["snapshot", "-i"],
+				id: "inspect-after-mutation",
+				reason: "Refresh interactive refs after a browser mutation, navigation, scroll, or rerender.",
+				safety: "Do not reuse prior @refs until a fresh snapshot confirms they still exist.",
+			}));
+		}
+		const artifacts = options.artifacts ?? [];
+		const savedFileArtifact = options.savedFilePath ? artifacts.find((artifact) => artifact.path === options.savedFilePath) : undefined;
+		if (options.savedFilePath && savedFileArtifact?.exists !== false) {
+			actions.push(buildArtifactAction(options.savedFilePath));
+		}
+		for (const artifact of artifacts) {
+			if (isPendingFileArtifact(artifact)) {
+				continue;
+			}
+			if (artifact.exists === false) {
+				if (artifact.kind === "download") {
+					actions.push(buildNextToolAction({
+						args: ["wait", "--download", artifact.path],
+						id: "wait-for-download",
+						reason: "Upstream reported a download path, but the wrapper did not verify the file on disk.",
+						safety: "Use a bounded wait timeout that stays below the native wrapper IPC budget.",
+					}));
+				} else {
+					actions.push(buildArtifactVerificationAction(artifact));
+				}
+				continue;
+			}
+			if (artifact.path !== options.savedFilePath) {
+				actions.push(buildArtifactAction(artifact.path));
+			}
+		}
+	} else {
+		switch (options.failureCategory) {
+			case "confirmation-required":
+				if (options.confirmationId) {
+					actions.push(
+						buildNextToolAction({
+							args: ["confirm", options.confirmationId],
+							id: "approve-confirmation",
+							reason: "Approve the pending upstream confirmation when the requested action is safe.",
+							safety: "Only confirm after reviewing the guarded action shown in the result.",
+						}),
+						buildNextToolAction({
+							args: ["deny", options.confirmationId],
+							id: "deny-confirmation",
+							reason: "Deny the pending upstream confirmation when the guarded action is unsafe or unintended.",
+						}),
+					);
+				}
+				break;
+			case "stale-ref":
+			case "selector-not-found":
+			case "selector-unsupported":
+				actions.push(buildNextToolAction({
+					args: ["snapshot", "-i"],
+					id: "refresh-interactive-refs",
+					reason: "Get current interactive refs before retrying the element action.",
+					safety: "Prefer a current @ref or a stable find locator; do not retry stale refs blindly.",
+				}));
+				break;
+			case "download-not-verified":
+				{
+					const retryPath = getDownloadRetryPath(options.args, options.savedFilePath);
+					actions.push(buildNextToolAction({
+						args: retryPath ? ["wait", "--download", retryPath] : ["wait", "--download"],
+						id: "wait-for-download",
+						reason: "Wait for the browser download and let the wrapper verify saved-file metadata.",
+						safety: "Use a bounded wait timeout that stays below the native wrapper IPC budget.",
+					}));
+				}
+				break;
+			case "tab-drift":
+				actions.push(
+					buildNextToolAction({
+						args: ["tab", "list"],
+						id: "list-tabs-for-recovery",
+						reason: "Inspect available tabs before selecting the intended target.",
+					}),
+					buildNextToolAction({
+						args: ["snapshot", "-i"],
+						id: "inspect-current-tab",
+						reason: "Inspect the currently selected tab after tab recovery.",
+					}),
+				);
+				break;
+		}
+	}
+	return actions.length > 0 ? actions : undefined;
+}
+
+export function buildAgentBrowserResultCategoryDetails(options: {
+	artifacts?: FileArtifactMetadata[];
+	args?: string[];
+	command?: string;
+	confirmationRequired?: boolean;
+	errorText?: string;
+	failureCategory?: AgentBrowserFailureCategory;
+	inspection?: boolean;
+	parseError?: string;
+	savedFile?: SavedFilePresentationDetails;
+	spawnError?: string;
+	succeeded: boolean;
+	tabDrift?: boolean;
+	timedOut?: boolean;
+	validationError?: string;
+}): AgentBrowserResultCategoryDetails {
+	if (options.succeeded) {
+		return {
+			resultCategory: "success",
+			successCategory: classifyAgentBrowserSuccessCategory(options),
+		};
+	}
+	return {
+		failureCategory: options.failureCategory ?? classifyAgentBrowserFailureCategory(options),
+		resultCategory: "failure",
+	};
+}
+
+export type NetworkFailureImpact = "actionable" | "benign";
+
+export interface NetworkFailureClassification {
+	impact: NetworkFailureImpact;
+	reason: string;
+	resourceType?: string;
+	status?: number;
+	url?: string;
+}
+
+export interface NetworkFailureSummary {
+	actionableCount: number;
+	benignCount: number;
+	failures: NetworkFailureClassification[];
+	totalCount: number;
+}
+
+function getStringRecordField(value: Record<string, unknown>, key: string): string | undefined {
+	const field = value[key];
+	return typeof field === "string" && field.trim().length > 0 ? field.trim() : undefined;
+}
+
+function getNetworkRequestUrlPath(url: string | undefined): string | undefined {
+	if (!url) return undefined;
+	try {
+		return new URL(url).pathname;
+	} catch {
+		const withoutQuery = url.split(/[?#]/, 1)[0];
+		return withoutQuery.length > 0 ? withoutQuery : undefined;
+	}
+}
+
+function isFailedNetworkRequest(request: Record<string, unknown>): boolean {
+	return (typeof request.status === "number" && request.status >= 400) || request.failed === true || typeof request.error === "string";
+}
+
+function isBenignAssetFailure(request: Record<string, unknown>, url: string | undefined, resourceType: string | undefined): boolean {
+	const path = getNetworkRequestUrlPath(url);
+	if (!path) return false;
+	const normalizedResourceType = resourceType?.toLowerCase();
+	return /(?:^|\/)(?:favicon(?:[-.\w]*)?\.(?:ico|png|svg)|apple-touch-icon(?:[-.\w]*)?\.png)$/i.test(path)
+		&& (request.status === 404 || request.failed === true || typeof request.error === "string")
+		&& (!normalizedResourceType || ["image", "img", "other"].includes(normalizedResourceType) || normalizedResourceType.startsWith("image/"));
+}
+
+export function classifyNetworkRequestFailure(request: Record<string, unknown>): NetworkFailureClassification | undefined {
+	if (!isFailedNetworkRequest(request)) return undefined;
+	const url = getStringRecordField(request, "url");
+	const resourceType = getStringRecordField(request, "resourceType") ?? getStringRecordField(request, "mimeType");
+	const status = typeof request.status === "number" ? request.status : undefined;
+	if (isBenignAssetFailure(request, url, resourceType)) {
+		return { impact: "benign", reason: "low-impact browser icon asset", resourceType, status, url };
+	}
+	return { impact: "actionable", reason: "document, script, API, or non-benign request failure", resourceType, status, url };
+}
+
+export function summarizeNetworkFailures(requests: unknown[]): NetworkFailureSummary {
+	const failures = requests.flatMap((request) => {
+		if (!isRecord(request)) return [];
+		const classification = classifyNetworkRequestFailure(request);
+		return classification ? [classification] : [];
+	});
+	const benignCount = failures.filter((failure) => failure.impact === "benign").length;
+	return {
+		actionableCount: failures.length - benignCount,
+		benignCount,
+		failures,
+		totalCount: failures.length,
+	};
+}
+
 export function stringifyUnknown(value: unknown): string {
 	if (typeof value === "string") return value;
 	if (typeof value === "number" || typeof value === "boolean") return String(value);

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

@@ -34,6 +34,7 @@ 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;
@@ -58,6 +59,7 @@ const SNAPSHOT_SIGNAL_ROLES = new Set([
 	"radio",
 	"region",
 	"row",
+	"searchbox",
 	"tab",
 	"textbox",
 ]);
@@ -69,14 +71,15 @@ const SNAPSHOT_ROLE_PRIORITY: Record<string, number> = {
 	menu: 3,
 	region: 4,
 	heading: 5,
-	button: 6,
+	searchbox: 6,
 	textbox: 7,
 	combobox: 8,
-	checkbox: 9,
-	radio: 10,
-	tab: 11,
-	option: 12,
-	link: 13,
+	button: 9,
+	checkbox: 10,
+	radio: 11,
+	tab: 12,
+	option: 13,
+	link: 14,
 	listitem: 14,
 	row: 15,
 	gridcell: 16,
@@ -103,6 +106,28 @@ const SNAPSHOT_CHROME_SECTION_PATTERNS = [
 	/\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;
@@ -458,6 +483,25 @@ 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);
@@ -611,7 +655,16 @@ export async function buildSnapshotPresentation(
 	const otherRefEntries = visibleRankedRefEntries
 		.filter((entry) => !keyRefIdSet.has(entry.id))
 		.slice(0, SNAPSHOT_OTHER_REF_MAX_LINES);
-	const omittedOtherRefs = Math.max(0, visibleRankedRefEntries.length - keyRefEntries.length - otherRefEntries.length);
+	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 origin = getSnapshotOrigin(data);
 
 	const lines: string[] = [
@@ -658,8 +711,14 @@ export async function buildSnapshotPresentation(
 	if (otherRefEntries.length > 0) {
 		lines.push("", "Other refs:", ...otherRefEntries.map(formatCompactRef));
 	}
-	if (omittedOtherRefs > 0) {
-		lines.push(`- ... (${omittedOtherRefs} additional refs omitted)`);
+	if (omittedNonHighlightedRefs > 0) {
+		lines.push(`- ... (${omittedNonHighlightedRefs} additional refs omitted)`);
+	}
+	if (visibleHighValueControlEntries.length > 0) {
+		lines.push("", "Omitted high-value controls:", ...visibleHighValueControlEntries.map(formatCompactRef));
+		if (omittedHighValueControls > 0) {
+			lines.push(`- ... (${omittedHighValueControls} additional high-value controls omitted)`);
+		}
 	}
 
 	lines.push(
@@ -689,6 +748,7 @@ export async function buildSnapshotPresentation(
 			previewMode: fallbackPreview ? "outline" : "structured",
 			spillError: spillErrorText,
 			previewRefIds: [...previewRefIds],
+			highValueControlRefIds: visibleHighValueControlEntries.map((entry) => entry.id),
 			additionalSectionsOmitted: omittedAdditionalSectionCount,
 			previewSections: [
 				...(primarySegment

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

@@ -8,9 +8,21 @@
 
 export { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "./results/envelope.js";
 export { buildToolPresentation } from "./results/presentation.js";
+export {
+	buildAgentBrowserNextActions,
+	buildAgentBrowserResultCategoryDetails,
+	classifyAgentBrowserFailureCategory,
+	classifyAgentBrowserSuccessCategory,
+} from "./results/shared.js";
 export type {
 	AgentBrowserBatchResult,
 	AgentBrowserEnvelope,
+	AgentBrowserFailureCategory,
+	AgentBrowserResultCategory,
+	AgentBrowserNextAction,
+	AgentBrowserPageChangeSummary,
+	AgentBrowserResultCategoryDetails,
+	AgentBrowserSuccessCategory,
 	FileArtifactKind,
 	FileArtifactMetadata,
 	ToolPresentation,