pi-agent-browser-native 0.2.29 → 0.2.31

package/extensions/agent-browser/index.ts

@@ -86,7 +86,7 @@ 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 AGENT_BROWSER_JOB_STEP_ACTIONS = ["open", "click", "fill", "select", "wait", "assertText", "assertUrl", "waitForDownload", "screenshot"] as const;
 const AGENT_BROWSER_QA_LOAD_STATES = ["domcontentloaded", "load", "networkidle"] 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"]);
@@ -102,8 +102,10 @@ type AgentBrowserNetworkSourceLookupStatus = "failed-requests-found" | "no-faile
 
 interface AgentBrowserSemanticActionInput {
 	action: AgentBrowserSemanticActionName;
-	locator: AgentBrowserSemanticLocator;
-	value: string;
+	locator?: AgentBrowserSemanticLocator;
+	value?: string;
+	values?: string[];
+	selector?: string;
 	text?: string;
 	role?: string;
 	name?: string;
@@ -112,7 +114,9 @@ interface AgentBrowserSemanticActionInput {
 
 interface CompiledAgentBrowserSemanticAction {
 	action: AgentBrowserSemanticActionName;
-	locator: AgentBrowserSemanticLocator;
+	locator?: AgentBrowserSemanticLocator;
+	selector?: string;
+	values?: string[];
 	args: string[];
 }
 
@@ -225,6 +229,7 @@ interface CompiledAgentBrowserNetworkSourceLookup {
 		filter?: string;
 		maxWorkspaceFiles: number;
 		requestId?: string;
+		session?: string;
 		url?: string;
 	};
 }
@@ -265,16 +270,18 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 	semanticAction: Type.Optional(
 		Type.Object({
 			action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS, {
-				description: "Intent action to compile to an existing agent-browser find command.",
+				description: "Intent action to compile to an existing agent-browser find command, or to upstream select when action=select.",
 			}),
-			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." })),
+			locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, {
+				description: "Upstream find locator family to use for check/click/fill/uncheck actions.",
+			})),
+			value: Type.Optional(Type.String({ description: "Locator value for find actions, or a single option value for select actions." })),
+			values: Type.Optional(Type.Array(Type.String({ description: "Option value for select actions." }), { description: "One or more option values for select actions.", minItems: 1 })),
+			selector: Type.Optional(Type.String({ description: "Selector or @ref for select actions; compiled to select <selector> <value...>." })),
+			text: Type.Optional(Type.String({ description: "Text/value argument for fill 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>." })),
-			session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the compiled find command." })),
+			session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the compiled command." })),
 		}),
 	),
 	qa: Type.Optional(
@@ -302,6 +309,7 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 		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>." })),
+			session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the generated batch." })),
 			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 })),
 		}),
@@ -314,8 +322,10 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 						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." })),
+					selector: Type.Optional(Type.String({ description: "Selector or @ref for click/fill/select-like steps." })),
 					text: Type.Optional(Type.String({ description: "Text for fill steps or visible text for assertText steps." })),
+					value: Type.Optional(Type.String({ description: "Single option value for select steps." })),
+					values: Type.Optional(Type.Array(Type.String({ description: "Option value for select steps." }), { description: "One or more option values for select steps.", minItems: 1 })),
 					path: Type.Optional(Type.String({ description: "Artifact/download path for waitForDownload or screenshot steps." })),
 					milliseconds: Type.Optional(Type.Number({ description: "Milliseconds for wait steps." })),
 				}),
@@ -355,6 +365,24 @@ function getRequiredJobString(step: Record<string, unknown>, field: "path" | "se
 	return { value };
 }
 
