pi-agent-browser-native 0.2.24 → 0.2.25

package/extensions/agent-browser/index.ts

@@ -6,7 +6,7 @@
  * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
  */
 
-import { copyFile, mkdir, readFile, rm, stat } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -27,6 +27,8 @@ import {
 } from "./lib/playbook.js";
 import { SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS, runAgentBrowserProcess } from "./lib/process.js";
 import {
+	buildAgentBrowserNextActions,
+	buildAgentBrowserResultCategoryDetails,
 	buildToolPresentation,
 	getAgentBrowserErrorText,
 	parseAgentBrowserEnvelope,
@@ -76,16 +78,202 @@ const DEFAULT_SESSION_MODE = "auto" as const;
 const DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV = "PI_AGENT_BROWSER_ALLOW_DIRECT_BASH";
 const PACKAGE_NAME = "pi-agent-browser-native";
 
+const AGENT_BROWSER_SEMANTIC_ACTIONS = ["check", "click", "fill", "select", "uncheck"] as const;
+const AGENT_BROWSER_SEMANTIC_LOCATORS = ["alt", "label", "placeholder", "role", "testid", "text", "title"] as const;
+const AGENT_BROWSER_JOB_STEP_ACTIONS = ["open", "click", "fill", "wait", "assertText", "assertUrl", "waitForDownload", "screenshot"] as const;
+const SOURCE_LOOKUP_WORKSPACE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+const SOURCE_LOOKUP_IGNORED_DIRECTORIES = new Set([".git", "node_modules", "dist", "build", "coverage", ".next", "out", "tmp", "temp"]);
+const SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES = 2_000;
+const SOURCE_LOOKUP_MAX_WORKSPACE_FILES = 5_000;
+
+type AgentBrowserSemanticActionName = (typeof AGENT_BROWSER_SEMANTIC_ACTIONS)[number];
+type AgentBrowserSemanticLocator = (typeof AGENT_BROWSER_SEMANTIC_LOCATORS)[number];
+type AgentBrowserJobStepAction = (typeof AGENT_BROWSER_JOB_STEP_ACTIONS)[number];
+type AgentBrowserSourceLookupStatus = "candidates-found" | "no-candidates" | "unsupported";
+type AgentBrowserNetworkSourceLookupStatus = "failed-requests-found" | "no-failed-requests" | "no-candidates";
+
+interface AgentBrowserSemanticActionInput {
+	action: AgentBrowserSemanticActionName;
+	locator: AgentBrowserSemanticLocator;
+	value: string;
+	text?: string;
+	role?: string;
+	name?: string;
+}
+
+interface CompiledAgentBrowserSemanticAction {
+	action: AgentBrowserSemanticActionName;
+	locator: AgentBrowserSemanticLocator;
+	args: string[];
+}
+
+interface CompiledAgentBrowserJobStep {
+	action: AgentBrowserJobStepAction;
+	args: string[];
+}
+
+interface CompiledAgentBrowserJob {
+	args: string[];
+	stdin: string;
+	steps: CompiledAgentBrowserJobStep[];
+}
+
+interface CompiledAgentBrowserQaPreset extends CompiledAgentBrowserJob {
+	checks: {
+		checkConsole: boolean;
+		checkErrors: boolean;
+		checkNetwork: boolean;
+		expectedText: string[];
+		expectedSelector?: string;
+		screenshotPath?: string;
+		url: string;
+	};
+}
+
+interface CompiledAgentBrowserSourceLookupStep {
+	action: "dom" | "react";
+	args: string[];
+}
+
+interface CompiledAgentBrowserSourceLookup {
+	args: string[];
+	stdin: string;
+	steps: CompiledAgentBrowserSourceLookupStep[];
+	query: {
+		componentName?: string;
+		includeDomHints: boolean;
+		maxWorkspaceFiles: number;
+		reactFiberId?: string;
+		selector?: string;
+	};
+}
+
+interface AgentBrowserSourceLookupCandidate {
+	column?: number;
+	componentName?: string;
+	confidence: "high" | "medium" | "low";
+	evidence: string[];
+	file?: string;
+	line?: number;
+	source: "react-inspect" | "dom-attribute" | "workspace-search";
+}
+
+interface AgentBrowserSourceLookupAnalysis {
+	candidates: AgentBrowserSourceLookupCandidate[];
+	limitations: string[];
+	status: AgentBrowserSourceLookupStatus;
+	summary: string;
+}
+
+interface CompiledAgentBrowserNetworkSourceLookup {
+	args: string[];
+	stdin: string;
+	steps: Array<{ action: "network"; args: string[] }>;
+	query: {
+		filter?: string;
+		maxWorkspaceFiles: number;
+		requestId?: string;
+		url?: string;
+	};
+}
+
+interface AgentBrowserNetworkSourceLookupRequest {
+	error?: string;
+	method?: string;
+	requestId?: string;
+	status?: number;
+	url?: string;
+}
+
+interface AgentBrowserNetworkSourceLookupCandidate {
+	confidence: "high" | "medium" | "low";
+	evidence: string[];
+	file?: string;
+	line?: number;
+	requestUrl?: string;
+	source: "initiator" | "workspace-search";
+}
+
+interface AgentBrowserNetworkSourceLookupAnalysis {
+	candidates: AgentBrowserNetworkSourceLookupCandidate[];
+	failedRequests: AgentBrowserNetworkSourceLookupRequest[];
+	limitations: string[];
+	status: AgentBrowserNetworkSourceLookupStatus;
+	summary: string;
+}
+
 const AGENT_BROWSER_PARAMS = Type.Object({
-	args: Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
-		description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators.",
-		minItems: 1,
-	}),
-	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, and auth save --password-stdin." })),
+
+	args: Type.Optional(
+		Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
+			description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators. Required unless semanticAction, job, qa, sourceLookup, or networkSourceLookup is provided.",
+			minItems: 1,
+		}),
+	),
+	semanticAction: Type.Optional(
+		Type.Object({
+			action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS, {
+				description: "Intent action to compile to an existing agent-browser find command.",
+			}),
+			locator: StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, {
+				description: "Upstream find locator family to use.",
+			}),
+			value: Type.String({ description: "Locator value, such as visible text, label text, placeholder text, test id, title, alt text, or role." }),
+			text: Type.Optional(Type.String({ description: "Text/value argument for fill or select actions." })),
+			role: Type.Optional(Type.String({ description: "Role locator value; when set it must match value for locator=role." })),
+			name: Type.Optional(Type.String({ description: "Accessible name filter for locator=role; compiles to --name <name>." })),
+		}),
+	),
+	qa: Type.Optional(
+		Type.Object({
+			url: Type.String({ description: "URL to open for a lightweight QA preset." }),
+			expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Text that must appear on the page." })),
+			expectedSelector: Type.Optional(Type.String({ description: "Selector or @ref that must appear on the page." })),
+			screenshotPath: Type.Optional(Type.String({ description: "Optional evidence screenshot path captured at the end of the QA preset." })),
+			checkConsole: Type.Optional(Type.Boolean({ description: "Whether to fail on console error messages. Defaults to true." })),
+			checkErrors: Type.Optional(Type.Boolean({ description: "Whether to fail on page errors. Defaults to true." })),
+			checkNetwork: Type.Optional(Type.Boolean({ description: "Whether to fail on failed network requests. Defaults to true." })),
+		}),
+	),
+	sourceLookup: Type.Optional(
+		Type.Object({
+			selector: Type.Optional(Type.String({ description: "Visible selector or @ref whose DOM metadata should be inspected for source hints." })),
+			reactFiberId: Type.Optional(Type.String({ description: "React fiber id to inspect with upstream react inspect. Requires a session opened with --enable react-devtools." })),
+			componentName: Type.Optional(Type.String({ description: "Component name to correlate with react tree output and bounded local workspace search." })),
+			includeDomHints: Type.Optional(Type.Boolean({ description: "Whether selector lookups should inspect DOM HTML attributes for source-like metadata. Defaults to true." })),
+			maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan when componentName is provided. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+		}),
+	),
+	networkSourceLookup: Type.Optional(
+		Type.Object({
+			filter: Type.Optional(Type.String({ description: "Optional upstream network requests filter pattern." })),
+			requestId: Type.Optional(Type.String({ description: "Optional network request id to inspect with network request <id>." })),
+			url: Type.Optional(Type.String({ description: "Optional failed request URL or URL fragment to correlate with local source." })),
+			maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan for URL literals. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+		}),
+	),
+	job: Type.Optional(
+		Type.Object({
+			steps: Type.Array(
+				Type.Object({
+					action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS, {
+						description: "Constrained one-call job step compiled to existing upstream batch commands.",
+					}),
+					url: Type.Optional(Type.String({ description: "URL for open steps, or URL pattern for assertUrl steps." })),
+					selector: Type.Optional(Type.String({ description: "Selector or @ref for click/fill/get-like steps." })),
+					text: Type.Optional(Type.String({ description: "Text for fill steps or visible text for assertText steps." })),
+					path: Type.Optional(Type.String({ description: "Artifact/download path for waitForDownload or screenshot steps." })),
+					milliseconds: Type.Optional(Type.Number({ description: "Milliseconds for wait steps." })),
+				}),
+				{ minItems: 1 },
+			),
+		}),
+	),
+	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, auth save --password-stdin, and is generated internally by job, qa, sourceLookup, or networkSourceLookup mode." })),
 	sessionMode: Type.Optional(
 		StringEnum(["auto", "fresh"] as const, {
 			description:
-				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable apply and later auto calls follow the new browser.",
+				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),
@@ -105,6 +293,635 @@ function buildInvocationPreview(effectiveArgs: string[]): string {
 	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
 }
 
+function getRequiredJobString(step: Record<string, unknown>, field: "path" | "selector" | "text" | "url", action: AgentBrowserJobStepAction): { value?: string; error?: string } {
+	const value = step[field];
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return { error: `job step ${action} requires a non-empty ${field} string.` };
+	}
+	return { value };
+}
+
+function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAgentBrowserJob; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "job must be an object." };
+	}
+	const rawSteps = input.steps;
+	if (!Array.isArray(rawSteps) || rawSteps.length === 0) {
+		return { error: "job.steps must be a non-empty array." };
+	}
+	const steps: CompiledAgentBrowserJobStep[] = [];
+	for (const [index, rawStep] of rawSteps.entries()) {
+		if (!isRecord(rawStep)) {
+			return { error: `job.steps[${index}] must be an object.` };
+		}
+		const action = rawStep.action;
+		if (typeof action !== "string" || !AGENT_BROWSER_JOB_STEP_ACTIONS.includes(action as AgentBrowserJobStepAction)) {
+			return { error: `job.steps[${index}].action must be one of: ${AGENT_BROWSER_JOB_STEP_ACTIONS.join(", ")}.` };
+		}
+		const jobAction = action as AgentBrowserJobStepAction;
+		let args: string[];
+		if (jobAction === "open") {
+			const result = getRequiredJobString(rawStep, "url", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["open", result.value as string];
+		} else if (jobAction === "click") {
+			const result = getRequiredJobString(rawStep, "selector", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["click", result.value as string];
+		} else if (jobAction === "fill") {
+			const selector = getRequiredJobString(rawStep, "selector", jobAction);
+			if (selector.error) return { error: `job.steps[${index}]: ${selector.error}` };
+			const text = getRequiredJobString(rawStep, "text", jobAction);
+			if (text.error) return { error: `job.steps[${index}]: ${text.error}` };
+			args = ["fill", selector.value as string, text.value as string];
+		} else if (jobAction === "wait") {
+			const milliseconds = rawStep.milliseconds;
+			if (typeof milliseconds !== "number" || !Number.isInteger(milliseconds) || milliseconds <= 0) {
+				return { error: `job.steps[${index}]: job step wait requires a positive integer milliseconds value.` };
+			}
+			args = ["wait", String(milliseconds)];
+		} else if (jobAction === "assertText") {
+			const result = getRequiredJobString(rawStep, "text", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--text", result.value as string];
+		} else if (jobAction === "assertUrl") {
+			const result = getRequiredJobString(rawStep, "url", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--url", result.value as string];
+		} else if (jobAction === "waitForDownload") {
+			const result = getRequiredJobString(rawStep, "path", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--download", result.value as string];
+		} else {
+			const result = getRequiredJobString(rawStep, "path", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["screenshot", result.value as string];
+		}
+		steps.push({ action: jobAction, args });
+	}
+	return { compiled: { args: ["batch"], stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+}
+
+interface AgentBrowserQaPresetAnalysis {
+	failedChecks: string[];
+	passed: boolean;
+	summary: string;
+}
+
+function getBatchResultItems(data: unknown): Array<Record<string, unknown>> {
+	return Array.isArray(data) ? data.filter(isRecord) : [];
+}
+
+function getCommandNameFromBatchItem(item: Record<string, unknown>): string | undefined {
+	const command = item.command;
+	return Array.isArray(command) && typeof command[0] === "string" ? command[0] : undefined;
+}
+
+function analyzeQaPresetResults(data: unknown): AgentBrowserQaPresetAnalysis | undefined {
+	const items = getBatchResultItems(data);
+	if (items.length === 0) return undefined;
+	const failedChecks: string[] = [];
+	for (const item of items) {
+		if (item.success === false) {
+			failedChecks.push(`${getCommandNameFromBatchItem(item) ?? "step"} failed`);
+		}
+		const result = isRecord(item.result) ? item.result : undefined;
+		const commandName = getCommandNameFromBatchItem(item);
+		if (commandName === "errors" && Array.isArray(result?.errors) && result.errors.length > 0) {
+			failedChecks.push(`${result.errors.length} page error(s)`);
+		}
+		if (commandName === "console" && Array.isArray(result?.messages)) {
+			const errorCount = result.messages.filter((message) => isRecord(message) && /error/i.test(String(message.type ?? message.level ?? ""))).length;
+			if (errorCount > 0) failedChecks.push(`${errorCount} console error message(s)`);
+		}
+		if (commandName === "network" && Array.isArray(result?.requests)) {
+			const failedRequestCount = result.requests.filter((request) => isRecord(request) && ((typeof request.status === "number" && request.status >= 400) || request.failed === true || typeof request.error === "string")).length;
+			if (failedRequestCount > 0) failedChecks.push(`${failedRequestCount} failed network request(s)`);
+		}
+	}
+	const uniqueFailures = [...new Set(failedChecks)];
+	return {
+		failedChecks: uniqueFailures,
+		passed: uniqueFailures.length === 0,
+		summary: uniqueFailures.length === 0 ? "QA preset passed." : `QA preset failed: ${uniqueFailures.join("; ")}.`,
+	};
+}
+
+function compileAgentBrowserQaPreset(input: unknown): { compiled?: CompiledAgentBrowserQaPreset; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "qa must be an object." };
+	}
+	const url = input.url;
+	if (typeof url !== "string" || url.trim().length === 0) {
+		return { error: "qa.url must be a non-empty string." };
+	}
+	const expectedText = input.expectedText === undefined
+		? []
+		: typeof input.expectedText === "string"
+			? [input.expectedText]
+			: Array.isArray(input.expectedText)
+				? input.expectedText
+				: undefined;
+	if (!expectedText || expectedText.some((text) => typeof text !== "string" || text.trim().length === 0)) {
+		return { error: "qa.expectedText must be a non-empty string or array of non-empty strings when provided." };
+	}
+	const expectedSelector = input.expectedSelector;
+	if (expectedSelector !== undefined && (typeof expectedSelector !== "string" || expectedSelector.trim().length === 0)) {
+		return { error: "qa.expectedSelector must be a non-empty string when provided." };
+	}
+	const screenshotPath = input.screenshotPath;
+	if (screenshotPath !== undefined && (typeof screenshotPath !== "string" || screenshotPath.trim().length === 0)) {
+		return { error: "qa.screenshotPath must be a non-empty string when provided." };
+	}
+	for (const field of ["checkConsole", "checkErrors", "checkNetwork"] as const) {
+		if (input[field] !== undefined && typeof input[field] !== "boolean") {
+			return { error: `qa.${field} must be a boolean when provided.` };
+		}
+	}
+	const checkConsole = input.checkConsole !== false;
+	const checkErrors = input.checkErrors !== false;
+	const checkNetwork = input.checkNetwork !== false;
+	const steps: CompiledAgentBrowserJobStep[] = [];
+	if (checkNetwork) steps.push({ action: "wait", args: ["network", "requests", "--clear"] });
+	if (checkConsole) steps.push({ action: "wait", args: ["console", "--clear"] });
+	if (checkErrors) steps.push({ action: "wait", args: ["errors", "--clear"] });
+	steps.push(
+		{ action: "open", args: ["open", url] },
+		{ action: "wait", args: ["wait", "--load", "networkidle"] },
+	);
+	for (const text of expectedText) {
+		steps.push({ action: "assertText", args: ["wait", "--text", text] });
+	}
+	if (typeof expectedSelector === "string") {
+		steps.push({ action: "wait", args: ["wait", expectedSelector] });
+	}
+	if (checkNetwork) steps.push({ action: "wait", args: ["network", "requests"] });
+	if (checkConsole) steps.push({ action: "wait", args: ["console"] });
+	if (checkErrors) steps.push({ action: "wait", args: ["errors"] });
+	if (typeof screenshotPath === "string") steps.push({ action: "screenshot", args: ["screenshot", screenshotPath] });
+	return {
+		compiled: {
+			args: ["batch"],
+			checks: { checkConsole, checkErrors, checkNetwork, expectedSelector, expectedText, screenshotPath, url },
+			stdin: JSON.stringify(steps.map((step) => step.args)),
+			steps,
+		},
+	};
+}
+
+function compileAgentBrowserSourceLookup(input: unknown): { compiled?: CompiledAgentBrowserSourceLookup; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "sourceLookup must be an object." };
+	}
+	const selector = input.selector;
+	const reactFiberId = input.reactFiberId;
+	const componentName = input.componentName;
+	if (selector !== undefined && (typeof selector !== "string" || selector.trim().length === 0)) {
+		return { error: "sourceLookup.selector must be a non-empty string when provided." };
+	}
+	if (reactFiberId !== undefined && (typeof reactFiberId !== "string" || reactFiberId.trim().length === 0)) {
+		return { error: "sourceLookup.reactFiberId must be a non-empty string when provided." };
+	}
+	if (componentName !== undefined && (typeof componentName !== "string" || componentName.trim().length === 0)) {
+		return { error: "sourceLookup.componentName must be a non-empty string when provided." };
+	}
+	if (selector === undefined && reactFiberId === undefined && componentName === undefined) {
+		return { error: "sourceLookup requires selector, reactFiberId, or componentName." };
+	}
+	if (input.includeDomHints !== undefined && typeof input.includeDomHints !== "boolean") {
+		return { error: "sourceLookup.includeDomHints must be a boolean when provided." };
+	}
+	const rawMaxWorkspaceFiles = input.maxWorkspaceFiles;
+	if (rawMaxWorkspaceFiles !== undefined && (typeof rawMaxWorkspaceFiles !== "number" || !Number.isInteger(rawMaxWorkspaceFiles) || rawMaxWorkspaceFiles <= 0)) {
+		return { error: "sourceLookup.maxWorkspaceFiles must be a positive integer when provided." };
+	}
+	if (typeof rawMaxWorkspaceFiles === "number" && rawMaxWorkspaceFiles > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
+		return { error: `sourceLookup.maxWorkspaceFiles must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
+	}
+	const includeDomHints = input.includeDomHints !== false;
+	const maxWorkspaceFiles = (rawMaxWorkspaceFiles as number | undefined) ?? SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES;
+	const steps: CompiledAgentBrowserSourceLookupStep[] = [];
+	if (typeof selector === "string") {
+		steps.push({ action: "dom", args: ["is", "visible", selector] });
+		if (includeDomHints) {
+			steps.push({ action: "dom", args: ["get", "html", selector] });
+		}
+	}
+	if (typeof reactFiberId === "string") {
+		steps.push({ action: "react", args: ["react", "inspect", reactFiberId] });
+	}
+	if (typeof componentName === "string") {
+		steps.push({ action: "react", args: ["react", "tree"] });
+	}
+	return {
+		compiled: {
+			args: ["batch"],
+			query: { componentName, includeDomHints, maxWorkspaceFiles, reactFiberId, selector },
+			stdin: JSON.stringify(steps.map((step) => step.args)),
+			steps,
+		},
+	};
+}
+
+function extractStringField(value: Record<string, unknown>, names: string[]): string | undefined {
+	for (const name of names) {
+		const field = value[name];
+		if (typeof field === "string" && field.trim().length > 0) return field;
+	}
+	return undefined;
+}
+
+function extractNumberField(value: Record<string, unknown>, names: string[]): number | undefined {
+	for (const name of names) {
+		const field = value[name];
+		if (typeof field === "number" && Number.isFinite(field)) return field;
+		if (typeof field === "string" && /^\d+$/.test(field)) return Number(field);
+	}
+	return undefined;
+}
+
+function candidateKey(candidate: AgentBrowserSourceLookupCandidate): string {
+	return [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.column ?? "", candidate.componentName ?? ""].join(":");
+}
+
+function addSourceLookupCandidate(candidates: AgentBrowserSourceLookupCandidate[], candidate: AgentBrowserSourceLookupCandidate): void {
+	if (!candidates.some((existing) => candidateKey(existing) === candidateKey(candidate))) {
+		candidates.push(candidate);
+	}
+}
+
+function collectSourceCandidatesFromValue(value: unknown, source: "react-inspect" | "dom-attribute", candidates: AgentBrowserSourceLookupCandidate[], evidence: string[], depth = 0): void {
+	if (depth > 6 || value === undefined || value === null) return;
+	if (typeof value === "string") {
+		const sourcePattern = /([A-Za-z0-9_./@-]+\.(?:tsx|jsx|ts|js))(?:[:#](\d+))?(?:[:#](\d+))?/g;
+		for (const match of value.matchAll(sourcePattern)) {
+			addSourceLookupCandidate(candidates, {
+				column: match[3] ? Number(match[3]) : undefined,
+				confidence: source === "react-inspect" ? "high" : "medium",
+				evidence,
+				file: match[1],
+				line: match[2] ? Number(match[2]) : undefined,
+				source,
+			});
+		}
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) collectSourceCandidatesFromValue(item, source, candidates, evidence, depth + 1);
+		return;
+	}
+	if (!isRecord(value)) return;
+	const file = extractStringField(value, ["file", "fileName", "filename", "filePath", "path", "source", "url"]);
+	if (file && /\.(?:tsx|jsx|ts|js)(?:$|[:?#])/.test(file)) {
+		addSourceLookupCandidate(candidates, {
+			column: extractNumberField(value, ["column", "columnNumber", "col"]),
+			confidence: source === "react-inspect" ? "high" : "medium",
+			evidence,
+			file,
+			line: extractNumberField(value, ["line", "lineNumber"]),
+			source,
+		});
+	}
+	for (const nested of Object.values(value)) {
+		collectSourceCandidatesFromValue(nested, source, candidates, evidence, depth + 1);
+	}
+}
+
+function getHtmlAttributeValue(html: string, name: string): string | undefined {
+	const pattern = new RegExp(`${name}=["']([^"']+)["']`, "i");
+	return pattern.exec(html)?.[1];
+}
+
+function collectDomSourceCandidates(html: unknown, candidates: AgentBrowserSourceLookupCandidate[]): void {
+	if (typeof html !== "string") return;
+	const file = getHtmlAttributeValue(html, "(?:data-source-file|data-file|data-component-file|data-source)");
+	if (file && /\.(?:tsx|jsx|ts|js)$/.test(file)) {
+		const line = getHtmlAttributeValue(html, "(?:data-source-line|data-line)");
+		const column = getHtmlAttributeValue(html, "(?:data-source-column|data-column)");
+		addSourceLookupCandidate(candidates, {
+			column: column && /^\d+$/.test(column) ? Number(column) : undefined,
+			confidence: "medium",
+			evidence: ["selector HTML contained source-like data attributes"],
+			file,
+			line: line && /^\d+$/.test(line) ? Number(line) : undefined,
+			source: "dom-attribute",
+		});
+	}
+	collectSourceCandidatesFromValue(html, "dom-attribute", candidates, ["selector HTML contained source-like text"]);
+}
+
+async function walkWorkspaceSourceFiles(root: string, maxFiles: number): Promise<string[]> {
+	const files: string[] = [];
+	async function visit(directory: string): Promise<void> {
+		if (files.length >= maxFiles) return;
+		let entries: Array<{ isDirectory: () => boolean; isFile: () => boolean; name: string }>;
+		try {
+			entries = await readdir(directory, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (files.length >= maxFiles) return;
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) {
+				if (!SOURCE_LOOKUP_IGNORED_DIRECTORIES.has(entry.name)) await visit(path);
+			} else if (entry.isFile() && SOURCE_LOOKUP_WORKSPACE_EXTENSIONS.has(extname(entry.name))) {
+				files.push(path);
+			}
+		}
+	}
+	await visit(root);
+	return files;
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function collectWorkspaceComponentCandidates(query: CompiledAgentBrowserSourceLookup["query"], cwd: string, candidates: AgentBrowserSourceLookupCandidate[], limitations: string[]): Promise<void> {
+	if (!query.componentName) return;
+	const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
+	if (files.length >= query.maxWorkspaceFiles) {
+		limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
+	}
+	const componentPattern = new RegExp(`(?:function|class)\\s+${escapeRegExp(query.componentName)}\\b|(?:const|let|var)\\s+${escapeRegExp(query.componentName)}\\s*=|export\\s+default\\s+function\\s+${escapeRegExp(query.componentName)}\\b`);
+	for (const file of files) {
+		let text: string;
+		try {
+			text = await readFile(file, "utf8");
+		} catch {
+			continue;
+		}
+		const match = componentPattern.exec(text);
+		if (!match) continue;
+		const line = text.slice(0, match.index).split("\n").length;
+		addSourceLookupCandidate(candidates, {
+			componentName: query.componentName,
+			confidence: "low",
+			evidence: [`local workspace contains a matching ${query.componentName} declaration`],
+			file,
+			line,
+			source: "workspace-search",
+		});
+		if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10) break;
+	}
+}
+
+function validateLookupMaxWorkspaceFiles(value: unknown, fieldName: string): { value?: number; error?: string } {
+	if (value === undefined) return { value: SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES };
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+		return { error: `${fieldName} must be a positive integer when provided.` };
+	}
+	if (value > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
+		return { error: `${fieldName} must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
+	}
+	return { value };
+}
+
+async function analyzeSourceLookupResults(data: unknown, compiled: CompiledAgentBrowserSourceLookup, cwd: string): Promise<AgentBrowserSourceLookupAnalysis> {
+	const items = getBatchResultItems(data);
+	const candidates: AgentBrowserSourceLookupCandidate[] = [];
+	const limitations = [
+		"Experimental lookup only reports candidates with evidence; it cannot guarantee a DOM node maps to one source file.",
+		"React source hints require the page to be opened with --enable react-devtools and source information from the app build.",
+	];
+	let unsupported = false;
+	for (const item of items) {
+		const command = Array.isArray(item.command) ? item.command : [];
+		const result = isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
+		if (item.success === false && command[0] === "react") unsupported = true;
+		if (command[0] === "react" && command[1] === "inspect") {
+			collectSourceCandidatesFromValue(result, "react-inspect", candidates, ["react inspect returned source-like metadata"]);
+		}
+		if (command[0] === "get" && command[1] === "html") {
+			collectDomSourceCandidates(result, candidates);
+		}
+	}
+	await collectWorkspaceComponentCandidates(compiled.query, cwd, candidates, limitations);
+	const status: AgentBrowserSourceLookupStatus = candidates.length > 0 ? "candidates-found" : unsupported ? "unsupported" : "no-candidates";
+	return {
+		candidates,
+		limitations,
+		status,
+		summary: candidates.length > 0
+			? `Source lookup found ${candidates.length} candidate location(s).`
+			: unsupported
+				? "Source lookup could not inspect React metadata in this session."
+				: "Source lookup found no candidate locations.",
+	};
+}
+
+function compileAgentBrowserNetworkSourceLookup(input: unknown): { compiled?: CompiledAgentBrowserNetworkSourceLookup; error?: string } {
+	if (!isRecord(input)) return { error: "networkSourceLookup must be an object." };
+	const filter = input.filter;
+	const requestId = input.requestId;
+	const url = input.url;
+	if (filter !== undefined && (typeof filter !== "string" || filter.trim().length === 0)) return { error: "networkSourceLookup.filter must be a non-empty string when provided." };
+	if (requestId !== undefined && (typeof requestId !== "string" || requestId.trim().length === 0)) return { error: "networkSourceLookup.requestId must be a non-empty string when provided." };
+	if (url !== undefined && (typeof url !== "string" || url.trim().length === 0)) return { error: "networkSourceLookup.url must be a non-empty string when provided." };
+	if (filter === undefined && requestId === undefined && url === undefined) return { error: "networkSourceLookup requires requestId, filter, or url." };
+	const maxWorkspaceFiles = validateLookupMaxWorkspaceFiles(input.maxWorkspaceFiles, "networkSourceLookup.maxWorkspaceFiles");
+	if (maxWorkspaceFiles.error) return { error: maxWorkspaceFiles.error };
+	const steps: Array<{ action: "network"; args: string[] }> = [];
+	if (typeof requestId === "string") {
+		steps.push({ action: "network", args: ["network", "request", requestId] });
+	}
+	const effectiveFilter = typeof filter === "string" ? filter : typeof url === "string" ? url : undefined;
+	if (effectiveFilter) {
+		steps.push({ action: "network", args: ["network", "requests", "--filter", effectiveFilter] });
+	}
+	return { compiled: { args: ["batch"], query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value as number, requestId, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+}
+
+function getResultPayload(item: Record<string, unknown>): unknown {
+	return isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
+}
+
+function networkRequestMatchesQuery(url: string | undefined, queryText: string | undefined): boolean {
+	return queryText === undefined || url === undefined || url.includes(queryText) || queryText.includes(url);
+}
+
+function isFailedNetworkRecord(request: Record<string, unknown>): boolean {
+	const status = typeof request.status === "number" ? request.status : undefined;
+	const error = typeof request.error === "string" ? request.error : undefined;
+	return request.failed === true || error !== undefined || (status !== undefined && status >= 400);
+}
+
+function getFailedNetworkRequests(data: unknown, queryText?: string): AgentBrowserNetworkSourceLookupRequest[] {
+	const failed: AgentBrowserNetworkSourceLookupRequest[] = [];
+	for (const item of getBatchResultItems(data)) {
+		const payload = getResultPayload(item);
+		const requests = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : Array.isArray(payload) ? payload : isRecord(payload) ? [payload] : [];
+		for (const request of requests) {
+			if (!isRecord(request)) continue;
+			const url = typeof request.url === "string" ? request.url : undefined;
+			if (!networkRequestMatchesQuery(url, queryText) || !isFailedNetworkRecord(request)) continue;
+			failed.push({
+				error: typeof request.error === "string" ? request.error : undefined,
+				method: typeof request.method === "string" ? request.method : undefined,
+				requestId: typeof request.id === "string" ? request.id : typeof request.requestId === "string" ? request.requestId : undefined,
+				status: typeof request.status === "number" ? request.status : undefined,
+				url,
+			});
+		}
+	}
+	return failed;
+}
+
+function addNetworkCandidate(candidates: AgentBrowserNetworkSourceLookupCandidate[], candidate: AgentBrowserNetworkSourceLookupCandidate): void {
+	const key = [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.requestUrl ?? ""].join(":");
+	if (!candidates.some((existing) => [existing.source, existing.file ?? "", existing.line ?? "", existing.requestUrl ?? ""].join(":") === key)) candidates.push(candidate);
+}
+
+function collectInitiatorCandidates(data: unknown, failedRequests: AgentBrowserNetworkSourceLookupRequest[], candidates: AgentBrowserNetworkSourceLookupCandidate[]): void {
+	const failedRequestIds = new Set(failedRequests.map((request) => request.requestId).filter((value): value is string => value !== undefined));
+	const failedRequestUrls = new Set(failedRequests.map((request) => request.url).filter((value): value is string => value !== undefined));
+	for (const item of getBatchResultItems(data)) {
+		const payload = getResultPayload(item);
+		const requestValues = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : [payload];
+		for (const value of requestValues) {
+			if (!isRecord(value)) continue;
+			const requestUrl = typeof value.url === "string" ? value.url : undefined;
+			const requestId = typeof value.id === "string" ? value.id : typeof value.requestId === "string" ? value.requestId : undefined;
+			const correlatesWithFailedRequest = (requestId !== undefined && failedRequestIds.has(requestId)) || (requestUrl !== undefined && failedRequestUrls.has(requestUrl));
+			if (!correlatesWithFailedRequest && !isFailedNetworkRecord(value)) continue;
+			for (const field of [value.initiator, value.stack, value.source, value.trace]) {
+				const localCandidates: AgentBrowserSourceLookupCandidate[] = [];
+				collectSourceCandidatesFromValue(field, "dom-attribute", localCandidates, ["failed network request included source-like initiator metadata"]);
+				for (const candidate of localCandidates) {
+					addNetworkCandidate(candidates, { confidence: "medium", evidence: candidate.evidence, file: candidate.file, line: candidate.line, requestUrl, source: "initiator" });
+				}
+			}
+		}
+	}
+}
+
+async function collectWorkspaceRequestCandidates(query: CompiledAgentBrowserNetworkSourceLookup["query"], failedRequests: AgentBrowserNetworkSourceLookupRequest[], cwd: string, candidates: AgentBrowserNetworkSourceLookupCandidate[], limitations: string[]): Promise<void> {
+	const needles = [...new Set([query.url, query.filter, ...failedRequests.map((request) => request.url)].filter((value): value is string => typeof value === "string" && value.length > 0).flatMap((value) => {
+		try {
+			const parsed = new URL(value);
+			return [value, parsed.pathname].filter((item) => item && item !== "/");
+		} catch {
+			return [value];
+		}
+	}))].slice(0, 8);
+	if (needles.length === 0) return;
+	const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
+	if (files.length >= query.maxWorkspaceFiles) limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
+	for (const file of files) {
+		let text: string;
+		try { text = await readFile(file, "utf8"); } catch { continue; }
+		for (const needle of needles) {
+			const index = text.indexOf(needle);
+			if (index === -1) continue;
+			addNetworkCandidate(candidates, { confidence: "low", evidence: [`local workspace contains request URL literal ${needle}`], file, line: text.slice(0, index).split("\n").length, requestUrl: needle, source: "workspace-search" });
+			if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10) return;
+		}
+	}
+}
+
+function redactNetworkSourceLookupUrl(value: string | undefined): string | undefined {
+	if (!value) return value;
+	try {
+		const isRelative = value.startsWith("/");
+		const url = new URL(value, isRelative ? "https://redacted.invalid" : undefined);
+		url.username = url.username ? "[REDACTED]" : "";
+		url.password = url.password ? "[REDACTED]" : "";
+		for (const key of [...url.searchParams.keys()]) {
+			url.searchParams.set(key, "[REDACTED]");
+		}
+		if (/(?:token|secret|password|passwd|pwd|key|auth|session|jwt|credential)/i.test(url.hash)) {
+			url.hash = "#[REDACTED]";
+		}
+		return isRelative ? `${url.pathname}${url.search}${url.hash}` : url.toString();
+	} catch {
+		return redactSensitiveText(value
+			.replace(/([a-z][a-z0-9+.-]*:\/\/)\S+:\S+@/gi, "$1[REDACTED]@")
+			.replace(/([?&][^=]+)=([^&#\s"'\]]+)/g, "$1=[REDACTED]"));
+	}
+}
+
+function redactNetworkSourceLookupArgs(args: string[]): string[] {
+	return redactInvocationArgs(args).map((arg) => redactNetworkSourceLookupUrl(arg) ?? arg);
+}
+
+function redactNetworkSourceLookupSurface(value: unknown): unknown {
+	if (typeof value === "string") return redactNetworkSourceLookupUrl(value) ?? value;
+	if (Array.isArray(value)) return value.map((item) => redactNetworkSourceLookupSurface(item));
+	if (!isRecord(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactNetworkSourceLookupSurface(item)]));
+}
+
+function redactNetworkSourceLookupAnalysis(analysis: AgentBrowserNetworkSourceLookupAnalysis): AgentBrowserNetworkSourceLookupAnalysis {
+	return {
+		...analysis,
+		candidates: analysis.candidates.map((candidate) => ({
+			...candidate,
+			evidence: candidate.evidence.map((item) => redactNetworkSourceLookupUrl(item) ?? redactSensitiveText(item)),
+			file: redactNetworkSourceLookupUrl(candidate.file),
+			requestUrl: redactNetworkSourceLookupUrl(candidate.requestUrl),
+		})),
+		failedRequests: analysis.failedRequests.map((request) => ({ ...request, error: redactNetworkSourceLookupUrl(request.error), url: redactNetworkSourceLookupUrl(request.url) })),
+	};
+}
+
+async function analyzeNetworkSourceLookupResults(data: unknown, compiled: CompiledAgentBrowserNetworkSourceLookup, cwd: string): Promise<AgentBrowserNetworkSourceLookupAnalysis> {
+	const limitations = [
+		"Experimental network source hints report candidates only; failed requests can be triggered indirectly by frameworks, caches, service workers, or third-party scripts.",
+		"Initiator/source-map metadata is upstream/browser-build dependent and may be absent.",
+	];
+	const failedRequests = getFailedNetworkRequests(data, compiled.query.url ?? compiled.query.filter);
+	const candidates: AgentBrowserNetworkSourceLookupCandidate[] = [];
+	collectInitiatorCandidates(data, failedRequests, candidates);
+	await collectWorkspaceRequestCandidates(compiled.query, failedRequests, cwd, candidates, limitations);
+	const status: AgentBrowserNetworkSourceLookupStatus = failedRequests.length === 0 ? "no-failed-requests" : candidates.length > 0 ? "failed-requests-found" : "no-candidates";
+	return { candidates, failedRequests, limitations, status, summary: failedRequests.length === 0 ? "Network source lookup found no failed requests." : candidates.length > 0 ? `Network source lookup found ${failedRequests.length} failed request(s) and ${candidates.length} candidate source hint(s).` : `Network source lookup found ${failedRequests.length} failed request(s) but no source candidates.` };
+}
+
+function compileAgentBrowserSemanticAction(input: unknown): { compiled?: CompiledAgentBrowserSemanticAction; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "semanticAction must be an object." };
+	}
+	const action = input.action;
+	const locator = input.locator;
+	const value = input.value;
+	const text = input.text;
+	const role = input.role;
+	const name = input.name;
+	if (typeof action !== "string" || !AGENT_BROWSER_SEMANTIC_ACTIONS.includes(action as AgentBrowserSemanticActionName)) {
+		return { error: `semanticAction.action must be one of: ${AGENT_BROWSER_SEMANTIC_ACTIONS.join(", ")}.` };
+	}
+	if (typeof locator !== "string" || !AGENT_BROWSER_SEMANTIC_LOCATORS.includes(locator as AgentBrowserSemanticLocator)) {
+		return { error: `semanticAction.locator must be one of: ${AGENT_BROWSER_SEMANTIC_LOCATORS.join(", ")}.` };
+	}
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return { error: "semanticAction.value must be a non-empty string." };
+	}
+	if (text !== undefined && typeof text !== "string") {
+		return { error: "semanticAction.text must be a string when provided." };
+	}
+	if ((action === "fill" || action === "select") && (typeof text !== "string" || text.length === 0)) {
+		return { error: `semanticAction.text is required for ${action}.` };
+	}
+	if (action !== "fill" && action !== "select" && text !== undefined) {
+		return { error: `semanticAction.text is only supported for fill and select actions.` };
+	}
+	if (role !== undefined && (locator !== "role" || role !== value)) {
+		return { error: "semanticAction.role is only supported for locator=role and must match value." };
+	}
+	if (name !== undefined && (locator !== "role" || typeof name !== "string" || name.length === 0)) {
+		return { error: "semanticAction.name is only supported as a non-empty string for locator=role." };
+	}
+	const args = ["find", locator, value, action];
+	if (action === "fill" || action === "select") {
+		args.push(text as string);
+	}
+	if (locator === "role" && typeof name === "string") {
+		args.push("--name", name);
+	}
+	return { compiled: { action: action as AgentBrowserSemanticActionName, locator: locator as AgentBrowserSemanticLocator, args } };
+}
+
 const TUI_COLLAPSED_OUTPUT_MAX_LINES = 10;
 const TUI_INVOCATION_PREVIEW_MAX_CHARS = 120;
 const ANSI_CONTROL_SEQUENCE_PATTERN = /\x1B(?:\][^\x07\x1B]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B]*(?:\x1B\\)|_[^\x1B]*(?:\x1B\\)|\^[^\x1B]*(?:\x1B\\)|[@-Z\\-_])/g;
@@ -178,7 +995,15 @@ function formatVisualTruncationNotice(remainingLines: number, totalLines: number
 
 function formatAgentBrowserRenderCall(args: unknown, theme: Theme): string {
 	const input = isRecord(args) ? args : {};
-	const rawArgs = Array.isArray(input.args) ? input.args.filter((value): value is string => typeof value === "string") : [];
+	const semanticAction = compileAgentBrowserSemanticAction(input.semanticAction);
+	const job = compileAgentBrowserJob(input.job);
+	const qa = compileAgentBrowserQaPreset(input.qa);
+	const sourceLookup = compileAgentBrowserSourceLookup(input.sourceLookup);
+	const networkSourceLookup = compileAgentBrowserNetworkSourceLookup(input.networkSourceLookup);
+	const generatedBatch = networkSourceLookup.compiled ?? sourceLookup.compiled ?? job.compiled ?? qa.compiled;
+	const rawArgs = Array.isArray(input.args)
+		? input.args.filter((value): value is string => typeof value === "string")
+		: (semanticAction.compiled?.args ?? generatedBatch?.args ?? []);
 	const redactedArgs = redactInvocationArgs(rawArgs);
 	const invocation = sanitizeDisplayText(redactedArgs.join(" ")).replace(/\s+/g, " ").trim();
 	const invocationPreview =
@@ -1723,17 +2548,77 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			return component;
 		},
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const redactedArgs = redactInvocationArgs(params.args);
-			const validationError = validateToolArgs(params.args) ?? getBatchAnnotateValidationError(params.args, params.stdin);
+			const semanticActionResult = params.semanticAction === undefined ? {} : compileAgentBrowserSemanticAction(params.semanticAction);
+			const jobResult = params.job === undefined ? {} : compileAgentBrowserJob(params.job);
+			const qaResult = params.qa === undefined ? {} : compileAgentBrowserQaPreset(params.qa);
+			const sourceLookupResult = params.sourceLookup === undefined ? {} : compileAgentBrowserSourceLookup(params.sourceLookup);
+			const networkSourceLookupResult = params.networkSourceLookup === undefined ? {} : compileAgentBrowserNetworkSourceLookup(params.networkSourceLookup);
+			const hasExplicitArgs = Array.isArray(params.args);
+			const explicitInputModes = [hasExplicitArgs, Boolean(semanticActionResult.compiled), Boolean(jobResult.compiled), Boolean(qaResult.compiled), Boolean(sourceLookupResult.compiled), Boolean(networkSourceLookupResult.compiled)].filter(Boolean).length;
+			const semanticActionError = semanticActionResult.error;
+			const jobError = jobResult.error;
+			const qaError = qaResult.error;
+			const sourceLookupError = sourceLookupResult.error;
+			const networkSourceLookupError = networkSourceLookupResult.error;
+			const inputModeError = explicitInputModes !== 1
+				? "Provide exactly one of args, semanticAction, job, qa, sourceLookup, or networkSourceLookup."
+				: undefined;
+			const compiledSemanticAction = semanticActionResult.compiled;
+			const compiledQaPreset = qaResult.compiled;
+			const compiledSourceLookup = sourceLookupResult.compiled;
+			const compiledNetworkSourceLookup = networkSourceLookupResult.compiled;
+			const compiledJob = jobResult.compiled ?? compiledQaPreset;
+			const compiledGeneratedBatch = compiledNetworkSourceLookup ?? compiledSourceLookup ?? compiledJob;
+			const toolArgs = compiledSemanticAction?.args ?? compiledGeneratedBatch?.args ?? params.args ?? [];
+			const toolStdin = compiledGeneratedBatch?.stdin ?? params.stdin;
+			const redactedArgs = redactInvocationArgs(toolArgs);
+			const generatedStdinError = compiledGeneratedBatch && params.stdin !== undefined ? "Do not provide stdin with job, qa, sourceLookup, or networkSourceLookup; those modes generate their own batch stdin." : undefined;
+			const validationError = semanticActionError ?? jobError ?? qaError ?? sourceLookupError ?? networkSourceLookupError ?? inputModeError ?? generatedStdinError ?? validateToolArgs(toolArgs) ?? getBatchAnnotateValidationError(toolArgs, toolStdin);
+			const redactedCompiledSemanticAction = compiledSemanticAction
+				? { ...compiledSemanticAction, args: redactInvocationArgs(compiledSemanticAction.args) }
+				: undefined;
+			const redactedCompiledJobSteps = compiledJob?.steps.map((step) => ({ ...step, args: redactInvocationArgs(step.args) }));
+			const redactedCompiledJob = compiledJob && redactedCompiledJobSteps
+				? { ...compiledJob, stdin: JSON.stringify(redactedCompiledJobSteps.map((step) => step.args)), steps: redactedCompiledJobSteps }
+				: undefined;
+			const redactedCompiledQaPreset = compiledQaPreset && redactedCompiledJob
+				? { ...redactedCompiledJob, checks: compiledQaPreset.checks }
+				: undefined;
+			const redactedCompiledSourceLookupSteps = compiledSourceLookup?.steps.map((step) => ({ ...step, args: redactInvocationArgs(step.args) }));
+			const redactedCompiledSourceLookup = compiledSourceLookup && redactedCompiledSourceLookupSteps
+				? { ...compiledSourceLookup, stdin: JSON.stringify(redactedCompiledSourceLookupSteps.map((step) => step.args)), steps: redactedCompiledSourceLookupSteps }
+				: undefined;
+			const redactedCompiledNetworkSourceLookupSteps = compiledNetworkSourceLookup?.steps.map((step) => ({ ...step, args: redactNetworkSourceLookupArgs(step.args) }));
+			const redactedCompiledNetworkSourceLookup = compiledNetworkSourceLookup && redactedCompiledNetworkSourceLookupSteps
+				? {
+					...compiledNetworkSourceLookup,
+					query: {
+						...compiledNetworkSourceLookup.query,
+						filter: redactNetworkSourceLookupUrl(compiledNetworkSourceLookup.query.filter),
+						url: redactNetworkSourceLookupUrl(compiledNetworkSourceLookup.query.url),
+					},
+					stdin: JSON.stringify(redactedCompiledNetworkSourceLookupSteps.map((step) => step.args)),
+					steps: redactedCompiledNetworkSourceLookupSteps,
+				}
+				: undefined;
 			if (validationError) {
 				return {
 					content: [{ type: "text", text: validationError }],
-					details: { args: redactedArgs, validationError },
+					details: {
+						args: redactedArgs,
+						compiledJob: redactedCompiledJob,
+						compiledQaPreset: redactedCompiledQaPreset,
+						compiledSourceLookup: redactedCompiledSourceLookup,
+						compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
+						compiledSemanticAction: redactedCompiledSemanticAction,
+						...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, errorText: validationError, succeeded: false, validationError }),
+						validationError,
+					},
 					isError: true,
 				};
 			}
-			const preparedArgs = await prepareAgentBrowserArgs(params.args, params.stdin, ctx.cwd);
-			const userRequestedJson = params.args.includes("--json");
+			const preparedArgs = await prepareAgentBrowserArgs(toolArgs, toolStdin, ctx.cwd);
+			const userRequestedJson = toolArgs.includes("--json");
 
 			const tabTargetUpdateOrder = ++sessionTabTargetUpdateOrder;
 			const runTool = async (): Promise<AgentBrowserToolResult> => {
@@ -1757,10 +2642,15 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						content: [{ type: "text", text: executionPlan.validationError }],
 						details: {
 							args: redactedArgs,
+							compiledJob: redactedCompiledJob,
+							compiledQaPreset: redactedCompiledQaPreset,
+							compiledSourceLookup: redactedCompiledSourceLookup,
+							compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
 							invalidValueFlag: executionPlan.invalidValueFlag,
 							sessionMode,
 							sessionRecoveryHint: redactedRecoveryHint,
 							startupScopedFlags: executionPlan.startupScopedFlags,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, command: executionPlan.commandInfo.command, errorText: executionPlan.validationError, succeeded: false, validationError: executionPlan.validationError }),
 							validationError: executionPlan.validationError,
 						},
 						isError: true,
@@ -1771,7 +2661,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				const exactSensitiveValues = getExactSensitiveStdinValues({
 					command: executionPlan.commandInfo.command,
 					commandTokens,
-					stdin: params.stdin,
+					stdin: toolStdin,
 				});
 				const traceOwnerGuardMessage = getTraceOwnerGuardMessage({
 					command: executionPlan.commandInfo.command,
@@ -1788,6 +2678,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							compatibilityWorkaround,
 							effectiveArgs: redactedEffectiveArgs,
 							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: traceOwnerGuardMessage, succeeded: false, validationError: traceOwnerGuardMessage }),
 							validationError: traceOwnerGuardMessage,
 							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						},
@@ -1797,7 +2688,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				const stdinValidationError = validateStdinCommandContract({
 					command: executionPlan.commandInfo.command,
 					commandTokens,
-					stdin: params.stdin,
+					stdin: toolStdin,
 				});
 				if (stdinValidationError) {
 					return {
@@ -1808,13 +2699,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							compatibilityWorkaround,
 							effectiveArgs: redactedEffectiveArgs,
 							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: stdinValidationError, succeeded: false, validationError: stdinValidationError }),
 							validationError: stdinValidationError,
 							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						},
 						isError: true,
 					};
 				}
-				const waitIpcTimeoutError = validateWaitIpcTimeoutContract(commandTokens, params.stdin);
+				const waitIpcTimeoutError = validateWaitIpcTimeoutContract(commandTokens, toolStdin);
 				if (waitIpcTimeoutError) {
 					return {
 						content: [{ type: "text", text: waitIpcTimeoutError }],
@@ -1824,6 +2716,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							compatibilityWorkaround,
 							effectiveArgs: redactedEffectiveArgs,
 							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: waitIpcTimeoutError, succeeded: false, timedOut: true, validationError: waitIpcTimeoutError }),
 							validationError: waitIpcTimeoutError,
 							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						},
@@ -1837,14 +2730,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				let includePinnedNavigationSummary = false;
 				let sessionTabCorrection: OpenResultTabCorrection | undefined;
 				let processArgs = executionPlan.effectiveArgs;