+function getSelectValues(input: Record<string, unknown>, context: string): { values?: string[]; error?: string } {
+	const rawValue = input.value;
+	const rawValues = input.values;
+	if (rawValue !== undefined && rawValues !== undefined) {
+		return { error: `${context}.value and ${context}.values cannot both be provided for select.` };
+	}
+	if (rawValues !== undefined) {
+		if (!Array.isArray(rawValues) || rawValues.length === 0 || rawValues.some((value) => typeof value !== "string" || value.trim().length === 0)) {
+			return { error: `${context}.values must be a non-empty array of non-empty strings for select.` };
+		}
+		return { values: rawValues };
+	}
+	if (typeof rawValue === "string" && rawValue.trim().length > 0) {
+		return { values: [rawValue] };
+	}
+	return { error: `${context}.value or ${context}.values is required for select.` };
+}
+
 function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAgentBrowserJob; error?: string } {
 	if (!isRecord(input)) {
 		return { error: "job must be an object." };
@@ -388,6 +416,12 @@ function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAgentBrows
 			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 === "select") {
+			const selector = getRequiredJobString(rawStep, "selector", jobAction);
+			if (selector.error) return { error: `job.steps[${index}]: ${selector.error}` };
+			const values = getSelectValues(rawStep, `job.steps[${index}]`);
+			if (values.error) return { error: values.error };
+			args = ["select", selector.value as string, ...(values.values as string[])];
 		} else if (jobAction === "wait") {
 			const milliseconds = rawStep.milliseconds;
 			if (typeof milliseconds !== "number" || !Number.isInteger(milliseconds) || milliseconds <= 0) {
@@ -781,9 +815,11 @@ function compileAgentBrowserNetworkSourceLookup(input: unknown): { compiled?: Co
 	if (!isRecord(input)) return { error: "networkSourceLookup must be an object." };
 	const filter = input.filter;
 	const requestId = input.requestId;
+	const session = input.session;
 	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 (session !== undefined && (typeof session !== "string" || session.trim().length === 0)) return { error: "networkSourceLookup.session 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");
@@ -796,7 +832,8 @@ function compileAgentBrowserNetworkSourceLookup(input: unknown): { compiled?: Co
 	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 } };
+	const args = typeof session === "string" ? ["--session", session, "batch"] : ["batch"];
+	return { compiled: { args, query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value as number, requestId, session, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
 }
 
 function getResultPayload(item: Record<string, unknown>): unknown {
@@ -945,7 +982,7 @@ async function analyzeNetworkSourceLookupResults(data: unknown, compiled: Compil
 }
 
 function appendSemanticActionTextArg(args: string[], action: string, text: string | undefined): void {
-	if ((action === "fill" || action === "select") && text) {
+	if (action === "fill" && text) {
 		args.push(text);
 	}
 }
@@ -955,7 +992,7 @@ function getCompiledSemanticActionCommandIndex(compiled: CompiledAgentBrowserSem
 }
 
 function getCompiledSemanticActionTextArg(compiled: CompiledAgentBrowserSemanticAction): string | undefined {
-	if (compiled.action !== "fill" && compiled.action !== "select") return undefined;
+	if (compiled.action !== "fill") return undefined;
 	const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
 	if (commandIndex < 0) return undefined;
 	const markerIndex = compiled.args.indexOf("--name");
@@ -967,6 +1004,11 @@ function getCompiledSemanticActionSessionPrefix(compiled: CompiledAgentBrowserSe
 	return commandIndex > 0 ? compiled.args.slice(0, commandIndex) : [];
 }
 
+function isCompiledSemanticActionFindCommand(compiled: CompiledAgentBrowserSemanticAction | undefined): boolean {
+	if (!compiled) return false;
+	return compiled.args[getCompiledSemanticActionCommandIndex(compiled)] === "find";
+}
+
 const SEMANTIC_ACTION_CANDIDATE_ACTION_IDS = new Set([
 	"try-searchbox-name-candidate",
 	"try-textbox-name-candidate",
@@ -986,7 +1028,7 @@ function formatSemanticActionCandidateText(actions: AgentBrowserNextAction[]): s
 
 function buildSemanticActionCandidateActions(compiled: CompiledAgentBrowserSemanticAction): AgentBrowserNextAction[] {
 	const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
-	if (commandIndex < 0) return [];
+	if (commandIndex < 0 || compiled.args[commandIndex] !== "find") return [];
 	const locator = compiled.args[commandIndex + 1];
 	const value = compiled.args[commandIndex + 2];
 	if (!locator || !value) return [];
@@ -1023,6 +1065,121 @@ function buildSemanticActionCandidateActions(compiled: CompiledAgentBrowserSeman
 	return [];
 }
 
+function isAgentBrowserSemanticActionName(value: string | undefined): value is AgentBrowserSemanticActionName {
+	return typeof value === "string" && AGENT_BROWSER_SEMANTIC_ACTIONS.includes(value as AgentBrowserSemanticActionName);
+}
+
+function getFindNameFlagValue(args: string[], startIndex: number): string | undefined {
+	const nameFlagIndex = args.indexOf("--name", startIndex);
+	const name = nameFlagIndex >= 0 ? args[nameFlagIndex + 1] : undefined;
+	return name && !name.startsWith("-") ? name : undefined;
+}
+
+function getFindVisibleRefFallbackTarget(args: string[]): VisibleRefFallbackTarget | undefined {
+	const findIndex = args[0] === "--session" ? 2 : 0;
+	if (args[findIndex] !== "find") return undefined;
+	const locator = args[findIndex + 1];
+	const value = args[findIndex + 2];
+	const action = args[findIndex + 3];
+	if (!locator || !value || !isAgentBrowserSemanticActionName(action) || action === "select") return undefined;
+	const text = action === "fill" ? args[findIndex + 4] : undefined;
+	if (action === "fill" && (!text || text.startsWith("-"))) return undefined;
+	if (locator === "role") {
+		const targetName = getFindNameFlagValue(args, findIndex + 4);
+		return targetName ? { action, roles: [value], targetName, text } : undefined;
+	}
+	if (locator === "text" && action === "click") {
+		return { action, roles: ["button", "link"], targetName: value };
+	}
+	if (locator === "label" && action === "fill") {
+		return { action, roles: ["textbox"], targetName: value, text };
+	}
+	if (locator === "placeholder" && action === "fill") {
+		return { action, roles: ["searchbox", "textbox"], targetName: value, text };
+	}
+	return undefined;
+}
+
+function getVisibleRefFallbackTarget(options: {
+	commandTokens: string[];
+	compiledSemanticAction?: CompiledAgentBrowserSemanticAction;
+}): VisibleRefFallbackTarget | undefined {
+	return getFindVisibleRefFallbackTarget(options.commandTokens) ?? (options.compiledSemanticAction ? getFindVisibleRefFallbackTarget(options.compiledSemanticAction.args) : undefined);
+}
+
+const VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT = 3;
+
+function getVisibleRefFallbackCandidates(target: VisibleRefFallbackTarget, snapshotData: unknown): VisibleRefFallbackCandidate[] {
+	const refs = getSnapshotRefRecord(snapshotData);
+	if (!refs) return [];
+	const roleOrder = target.roles.map((role) => role.toLowerCase());
+	const targetName = normalizeSemanticActionAccessibleName(target.targetName);
+	const candidates = Object.entries(refs).flatMap(([ref, entry]): VisibleRefFallbackCandidate[] => {
+		if (!/^e\d+$/.test(ref) || !isRecord(entry)) return [];
+		const role = typeof entry.role === "string" ? entry.role : undefined;
+		const name = typeof entry.name === "string" ? entry.name : undefined;
+		if (!role || !name || !roleOrder.includes(role.toLowerCase()) || normalizeSemanticActionAccessibleName(name) !== targetName) return [];
+		const args = [target.action, `@${ref}`];
+		appendSemanticActionTextArg(args, target.action, target.text);
+		return [{
+			action: target.action,
+			args,
+			name,
+			reason: `Current snapshot shows ${role} ${JSON.stringify(name)} at @${ref}, matching the failed ${target.action} locator exactly.`,
+			ref: `@${ref}`,
+			role,
+		}];
+	});
+	candidates.sort((left, right) => roleOrder.indexOf(left.role.toLowerCase()) - roleOrder.indexOf(right.role.toLowerCase()) || compareRefIds(left.ref.slice(1), right.ref.slice(1)));
+	return candidates.slice(0, VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT);
+}
+
+async function collectVisibleRefFallbackDiagnostic(options: {
+	commandTokens: string[];
+	compiledSemanticAction?: CompiledAgentBrowserSemanticAction;
+	cwd: string;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<VisibleRefFallbackDiagnostic | undefined> {
+	if (!options.sessionName) return undefined;
+	const target = getVisibleRefFallbackTarget({ commandTokens: options.commandTokens, compiledSemanticAction: options.compiledSemanticAction });
+	if (!target) return undefined;
+	const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal });
+	const snapshot = extractRefSnapshotFromData(snapshotData);
+	if (!snapshot) return undefined;
+	const candidates = getVisibleRefFallbackCandidates(target, snapshotData);
+	if (candidates.length === 0) return undefined;
+	return {
+		candidates,
+		snapshot,
+		summary: candidates.length === 1
+			? `Current snapshot has one exact visible ref match for ${target.action} ${JSON.stringify(target.targetName)}.`
+			: `Current snapshot has ${candidates.length} exact visible ref matches for ${target.action} ${JSON.stringify(target.targetName)}; choose only if the intended control is unambiguous.`,
+		target,
+	};
+}
+
+function buildVisibleRefFallbackNextActions(options: { diagnostic: VisibleRefFallbackDiagnostic; sessionName?: string }): AgentBrowserNextAction[] {
+	const ambiguous = options.diagnostic.candidates.length > 1;
+	return options.diagnostic.candidates.map((candidate, index) => ({
+		id: ambiguous ? `try-current-visible-ref-${index + 1}` : "try-current-visible-ref",
+		params: { args: sessionPrefixArgs(options.sessionName, candidate.args) },
+		reason: candidate.reason,
+		safety: ambiguous
+			? "Several current refs share the same exact role/name. Inspect the snapshot and use only the ref that clearly matches the intended target."
+			: "Use only while this current snapshot still represents the page; refresh refs first if the page changed.",
+		tool: "agent_browser" as const,
+	}));
+}
+
+function formatVisibleRefFallbackText(diagnostic: VisibleRefFallbackDiagnostic | undefined): string | undefined {
+	if (!diagnostic) return undefined;
+	return [
+		"Current snapshot ref fallback:",
+		...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role ? ` ${candidate.role}` : ""} ${JSON.stringify(candidate.name)}: ${candidate.reason}`),
+	].join("\n");
+}
+
 function normalizeSemanticActionAccessibleName(name: string): string {
 	return name.replace(/\s+/g, " ").trim().toLowerCase();
 }
@@ -1085,6 +1242,8 @@ function compileAgentBrowserSemanticAction(input: unknown): { compiled?: Compile
 	const action = input.action;
 	const locator = input.locator;
 	const value = input.value;
+	const values = input.values;
+	const selector = input.selector;
 	const text = input.text;
 	const role = input.role;
 	const name = input.name;
@@ -1092,6 +1251,27 @@ function compileAgentBrowserSemanticAction(input: unknown): { compiled?: Compile
 	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 (session !== undefined && (typeof session !== "string" || session.trim().length === 0)) {
+		return { error: "semanticAction.session must be a non-empty string when provided." };
+	}
+	if (action === "select") {
+		if (locator !== undefined || role !== undefined || name !== undefined) {
+			return { error: "semanticAction.locator, role, and name are not supported for select; use selector plus value or values." };
+		}
+		if (text !== undefined) {
+			return { error: "semanticAction.text is not supported for select; use value or values for option values." };
+		}
+		if (typeof selector !== "string" || selector.trim().length === 0) {
+			return { error: "semanticAction.selector is required for select." };
+		}
+		const selectedValues = getSelectValues(input, "semanticAction");
+		if (selectedValues.error) return { error: selectedValues.error };
+		const args = typeof session === "string" ? ["--session", session, "select", selector, ...(selectedValues.values as string[])] : ["select", selector, ...(selectedValues.values as string[])];
+		return { compiled: { action: "select", selector, values: selectedValues.values, args } };
+	}
+	if (selector !== undefined || values !== undefined) {
+		return { error: "semanticAction.selector and values are only supported for select actions." };
+	}
 	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(", ")}.` };
 	}
@@ -1101,11 +1281,11 @@ function compileAgentBrowserSemanticAction(input: unknown): { compiled?: Compile
 	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)) {
+	if (action === "fill" && (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 (action !== "fill" && text !== undefined) {
+		return { error: "semanticAction.text is only supported for fill actions." };
 	}
 	if (role !== undefined && (locator !== "role" || role !== value)) {
 		return { error: "semanticAction.role is only supported for locator=role and must match value." };
@@ -1113,11 +1293,8 @@ function compileAgentBrowserSemanticAction(input: unknown): { compiled?: Compile
 	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." };
 	}
-	if (session !== undefined && (typeof session !== "string" || session.trim().length === 0)) {
-		return { error: "semanticAction.session must be a non-empty string when provided." };
-	}
 	const args = typeof session === "string" ? ["--session", session, "find", locator, value, action] : ["find", locator, value, action];
-	if (action === "fill" || action === "select") {
+	if (action === "fill") {
 		args.push(text as string);
 	}
 	if (locator === "role" && typeof name === "string") {
@@ -1498,6 +1675,10 @@ async function isDirectAgentBrowserBashAllowed(cwd: string): Promise<boolean> {
 }
 
 const NAVIGATION_SUMMARY_COMMANDS = new Set(["back", "click", "dblclick", "forward", "reload"]);
+const NAVIGATION_SUMMARY_EVAL = `({ title: document.title, url: location.href })`;
+// These commands can expose URLs for inspected resources (request URLs, cookie/storage scope, or log sources),
+// but they do not navigate the active tab and must not poison page-scoped ref guards.
+const READ_ONLY_DIAGNOSTIC_SESSION_TARGET_COMMANDS = new Set(["console", "cookies", "errors", "network", "storage"]);
 
 interface NavigationSummary {
 	title?: string;
@@ -1518,6 +1699,34 @@ interface OverlayBlockerDiagnostic {
 	summary: string;
 }
 
+interface VisibleRefFallbackCandidate {
+	action: AgentBrowserSemanticActionName;
+	args: string[];
+	name: string;
+	reason: string;
+	ref: string;
+	role: string;
+}
+
+interface VisibleRefFallbackDiagnostic {
+	candidates: VisibleRefFallbackCandidate[];
+	snapshot: SessionRefSnapshot;
+	summary: string;
+	target: {
+		action: AgentBrowserSemanticActionName;
+		roles: string[];
+		text?: string;
+		targetName: string;
+	};
+}
+
+interface VisibleRefFallbackTarget {
+	action: AgentBrowserSemanticActionName;
+	roles: string[];
+	text?: string;
+	targetName: string;
+}
+
 interface SelectorTextVisibilityDiagnostic {
 	firstMatchVisible?: boolean;
 	firstVisibleTextPreview?: string;
@@ -1985,6 +2194,13 @@ function extractStringResultField(data: unknown, fieldName: "result" | "title" |
 	return text.length > 0 ? text : undefined;
 }
 
+function extractNavigationSummaryFromData(data: unknown): NavigationSummary | undefined {
+	const result = isRecord(data) && isRecord(data.result) ? data.result : data;
+	const title = extractStringResultField(result, "title");
+	const url = extractStringResultField(result, "url");
+	return title || url ? { title, url } : undefined;
+}
+
 const SESSION_TAB_PINNING_EXCLUDED_COMMANDS = new Set(["close", "goto", "navigate", "open", "session", "tab"]);
 const SESSION_TAB_POST_COMMAND_CORRECTION_EXCLUDED_COMMANDS = new Set(["batch", "close", "session", "tab"]);
 
@@ -2108,6 +2324,15 @@ function extractSessionTabTargetFromData(data: unknown): SessionTabTarget | unde
 	return undefined;
 }
 
+function isReadOnlyDiagnosticSessionTargetCommand(command: string | undefined, _subcommand: string | undefined): boolean {
+	return command !== undefined && READ_ONLY_DIAGNOSTIC_SESSION_TARGET_COMMANDS.has(command);
+}
+
+function extractSessionTabTargetFromCommandData(commandTokens: string[], data: unknown): SessionTabTarget | undefined {
+	const [command, subcommand] = commandTokens;
+	return isReadOnlyDiagnosticSessionTargetCommand(command, subcommand) ? undefined : extractSessionTabTargetFromData(data);
+}
+
 function extractBatchResultCommand(item: Record<string, unknown>): string[] {
 	return Array.isArray(item.command) ? item.command.filter((token): token is string => typeof token === "string") : [];
 }
@@ -2139,8 +2364,7 @@ function extractSessionTabTargetFromBatchResults(data: unknown): SessionTabTarge
 			pendingTitle = undefined;
 			continue;
 		}
-
-		const resultTarget = extractSessionTabTargetFromData(result);
+		const resultTarget = extractSessionTabTargetFromCommandData([name, subcommand].filter((token): token is string => token !== undefined), result);
 		if (resultTarget) {
 			currentTarget = resultTarget;
 		}
@@ -2149,6 +2373,40 @@ function extractSessionTabTargetFromBatchResults(data: unknown): SessionTabTarge
 	return currentTarget;
 }
 
+function batchContainsOnlyReadOnlyDiagnosticTargets(data: unknown): boolean {
+	if (!Array.isArray(data) || data.length === 0) {
+		return false;
+	}
+	return data.every((item) => {
+		if (!isRecord(item)) return false;
+		const [command, subcommand] = extractBatchResultCommand(item);
+		return isReadOnlyDiagnosticSessionTargetCommand(command, subcommand);
+	});
+}
+
+function getRestoredSessionTabTarget(details: Record<string, unknown>, command: string | undefined, subcommand: string | undefined): SessionTabTarget | undefined {
+	if (isReadOnlyDiagnosticSessionTargetCommand(command, subcommand)) {
+		return undefined;
+	}
+	const storedTarget = isRecord(details.sessionTabTarget)
+		? normalizeSessionTabTarget({
+				title: typeof details.sessionTabTarget.title === "string" ? details.sessionTabTarget.title : undefined,
+				url: typeof details.sessionTabTarget.url === "string" ? details.sessionTabTarget.url : undefined,
+		  })
+		: undefined;
+	if (command !== "batch") {
+		return storedTarget;
+	}
+	const batchTarget = extractSessionTabTargetFromBatchResults(details.data);
+	if (batchTarget) {
+		return batchTarget;
+	}
+	if (isRecord(details.compiledNetworkSourceLookup) || batchContainsOnlyReadOnlyDiagnosticTargets(details.data)) {
+		return undefined;
+	}
+	return storedTarget;
+}
+
 function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, OrderedSessionTabTarget> {
 	const restoredTargets = new Map<string, OrderedSessionTabTarget>();
 	let restoredOrder = 0;
@@ -2169,17 +2427,13 @@ function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, Orde
 			continue;
 		}
 		const command = typeof details.command === "string" ? details.command : undefined;
+		const subcommand = typeof details.subcommand === "string" ? details.subcommand : undefined;
 		if (command === "close" && message.isError !== true) {
 			restoredOrder += 1;
 			restoredTargets.delete(sessionName);
 			continue;
 		}
-		const sessionTabTarget = isRecord(details.sessionTabTarget)
-			? normalizeSessionTabTarget({
-					title: typeof details.sessionTabTarget.title === "string" ? details.sessionTabTarget.title : undefined,
-					url: typeof details.sessionTabTarget.url === "string" ? details.sessionTabTarget.url : undefined,
-			  })
-			: undefined;
+		const sessionTabTarget = getRestoredSessionTabTarget(details, command, subcommand);
 		if (sessionTabTarget) {
 			restoredOrder += 1;
 			restoredTargets.set(sessionName, { order: restoredOrder, target: sessionTabTarget });
@@ -2334,10 +2588,12 @@ function supportsPinnedStdinCommand(options: { command?: string; commandTokens:
 function shouldPinSessionTabForCommand(options: {
 	command?: string;
 	commandTokens: string[];
+	pinningRequired?: boolean;
 	sessionName?: string;
 	stdin?: string;
 }): boolean {
 	return (
+		options.pinningRequired === true &&
 		options.sessionName !== undefined &&
 		options.command !== undefined &&
 		!SESSION_TAB_PINNING_EXCLUDED_COMMANDS.has(options.command) &&
@@ -2403,7 +2659,6 @@ const REF_INVALIDATING_BATCH_COMMANDS = new Set([
 	"click",
 	"dblclick",
 	"drag",
-	"fill",
 	"forward",
 	"goto",
 	"keyboard",
@@ -2567,7 +2822,7 @@ function buildPinnedBatchPlan(options: {
 	const includeNavigationSummary = options.command !== undefined && NAVIGATION_SUMMARY_COMMANDS.has(options.command);
 	const tabSelectionStep: BatchCommandStep = ["tab", options.selectedTab];
 	const commandStep = options.commandTokens as BatchCommandStep;
-	const navigationSummarySteps: BatchCommandStep[] = includeNavigationSummary ? [["get", "title"], ["get", "url"]] : [];
+	const navigationSummarySteps: BatchCommandStep[] = includeNavigationSummary ? [["eval", NAVIGATION_SUMMARY_EVAL]] : [];
 	return {
 		includeNavigationSummary,
 		steps: [tabSelectionStep, commandStep, ...navigationSummarySteps],
@@ -2575,8 +2830,9 @@ function buildPinnedBatchPlan(options: {
 	};
 }
 
-function shouldCorrectSessionTabAfterCommand(options: { command?: string; sessionName?: string }): boolean {
+function shouldCorrectSessionTabAfterCommand(options: { command?: string; pinningRequired?: boolean; sessionName?: string }): boolean {
 	return (
+		options.pinningRequired === true &&
 		options.sessionName !== undefined &&
 		options.command !== undefined &&
 		!SESSION_TAB_POST_COMMAND_CORRECTION_EXCLUDED_COMMANDS.has(options.command)
@@ -2599,14 +2855,18 @@ function deriveSessionTabTarget(options: {
 	data: unknown;
 	navigationSummary?: NavigationSummary;
 	previousTarget?: SessionTabTarget;
+	subcommand?: string;
 }): SessionTabTarget | undefined {
 	if (options.command === "close") {
 		return undefined;
 	}
+	const commandDataTarget = isReadOnlyDiagnosticSessionTargetCommand(options.command, options.subcommand)
+		? undefined
+		: extractSessionTabTargetFromData(options.data);
 	return (
 		normalizeSessionTabTarget(options.navigationSummary) ??
 		extractSessionTabTargetFromBatchResults(options.data) ??
-		extractSessionTabTargetFromData(options.data) ??
+		commandDataTarget ??
 		options.previousTarget
 	);
 }
@@ -2655,12 +2915,8 @@ function unwrapPinnedSessionBatchEnvelope(options: {
 		};
 	}
 
-	const titleStep = options.includeNavigationSummary ? steps[2] : undefined;
-	const urlStep = options.includeNavigationSummary ? steps[3] : undefined;
-	const navigationSummary = normalizeSessionTabTarget({
-		title: extractStringResultField(titleStep?.result, "title"),
-		url: extractStringResultField(urlStep?.result, "url"),
-	});
+	const navigationSummaryStep = options.includeNavigationSummary ? steps[2] : undefined;
+	const navigationSummary = normalizeSessionTabTarget(extractNavigationSummaryFromData(navigationSummaryStep?.result));
 	return {
 		envelope: {
 			success: commandStep.success !== false,
@@ -2711,17 +2967,13 @@ async function collectNavigationSummary(options: {
 	sessionName?: string;
 	signal?: AbortSignal;
 }): Promise<NavigationSummary | undefined> {
-	const { cwd, sessionName, signal } = options;
-	const title = extractStringResultField(
-		await runSessionCommandData({ args: ["get", "title"], cwd, sessionName, signal }),
-		"title",
-	);
-	const url = extractStringResultField(
-		await runSessionCommandData({ args: ["get", "url"], cwd, sessionName, signal }),
-		"url",
-	);
-	if (!title && !url) return undefined;
-	return { title, url };
+	return extractNavigationSummaryFromData(await runSessionCommandData({
+		args: ["eval", "--stdin"],
+		cwd: options.cwd,
+		sessionName: options.sessionName,
+		signal: options.signal,
+		stdin: NAVIGATION_SUMMARY_EVAL,
+	}));
 }
 
 function extractScrollPositionSnapshot(data: unknown): ScrollPositionSnapshot | undefined {
@@ -2914,7 +3166,7 @@ function isComboboxFocusDiagnosticCommand(command: string | undefined, commandTo
 	const explicitlyTargetsCombobox = commandTokens.some((token) => /^(?:combobox|listbox)$/i.test(token));
 	if (!explicitlyTargetsCombobox) return false;
 	if (command === "click" || command === "fill") return true;
-	return command === "find" && commandTokens.some((token) => ["click", "fill", "select"].includes(token));
+	return command === "find" && commandTokens.some((token) => ["click", "fill"].includes(token));
 }
 
 function getCompiledSemanticActionRoleValue(compiled: CompiledAgentBrowserSemanticAction): string | undefined {
@@ -2925,7 +3177,7 @@ function getCompiledSemanticActionRoleValue(compiled: CompiledAgentBrowserSemant
 }
 
 function isComboboxFocusDiagnosticSemanticAction(compiled: CompiledAgentBrowserSemanticAction | undefined): boolean {
-	if (!compiled || !["click", "fill", "select"].includes(compiled.action)) return false;
+	if (!compiled || !["click", "fill"].includes(compiled.action)) return false;
 	return /^(?:combobox|listbox)$/i.test(getCompiledSemanticActionRoleValue(compiled) ?? "");
 }
 
@@ -3209,14 +3461,16 @@ function looksLikeFunctionEvalStdin(stdin: string | undefined): boolean {
 	return /^(?:async\s+)?function\b/.test(trimmed) || /^(?:async\s*)?\([^)]*\)\s*=>/.test(trimmed) || /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed);
 }
 
-function isEmptyRecord(value: unknown): boolean {
-	return isRecord(value) && Object.keys(value).length === 0;
+function isPlainEmptyObject(value: unknown): boolean {
+	if (!isRecord(value) || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return (prototype === Object.prototype || prototype === null) && Object.keys(value).length === 0;
 }
 
 function getEvalStdinHint(options: { command?: string; data: unknown; stdin?: string }): EvalStdinHint | undefined {
 	if (options.command !== "eval" || !looksLikeFunctionEvalStdin(options.stdin) || !isRecord(options.data)) return undefined;
 	const result = options.data.result;
-	if (!isEmptyRecord(result)) return undefined;
+	if (!isPlainEmptyObject(result)) return undefined;
 	return {
 		reason: "eval --stdin received a function-shaped snippet and the upstream JSON result was an empty object, which often means the function itself was returned or serialized instead of invoked.",
 		suggestion: "Pass a plain expression such as `({ title: document.title })`, or invoke the function explicitly, for example `(() => ({ title: document.title }))()`.",
@@ -3733,6 +3987,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	let freshSessionOrdinal = 0;
 	let sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
 	let sessionRefSnapshots = new Map<string, OrderedSessionRefSnapshot>();
+	let sessionTabPinningReasons = new Map<string, "drift" | "restore">();
 	let sessionTabTargetUpdateOrder = 0;
 	let traceOwners = new Map<string, TraceOwner>();
 	let artifactManifest: SessionArtifactManifest | undefined;
@@ -3747,6 +4002,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		freshSessionOrdinal = restoredState.freshSessionOrdinal;
 		sessionTabTargets = restoreSessionTabTargetsFromBranch(ctx.sessionManager.getBranch());
 		sessionRefSnapshots = restoreSessionRefSnapshotsFromBranch(ctx.sessionManager.getBranch());
+		sessionTabPinningReasons = new Map([...sessionTabTargets.keys()].map((sessionName) => [sessionName, "restore"]));
 		sessionTabTargetUpdateOrder = Math.max(getLatestSessionTabTargetOrder(sessionTabTargets), getLatestSessionTabTargetOrder(sessionRefSnapshots));
 		artifactManifest = restoreArtifactManifestFromBranch(ctx.sessionManager.getBranch());
 	});
@@ -3765,6 +4021,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		managedSessionActive = false;
 		sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
 		sessionRefSnapshots = new Map<string, OrderedSessionRefSnapshot>();
+		sessionTabPinningReasons = new Map<string, "drift" | "restore">();
 		sessionTabTargetUpdateOrder = 0;
 		traceOwners = new Map<string, TraceOwner>();
 		artifactManifest = undefined;
@@ -3862,6 +4119,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			const redactedCompiledNetworkSourceLookup = compiledNetworkSourceLookup && redactedCompiledNetworkSourceLookupSteps
 				? {
 					...compiledNetworkSourceLookup,
+					args: redactNetworkSourceLookupArgs(compiledNetworkSourceLookup.args),
 					query: {
 						...compiledNetworkSourceLookup.query,
 						filter: redactNetworkSourceLookupUrl(compiledNetworkSourceLookup.query.filter),
@@ -4013,6 +4271,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
 				const priorSessionTabTargetState = executionPlan.sessionName ? sessionTabTargets.get(executionPlan.sessionName) : undefined;
 				const priorSessionTabTarget = priorSessionTabTargetState?.target;
+				const sessionTabPinningReason = executionPlan.sessionName ? sessionTabPinningReasons.get(executionPlan.sessionName) : undefined;
 				const priorRefSnapshotState = executionPlan.sessionName ? sessionRefSnapshots.get(executionPlan.sessionName) : undefined;
 				const resolvedSemanticActionRefSnapshot = semanticActionVisibleRefResolution?.snapshot
 					? { ...semanticActionVisibleRefResolution.snapshot, target: semanticActionVisibleRefResolution.snapshot.target ?? priorSessionTabTarget }
@@ -4051,6 +4310,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					shouldPinSessionTabForCommand({
 						command: executionPlan.commandInfo.command,
 						commandTokens,
+						pinningRequired: sessionTabPinningReason !== undefined,
 						sessionName: executionPlan.sessionName,
 						stdin: toolStdin,
 					})
@@ -4286,12 +4546,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					const observedSessionTabTarget =
 						normalizeSessionTabTarget(navigationSummary) ??
 						extractSessionTabTargetFromBatchResults(presentationEnvelope?.data) ??
-						extractSessionTabTargetFromData(presentationEnvelope?.data);
+						extractSessionTabTargetFromCommandData(commandTokens, presentationEnvelope?.data);
 					let currentSessionTabTarget = deriveSessionTabTarget({
 						command: executionPlan.commandInfo.command,
 						data: presentationEnvelope?.data,
 						navigationSummary,
 						previousTarget: priorSessionTabTarget,
+						subcommand: executionPlan.commandInfo.subcommand,
 					});
 					let aboutBlankSessionMismatch: AboutBlankSessionMismatch | undefined;
 					const shouldTreatAboutBlankAsMismatch =
@@ -4336,6 +4597,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						observedSessionTabTarget &&
 						shouldCorrectSessionTabAfterCommand({
 							command: executionPlan.commandInfo.command,
+							pinningRequired: sessionTabPinningReason !== undefined,
 							sessionName: executionPlan.sessionName,
 						})
 					) {
@@ -4418,9 +4680,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							if (executionPlan.commandInfo.command === "close" && succeeded) {
 								sessionTabTargets.delete(executionPlan.sessionName);
 								sessionRefSnapshots.delete(executionPlan.sessionName);
+								sessionTabPinningReasons.delete(executionPlan.sessionName);
 							} else if (currentSessionTabTarget) {
 								sessionTabTargets.set(executionPlan.sessionName, { order: tabTargetUpdateOrder, target: currentSessionTabTarget });
 							}
+						} else if (succeeded && currentSessionTabTarget) {
+							// A stale overlapping command may have moved browser focus even though its older target
+							// must not replace the newer logical target. Require tab pinning on the next call.
+							sessionTabPinningReasons.set(executionPlan.sessionName, "drift");
 						}
 						const refSnapshot = succeeded
 			? executionPlan.commandInfo.command === "snapshot"
@@ -4464,9 +4731,18 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					if (executionPlan.managedSessionName && succeeded) {
 						managedSessionCwd = ctx.cwd;
 					}
+					if (executionPlan.sessionName && succeeded) {
+						if (openResultTabCorrection || sessionTabCorrection || aboutBlankSessionMismatch?.recoveryApplied) {
+							sessionTabPinningReasons.set(executionPlan.sessionName, "drift");
+						} else if (sessionTabPinningReason === "restore") {
+							sessionTabPinningReasons.delete(executionPlan.sessionName);
+						}
+					}
+
 					if (replacedManagedSessionName) {
 						sessionTabTargets.delete(replacedManagedSessionName);
 						sessionRefSnapshots.delete(replacedManagedSessionName);
+						sessionTabPinningReasons.delete(replacedManagedSessionName);
 						await closeManagedSession({
 							cwd: priorManagedSessionCwd,
 							sessionName: replacedManagedSessionName,
@@ -4622,10 +4898,28 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						timedOut: processResult.timedOut,
 						validationError: undefined,
 					});
+					let visibleRefFallbackDiagnostic: VisibleRefFallbackDiagnostic | undefined;
+					const visibleRefFallbackSessionName = executionPlan.sessionName ?? extractExplicitSessionName(toolArgs);
+					if (categoryDetails.failureCategory === "selector-not-found") {
+						visibleRefFallbackDiagnostic = await collectVisibleRefFallbackDiagnostic({
+							commandTokens,
+							compiledSemanticAction,
+							cwd: ctx.cwd,
+							sessionName: visibleRefFallbackSessionName,
+							signal,
+						});
+						if (visibleRefFallbackDiagnostic && visibleRefFallbackSessionName && shouldApplySessionTabTargetUpdate({ current: sessionRefSnapshots.get(visibleRefFallbackSessionName), updateOrder: tabTargetUpdateOrder })) {
+							currentRefSnapshot = { ...visibleRefFallbackDiagnostic.snapshot, target: visibleRefFallbackDiagnostic.snapshot.target ?? currentSessionTabTarget };
+							sessionRefSnapshots.set(visibleRefFallbackSessionName, { ...currentRefSnapshot, order: tabTargetUpdateOrder });
+						}
+					}
 					let nextActions = presentation.nextActions ? [...presentation.nextActions] : undefined;
 					if (categoryDetails.failureCategory === "stale-ref") {
 						nextActions = sessionAwareStaleRefNextActions(executionPlan.sessionName);
 					}
+					if (visibleRefFallbackDiagnostic) {
+						(nextActions ??= []).push(...buildVisibleRefFallbackNextActions({ diagnostic: visibleRefFallbackDiagnostic, sessionName: visibleRefFallbackSessionName }));
+					}
 					if (categoryDetails.failureCategory === "selector-not-found" && redactedCompiledSemanticAction) {
 						const candidateActions = buildSemanticActionCandidateActions(redactedCompiledSemanticAction);
 						if (candidateActions.length > 0) {
@@ -4644,7 +4938,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					if (comboboxFocusDiagnostic) {
 						(nextActions ??= []).push(...buildComboboxFocusNextActions(executionPlan.sessionName));
 					}
-					if (categoryDetails.failureCategory === "stale-ref" && redactedCompiledSemanticAction) {
+					if (categoryDetails.failureCategory === "stale-ref" && redactedCompiledSemanticAction && isCompiledSemanticActionFindCommand(compiledSemanticAction)) {
 						(nextActions ??= []).push({
 							id: "retry-semantic-action-after-stale-ref",
 							params: { args: redactedCompiledSemanticAction.args },
@@ -4691,6 +4985,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						nextActions,
 						pageChangeSummary,
 						overlayBlockers: overlayBlockerDiagnostic,
+						visibleRefFallback: visibleRefFallbackDiagnostic,
 						comboboxFocus: comboboxFocusDiagnostic,
 						recordingDependencyWarning,
 						scrollNoop: scrollNoopDiagnostic,
@@ -4718,6 +5013,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						timeoutMs: processResult.timeoutMs,
 					};
 
+					const visibleRefFallbackText = formatVisibleRefFallbackText(visibleRefFallbackDiagnostic);
 					const semanticActionCandidateText = nextActions ? formatSemanticActionCandidateText(nextActions) : undefined;
 					const overlayBlockerText = overlayBlockerDiagnostic ? formatOverlayBlockerText(overlayBlockerDiagnostic) : undefined;
 					const selectorTextVisibilityText = formatSelectorTextVisibilityText(selectorTextVisibilityDiagnostics);
@@ -4728,7 +5024,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					const artifactCleanupText = formatArtifactCleanupGuidanceText(artifactCleanup);
 					const timeoutPartialProgressText = timeoutPartialProgress ? formatTimeoutPartialProgressText(timeoutPartialProgress) : undefined;
 					const managedSessionOutcomeText = formatManagedSessionOutcomeText(managedSessionOutcome);
-					const rawAppendedDiagnosticText = [semanticActionCandidateText, overlayBlockerText, selectorTextVisibilityText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
+					const rawAppendedDiagnosticText = [visibleRefFallbackText, semanticActionCandidateText, overlayBlockerText, selectorTextVisibilityText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
 					const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, exactSensitiveValues));
 					const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!userRequestedJson || plainTextInspection);
 					const content = shouldAppendDiagnosticText && redactedContent[0]?.type === "text"