-				let processStdin = preparedArgs.stdin ?? params.stdin;
+				let processStdin = preparedArgs.stdin ?? toolStdin;
 				if (
 					priorSessionTabTarget &&
 					shouldPinSessionTabForCommand({
 						command: executionPlan.commandInfo.command,
 						commandTokens,
 						sessionName: executionPlan.sessionName,
-						stdin: params.stdin,
+						stdin: toolStdin,
 					})
 				) {
 					const plannedSessionTabSelection = await collectSessionTabSelection({
@@ -1854,7 +2747,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						target: priorSessionTabTarget,
 					});
 					if (plannedSessionTabSelection && executionPlan.sessionName) {
-						if (executionPlan.commandInfo.command === "eval" && params.stdin !== undefined) {
+						if (executionPlan.commandInfo.command === "eval" && toolStdin !== undefined) {
 							const appliedSessionTabSelection = await applyOpenResultTabCorrection({
 								correction: plannedSessionTabSelection,
 								cwd: ctx.cwd,
@@ -1872,6 +2765,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 										effectiveArgs: redactedEffectiveArgs,
 										sessionMode,
 										sessionTabCorrection: plannedSessionTabSelection,
+										...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: error, failureCategory: "tab-drift", succeeded: false, tabDrift: true, validationError: error }),
+										nextActions: buildAgentBrowserNextActions({ failureCategory: "tab-drift", resultCategory: "failure" }),
 										validationError: error,
 										...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 									},
@@ -1884,7 +2779,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 								command: executionPlan.commandInfo.command,
 								commandTokens,
 								selectedTab: plannedSessionTabSelection.selectedTab,
-								stdin: params.stdin,
+								stdin: toolStdin,
 							});
 							if (pinnedBatchPlan && "error" in pinnedBatchPlan) {
 								return {
@@ -1896,6 +2791,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 										effectiveArgs: redactedEffectiveArgs,
 										sessionMode,
 										sessionTabCorrection: plannedSessionTabSelection,
+										...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: pinnedBatchPlan.error, failureCategory: "tab-drift", succeeded: false, tabDrift: true, validationError: pinnedBatchPlan.error }),
+										nextActions: buildAgentBrowserNextActions({ failureCategory: "tab-drift", resultCategory: "failure" }),
 										validationError: pinnedBatchPlan.error,
 										...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 									},
@@ -1943,6 +2840,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							effectiveArgs: redactedProcessArgs,
 							sessionMode,
 							sessionTabCorrection,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedProcessArgs, command: executionPlan.commandInfo.command, errorText, failureCategory: "missing-binary", spawnError: processResult.spawnError.message, succeeded: false }),
 							spawnError: processResult.spawnError.message,
 						},
 						isError: true,
@@ -1997,7 +2895,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					const plainTextInspection = executionPlan.plainTextInspection && processSucceeded;
 					const parseSucceeded = plainTextInspection || parseError === undefined;
 					const envelopeSuccess = plainTextInspection ? true : presentationEnvelope?.success !== false;
-					const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
+					let succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
 					const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
 					updateTraceOwnerState({
 						command: executionPlan.commandInfo.command,
@@ -2025,7 +2923,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					if (
 						succeeded &&
 						executionPlan.sessionName &&
-						hasLaunchScopedTabCorrectionFlag(params.args) &&
+						hasLaunchScopedTabCorrectionFlag(toolArgs) &&
 						(executionPlan.commandInfo.command === "goto" ||
 							executionPlan.commandInfo.command === "navigate" ||
 							executionPlan.commandInfo.command === "open")
@@ -2165,7 +3063,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						exitCode: processResult.exitCode,
 						parseError,
 						plainTextInspection,
-						staleRefArgs: getStaleRefArgs(commandTokens, params.stdin),
+						staleRefArgs: getStaleRefArgs(commandTokens, toolStdin),
 						spawnError: processResult.spawnError,
 						stderr: processResult.stderr,
 						timedOut: processResult.timedOut,
@@ -2189,6 +3087,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							summary: `${redactedArgs.join(" ")} completed`,
 						  }
 						: await buildToolPresentation({
+								args: redactedProcessArgs,
 								artifactManifest,
 								artifactRequest: screenshotArtifactRequest,
 								batchArtifactRequests: batchScreenshotArtifactRequests,
@@ -2220,6 +3119,29 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					if (presentation.artifactManifest) {
 						artifactManifest = presentation.artifactManifest;
 					}
+					const qaPreset = compiledQaPreset ? analyzeQaPresetResults(presentationEnvelope?.data) : undefined;
+					const sourceLookup = compiledSourceLookup ? await analyzeSourceLookupResults(presentationEnvelope?.data, compiledSourceLookup, ctx.cwd) : undefined;
+					const networkSourceLookup = compiledNetworkSourceLookup ? redactNetworkSourceLookupAnalysis(await analyzeNetworkSourceLookupResults(presentationEnvelope?.data, compiledNetworkSourceLookup, ctx.cwd)) : undefined;
+					if (networkSourceLookup && presentation.content[0]?.type === "text") {
+						presentation.content[0] = { ...presentation.content[0], text: `${networkSourceLookup.summary}\n\n${presentation.content[0].text}` };
+					} else if (networkSourceLookup) {
+						presentation.content.unshift({ type: "text", text: networkSourceLookup.summary });
+					}
+					if (sourceLookup && presentation.content[0]?.type === "text") {
+						presentation.content[0] = { ...presentation.content[0], text: `${sourceLookup.summary}\n\n${presentation.content[0].text}` };
+					} else if (sourceLookup) {
+						presentation.content.unshift({ type: "text", text: sourceLookup.summary });
+					}
+					if (qaPreset && !qaPreset.passed) {
+						succeeded = false;
+						presentation.failureCategory = "qa-failure";
+						presentation.summary = qaPreset.summary;
+						if (presentation.content[0]?.type === "text") {
+							presentation.content[0] = { ...presentation.content[0], text: `${qaPreset.summary}\n\n${presentation.content[0].text}` };
+						} else {
+							presentation.content.unshift({ type: "text", text: qaPreset.summary });
+						}
+					}
 					const warningText = aboutBlankSessionMismatch ? buildAboutBlankWarning(aboutBlankSessionMismatch) : undefined;
 					const contentWithSessionWarnings = userRequestedJson && !plainTextInspection
 						? buildJsonVisibleContent({
@@ -2248,20 +3170,53 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							? { ...item, text: exactRedactedText }
 							: { ...item, text: redactSensitiveText(exactRedactedText) };
 					});
+					const categoryDetails = buildAgentBrowserResultCategoryDetails({
+						artifacts: presentation.artifacts,
+						args: redactedProcessArgs,
+						command: executionPlan.commandInfo.command,
+						confirmationRequired: presentation.summary.startsWith("Confirmation required"),
+						errorText: errorText ?? presentation.summary,
+						failureCategory: presentation.failureCategory ?? presentation.batchFailure?.failedStep.failureCategory,
+						inspection: plainTextInspection,
+						parseError,
+						savedFile: presentation.savedFile,
+						spawnError: processResult.spawnError?.message,
+						succeeded,
+						tabDrift: !succeeded && (aboutBlankSessionMismatch !== undefined || sessionTabCorrection !== undefined),
+						timedOut: processResult.timedOut,
+						validationError: undefined,
+					});
+					let nextActions = presentation.nextActions ? [...presentation.nextActions] : undefined;
+					if (categoryDetails.failureCategory === "stale-ref" && redactedCompiledSemanticAction) {
+						(nextActions ??= []).push({
+							id: "retry-semantic-action-after-stale-ref",
+							params: { args: redactedCompiledSemanticAction.args },
+							reason: "Retry the same semantic target via its compiled find command after the upstream stale-ref failure proves the prior action did not execute.",
+							safety: "Use only for the same intended target; direct stale @refs still require a fresh snapshot or stable locator before retrying.",
+							tool: "agent_browser" as const,
+						});
+					}
 					const details = {
 						args: redactedArgs,
+						compiledJob: redactedCompiledJob,
+						compiledQaPreset: redactedCompiledQaPreset,
+						compiledSourceLookup: redactedCompiledSourceLookup,
+						compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
 						artifactManifest: presentation.artifactManifest,
 						artifactRetentionSummary: presentation.artifactRetentionSummary,
+						artifactVerification: presentation.artifactVerification,
 						artifacts: presentation.artifacts,
 						batchFailure: presentation.batchFailure,
 						batchSteps: presentation.batchSteps,
 						command: executionPlan.commandInfo.command,
+						compiledSemanticAction: redactedCompiledSemanticAction,
 						compatibilityWorkaround,
 						subcommand: executionPlan.commandInfo.subcommand,
 						data: presentation.data,
 						error: plainTextInspection ? undefined : presentationEnvelope?.error,
 						inspection: plainTextInspection || undefined,
 						navigationSummary,
+						...categoryDetails,
 						aboutBlankSessionMismatch,
 						openResultTabCorrection,
 						effectiveArgs: redactedProcessArgs,
@@ -2271,9 +3226,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						fullOutputUnavailable: parseFailureOutput.fullOutputUnavailable,
 						imagePath: presentation.imagePath,
 						imagePaths: presentation.imagePaths,
+						nextActions,
+						pageChangeSummary: presentation.pageChangeSummary,
+						qaPreset,
 						parseError: plainTextInspection ? undefined : parseError,
 						savedFile: presentation.savedFile,
 						savedFilePath: presentation.savedFilePath,
+						sourceLookup,
+						networkSourceLookup,
 						sessionMode,
 						sessionTabCorrection,
 						sessionTabTarget: currentSessionTabTarget,
@@ -2287,11 +3247,12 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						timeoutMs: processResult.timeoutMs,
 					};
 
-					return {
+					const result = {
 						content: redactedContent,
 						details: redactToolDetails(details, exactSensitiveValues),
 						isError: !succeeded,
 					};
+					return compiledNetworkSourceLookup ? redactNetworkSourceLookupSurface(result) as typeof result : result;
 				} finally {
 					if (processResult.stdoutSpillPath) {
 						await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
@@ -2299,7 +3260,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				}
 			};
 
-			return extractExplicitSessionName(params.args)
+			return extractExplicitSessionName(toolArgs)
 				? runTool()
 				: managedSessionExecutionQueue.run(runTool);
 		},