pi-agent-browser-native 0.2.34 → 0.2.35

package/extensions/agent-browser/lib/input-modes/params.ts

@@ -45,7 +45,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			role: Type.Optional(Type.String({ description: "Role locator value for locator=role. May be used instead of value; when both are set they must match." })),
 			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 command." })),
-		}),
+		}, { additionalProperties: false }),
 	),
 	qa: Type.Optional(
 		Type.Union([
@@ -79,7 +79,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			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 })),
-		}, { description: "EXPERIMENTAL: local UI-to-source candidates only (confidence/evidence, not guaranteed mappings). Compiles to batch; mutually exclusive with other input modes." }),
+		}, { additionalProperties: false, description: "EXPERIMENTAL: local UI-to-source candidates only (confidence/evidence, not guaranteed mappings). Compiles to batch; mutually exclusive with other input modes." }),
 	),
 	networkSourceLookup: Type.Optional(
 		Type.Object({
@@ -88,7 +88,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			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 })),
-		}, { description: "EXPERIMENTAL: failed-request-to-source candidates only (initiator metadata and bounded workspace URL literals; not definitive blame). Compiles to batch; mutually exclusive with other input modes." }),
+		}, { additionalProperties: false, description: "EXPERIMENTAL: failed-request-to-source candidates only (initiator metadata and bounded workspace URL literals; not definitive blame). Compiles to batch; mutually exclusive with other input modes." }),
 	),
 	electron: Type.Optional(
 		Type.Union([
@@ -172,10 +172,10 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 					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." })),
-				}),
+				}, { additionalProperties: false }),
 				{ minItems: 1 },
 			),
-		}),
+		}, { additionalProperties: false }),
 	),
 	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. Do not use with electron mode." })),
 	sessionMode: Type.Optional(
@@ -185,4 +185,4 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),
-});
+}, { additionalProperties: false });

package/extensions/agent-browser/lib/orchestration/batch-stdin.ts

@@ -0,0 +1,65 @@
+export type BatchCommandStep = [string, ...string[]];
+
+function validateUserBatchStep(step: unknown, index: number): { error: string; ok: false } | { ok: true; step: BatchCommandStep } {
+	if (!Array.isArray(step)) {
+		return {
+			error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.`,
+			ok: false,
+		};
+	}
+	if (step.length === 0) {
+		return {
+			error: `agent_browser batch stdin step ${index} must not be empty.`,
+			ok: false,
+		};
+	}
+	const invalidTokenIndex = step.findIndex((token) => typeof token !== "string");
+	if (invalidTokenIndex !== -1) {
+		return {
+			error: `agent_browser batch stdin step ${index} token ${invalidTokenIndex} must be a string.`,
+			ok: false,
+		};
+	}
+	return { ok: true, step: step as BatchCommandStep };
+}
+
+export function parseBatchStdinJsonArray(stdin: string | undefined): { error?: string; steps?: unknown[] } {
+	if (stdin === undefined) {
+		return { steps: [] };
+	}
+	try {
+		const parsed = JSON.parse(stdin) as unknown;
+		if (!Array.isArray(parsed)) {
+			return { error: "agent_browser batch stdin must be a JSON array of command steps." };
+		}
+		return { steps: parsed };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { error: `agent_browser batch stdin could not be parsed as JSON: ${message}` };
+	}
+}
+
+export function parseUserBatchStdin(stdin: string | undefined): { error?: string; steps?: BatchCommandStep[] } {
+	const parsed = parseBatchStdinJsonArray(stdin);
+	if (parsed.error || parsed.steps === undefined) {
+		return parsed.error ? { error: parsed.error } : { steps: [] };
+	}
+	const steps: BatchCommandStep[] = [];
+	for (const [index, rawStep] of parsed.steps.entries()) {
+		const validated = validateUserBatchStep(rawStep, index);
+		if (!validated.ok) {
+			return { error: validated.error };
+		}
+		steps.push(validated.step);
+	}
+	return { steps };
+}
+
+export function parseValidBatchStepEntries(stdin: string | undefined): Array<{ index: number; step: BatchCommandStep }> {
+	const parsed = parseBatchStdinJsonArray(stdin);
+	if (parsed.error || parsed.steps === undefined) return [];
+	return parsed.steps.flatMap((step, index) => {
+		const validated = validateUserBatchStep(step, index);
+		return validated.ok ? [{ index, step: validated.step }] : [];
+	});
+}

package/extensions/agent-browser/lib/orchestration/browser-run/browser-action-model.ts

@@ -0,0 +1,154 @@
+/**
+ * Purpose: Normalize planned browser argv into a small action model for prompt-derived guards.
+ * Responsibilities: Map command tokens and batch stdin steps to click-like and keyboard-submit actions with target labels.
+ * Scope: Best-effort finalizing-action detection only; does not model eval, generic fill/type, or non-Enter keyboard flows.
+ */
+
+import type { SessionRefSnapshot } from "../../session-page-state.js";
+import { parseValidBatchStepEntries } from "../batch-stdin.js";
+
+const FINAL_ACTION_PATTERN = /\b(?:finish|place\s+(?:the\s+)?order|submit\s+(?:the\s+)?order|complete\s+(?:the\s+)?order|confirm\s+(?:the\s+)?order|purchase|buy\s+now|pay\s+now|finali[sz]e|submit\s+payment|checkout\s+complete)\b/i;
+
+const CLICK_LIKE_COMMANDS = new Set(["click", "dblclick", "tap"]);
+const FIND_CLICK_ACTIONS = new Set(["click", "dblclick", "tap"]);
+const KEYBOARD_SUBMIT_KEYS = new Set(["enter", "return"]);
+
+export type BrowserFinalizingActionKind = "click-like" | "keyboard-submit";
+
+export interface BrowserFinalizingAction {
+	command: string[];
+	kind: BrowserFinalizingActionKind;
+	stepIndex?: number;
+	targetLabel?: string;
+}
+
+export const STOP_BOUNDARY_GUARD_SCOPE = {
+	covered: [
+		"standalone click, dblclick, and tap",
+		"find … click|dblclick|tap",
+		"batch steps with the click-like shapes above",
+		"press <key> and key <key> when key is Enter or Return",
+	],
+	excluded: [
+		"eval --stdin and other scripted activation",
+		"fill, type, select, drag, and upload without an explicit click-like command",
+		"keyboard type/inserttext and keyboard shortcuts other than Enter/Return",
+		"semanticAction and job/qa compiled plans unless their batch stdin contains a covered step",
+	],
+} as const;
+
+function normalizeTargetText(value: string): string {
+	return value
+		.replace(/[_-]+/g, " ")
+		.replace(/[\[\]{}()#.'\"=:/]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function matchesFinalActionLabel(value: string | undefined): boolean {
+	return value !== undefined && FINAL_ACTION_PATTERN.test(normalizeTargetText(value));
+}
+
+function parseRefId(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	const candidate = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+	return /^e\d+$/.test(candidate) ? candidate : undefined;
+}
+
+function getRefTargetLabel(refSnapshot: SessionRefSnapshot | undefined, refId: string | undefined): string | undefined {
+	if (!refId) return undefined;
+	const ref = refSnapshot?.refs?.[refId];
+	return ref ? [ref.role, ref.name].filter(Boolean).join(" ") : undefined;
+}
+
+function getFlagValue(tokens: string[], flag: string): string | undefined {
+	for (const [index, token] of tokens.entries()) {
+		if (token === flag) return tokens[index + 1];
+		if (token.startsWith(`${flag}=`)) return token.slice(flag.length + 1);
+	}
+	return undefined;
+}
+
+function getClickLikeTargetLabel(command: string[], refSnapshot: SessionRefSnapshot | undefined): string | undefined {
+	const target = command[1];
+	return getRefTargetLabel(refSnapshot, parseRefId(target)) ?? target;
+}
+
+function getFindClickTargetLabel(command: string[]): string | undefined {
+	if (command[0] !== "find") return undefined;
+	const actionIndex = command.findIndex((token, index) => index >= 3 && FIND_CLICK_ACTIONS.has(token));
+	if (actionIndex === -1) return undefined;
+	return getFlagValue(command, "--name") ?? command[2];
+}
+
+function getKeyboardSubmitKey(command: string[]): string | undefined {
+	const commandName = command[0];
+	if (commandName === "press" || commandName === "key") return command[1];
+	return undefined;
+}
+
+function collectActionsFromCommand(command: string[], refSnapshot: SessionRefSnapshot | undefined, stepIndex?: number): BrowserFinalizingAction[] {
+	const actions: BrowserFinalizingAction[] = [];
+	if (CLICK_LIKE_COMMANDS.has(command[0] ?? "")) {
+		actions.push({
+			command,
+			kind: "click-like",
+			stepIndex,
+			targetLabel: getClickLikeTargetLabel(command, refSnapshot),
+		});
+		return actions;
+	}
+	if (command[0] === "find") {
+		const actionIndex = command.findIndex((token, index) => index >= 3 && FIND_CLICK_ACTIONS.has(token));
+		if (actionIndex !== -1) {
+			actions.push({
+				command,
+				kind: "click-like",
+				stepIndex,
+				targetLabel: getFindClickTargetLabel(command),
+			});
+		}
+		return actions;
+	}
+	const submitKey = getKeyboardSubmitKey(command)?.trim().toLowerCase();
+	if (submitKey && KEYBOARD_SUBMIT_KEYS.has(submitKey)) {
+		actions.push({
+			command,
+			kind: "keyboard-submit",
+			stepIndex,
+			targetLabel: submitKey,
+		});
+	}
+	return actions;
+}
+
+export function collectBrowserFinalizingActions(options: {
+	commandTokens: string[];
+	refSnapshot?: SessionRefSnapshot;
+	stdin?: string;
+}): BrowserFinalizingAction[] {
+	const actions = collectActionsFromCommand(options.commandTokens, options.refSnapshot);
+	if (options.commandTokens[0] !== "batch") return actions;
+	for (const { index, step } of parseValidBatchStepEntries(options.stdin)) {
+		actions.push(...collectActionsFromCommand(step, options.refSnapshot, index));
+	}
+	return actions;
+}
+
+export function shouldBlockFinalizingAction(action: BrowserFinalizingAction): boolean {
+	if (action.kind === "keyboard-submit") return true;
+	return matchesFinalActionLabel(action.targetLabel);
+}
+
+export function findBlockedFinalizingAction(options: {
+	commandTokens: string[];
+	refSnapshot?: SessionRefSnapshot;
+	stdin?: string;
+}): BrowserFinalizingAction | undefined {
+	for (const action of collectBrowserFinalizingActions(options)) {
+		if (!shouldBlockFinalizingAction(action)) continue;
+		return action;
+	}
+	return undefined;
+}

package/extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts

@@ -0,0 +1,149 @@
+import { isRecord } from "../../parsing.js";
+import { redactSensitiveText } from "../../runtime.js";
+import { withOptionalSessionArgs, type AgentBrowserNextAction } from "../../results/next-actions.js";
+import { runSessionCommandData } from "./session-state.js";
+import type { ClickDispatchDiagnostic, ClickDispatchProbe, ClickDispatchProbeTarget } from "./types.js";
+
+const CLICK_DISPATCH_MARKER_PREFIX = "__piAgentBrowserClickDispatchProbe_";
+const CLICK_DISPATCH_CLEANUP_TIMEOUT_MS = 2_000;
+
+function parseClickRefId(selector: string): string | undefined {
+	const trimmed = selector.trim();
+	const candidate = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+	return /^e\d+$/.test(candidate) ? candidate : undefined;
+}
+
+function getClickDispatchSelectorTarget(commandTokens: string[]): ClickDispatchProbeTarget | undefined {
+	if (commandTokens[0] !== "click" || commandTokens.includes("--new-tab")) return undefined;
+	const selector = commandTokens[1];
+	if (!selector || selector.startsWith("-")) return undefined;
+	if (parseClickRefId(selector)) return undefined;
+	if (selector.startsWith("xpath=")) return { kind: "xpath", selector: selector.slice("xpath=".length) };
+	return { kind: "selector", selector };
+}
+
+function getEvalResultRecord(data: unknown): Record<string, unknown> | undefined {
+	return isRecord(data) && isRecord(data.result) ? data.result : undefined;
+}
+
+function buildClickDispatchProbeInstallScript(probe: ClickDispatchProbe): string {
+	const target = probe.target;
+	const resolveTarget = target.kind === "selector"
+		? `(() => { try { return document.querySelector(${JSON.stringify(target.selector)}); } catch { return null; } })()`
+		: `(() => { try { return document.evaluate(${JSON.stringify(target.selector)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue; } catch { return null; } })()`;
+	return `(() => {
+const marker = ${JSON.stringify(probe.marker)};
+const element = ${resolveTarget};
+if (!element) return { status: "target-not-found", marker };
+const state = { events: [], target: { tagName: element.tagName.toLowerCase() } };
+const eventTypes = ["pointerdown", "mousedown", "pointerup", "mouseup", "click"];
+const listeners = eventTypes.map((type) => {
+  const listener = (event) => {
+    const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+    const eventTarget = event.target;
+    const targetMatched = path.includes(element) || eventTarget === element || (eventTarget instanceof Node && element.contains(eventTarget));
+    state.events.push({ type: event.type, isTrusted: event.isTrusted === true, targetMatched });
+  };
+  document.addEventListener(type, listener, true);
+  return [type, listener];
+});
+state.cleanup = () => listeners.forEach(([type, listener]) => document.removeEventListener(type, listener, true));
+window[marker] = state;
+return { status: "installed", marker, target: state.target };
+})()`;
+}
+
+function buildClickDispatchProbeCheckScript(probe: ClickDispatchProbe): string {
+	return `(() => {
+const marker = ${JSON.stringify(probe.marker)};
+const state = window[marker];
+const finish = (payload) => {
+  if (state && typeof state.cleanup === "function") state.cleanup();
+  try { delete window[marker]; } catch {}
+  return payload;
+};
+if (!state || !Array.isArray(state.events)) return finish({ status: "probe-missing", nativeEventCount: 0 });
+const nativeEventCount = state.events.filter((event) => event && event.isTrusted === true && event.targetMatched === true).length;
+if (nativeEventCount > 0) return finish({ status: "native-event-observed", nativeEventCount, target: state.target });
+return finish({ status: "no-native-event-observed", nativeEventCount, target: state.target });
+})()`;
+}
+
+function buildClickDispatchProbeCleanupScript(probe: ClickDispatchProbe): string {
+	return `(() => {
+const marker = ${JSON.stringify(probe.marker)};
+const state = window[marker];
+if (state && typeof state.cleanup === "function") state.cleanup();
+try { delete window[marker]; } catch {}
+return { status: "cleaned-up" };
+})()`;
+}
+
+function redactClickDispatchTarget(target: ClickDispatchProbeTarget): ClickDispatchProbeTarget {
+	return target.kind === "selector" || target.kind === "xpath"
+		? { ...target, selector: redactSensitiveText(target.selector) }
+		: target;
+}
+
+export function formatClickDispatchDiagnosticText(diagnostic: ClickDispatchDiagnostic): string {
+	return `Click dispatch diagnostic: ${diagnostic.summary}`;
+}
+
+export function buildClickDispatchNextActions(options: { commandTokens: string[]; sessionName?: string }): AgentBrowserNextAction[] {
+	const retryArgs = options.commandTokens[0] === "click" ? options.commandTokens : ["click", ...options.commandTokens];
+	return [
+		{
+			id: "inspect-click-dispatch-miss",
+			params: { args: withOptionalSessionArgs(options.sessionName, ["snapshot", "-i"]) },
+			reason: "Refresh interactive refs and verify the intended click target before retrying upstream click.",
+			safety: "Read-only snapshot; the wrapper does not replay clicks in-page when upstream reports success without DOM events.",
+			tool: "agent_browser",
+		},
+		{
+			id: "retry-click-after-dispatch-miss",
+			params: { args: withOptionalSessionArgs(options.sessionName, retryArgs) },
+			reason: "Retry the same upstream click after confirming the target is visible; do not assume the prior success mutated the page.",
+			safety: "Only retry when the target is still intended; use page-change evidence or a fresh snapshot before continuing the workflow.",
+			tool: "agent_browser",
+		},
+	];
+}
+
+export async function prepareClickDispatchProbe(options: { commandTokens: string[]; cwd: string; sessionName?: string; signal?: AbortSignal }): Promise<ClickDispatchProbe | undefined> {
+	if (!options.sessionName || options.commandTokens[0] !== "click" || options.commandTokens.includes("--new-tab")) return undefined;
+	const target = getClickDispatchSelectorTarget(options.commandTokens);
+	if (!target) return undefined;
+	const probe: ClickDispatchProbe = { marker: `${CLICK_DISPATCH_MARKER_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`, target };
+	const installData = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: buildClickDispatchProbeInstallScript(probe) });
+	const installResult = getEvalResultRecord(installData);
+	return installResult?.status === "installed" ? probe : undefined;
+}
+
+export async function collectClickDispatchDiagnostic(options: { cwd: string; probe?: ClickDispatchProbe; sessionName?: string; signal?: AbortSignal }): Promise<ClickDispatchDiagnostic | undefined> {
+	if (!options.probe || !options.sessionName) return undefined;
+	const data = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: buildClickDispatchProbeCheckScript(options.probe) });
+	const result = getEvalResultRecord(data);
+	if (!result) return undefined;
+	const status = typeof result.status === "string" ? result.status : undefined;
+	if (status !== "no-native-event-observed") return undefined;
+	const nativeEventCount = typeof result.nativeEventCount === "number" ? result.nativeEventCount : 0;
+	const summary = "Upstream click reported success but no trusted DOM event reached the selected element. Gather evidence with snapshot or page-change checks, then retry upstream click or report the workflow issue; the wrapper does not replay clicks in-page.";
+	return {
+		nativeEventCount,
+		reason: "native-click-produced-no-target-dom-event",
+		status,
+		summary,
+		target: redactClickDispatchTarget(options.probe.target),
+	};
+}
+
+export async function cleanupClickDispatchProbe(options: { cwd: string; probe?: ClickDispatchProbe; sessionName?: string }): Promise<void> {
+	if (!options.probe || !options.sessionName) return;
+	await runSessionCommandData({
+		args: ["eval", "--stdin"],
+		cwd: options.cwd,
+		sessionName: options.sessionName,
+		stdin: buildClickDispatchProbeCleanupScript(options.probe),
+		timeoutMs: CLICK_DISPATCH_CLEANUP_TIMEOUT_MS,
+	}).catch(() => undefined);
+}

package/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.ts

@@ -1,8 +1,9 @@
-import { constants as fsConstants } from "node:fs";
-import { access, stat } from "node:fs/promises";
-import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
 
+import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
 import type { ElectronLaunchRecord } from "../../electron/launch.js";
+import { executableExistsOnPath } from "../../executable-path.js";
 import type { AgentBrowserSourceLookupAnalysis, CompiledAgentBrowserJob, CompiledAgentBrowserSemanticAction } from "../../input-modes.js";
 import { isHttpOrHttpsUrl } from "../../input-modes/job.js";
 import type { AgentBrowserNextAction } from "../../results.js";
@@ -20,12 +21,14 @@ import {
 	getGuardedRefUsage,
 	runSessionCommandData,
 } from "./session-state.js";
+import { parseValidBatchStepEntries } from "../batch-stdin.js";
 import { getScreenshotPathTokenIndex } from "./prepare.js";
 import type {
 	ArtifactCleanupGuidance,
 	ComboboxFocusDiagnostic,
 	ElectronBroadGetTextScopeDiagnostic,
 	ElectronHandoffSummary,
+	ElectronManagedSessionTarget,
 	FillVerificationDiagnostic,
 	NavigationSummary,
 	OverlayBlockerCandidate,
@@ -238,23 +241,6 @@ function getRecordStartLikeCommand(command: string | undefined, commandTokens: s
 	return undefined;
 }
 
-async function executableExistsOnPath(command: string): Promise<boolean> {
-	const pathValue = process.env.PATH ?? "";
-	const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [""];
-	for (const directory of pathValue.split(delimiter).filter(Boolean)) {
-		for (const extension of extensions) {
-			try {
-				const candidate = join(directory, `${command}${extension}`);
-				await access(candidate, fsConstants.X_OK);
-				if ((await stat(candidate)).isFile()) return true;
-			} catch {
-				// Try the next candidate.
-			}
-		}
-	}
-	return false;
-}
-
 export async function collectRecordingDependencyWarning(options: { command: string | undefined; commandTokens: string[]; succeeded: boolean }): Promise<RecordingDependencyWarning | undefined> {
 	if (!options.succeeded) return undefined;
 	const recordCommand = getRecordStartLikeCommand(options.command, options.commandTokens);
@@ -466,7 +452,7 @@ export function formatEvalStdinHintText(hint: ReturnType<typeof getEvalStdinHint
 }
 
 export async function getArtifactCleanupGuidance(options: { command?: string; cwd: string; manifest?: SessionArtifactManifest; succeeded: boolean }): Promise<ArtifactCleanupGuidance | undefined> {
-	if (!options.succeeded || options.command !== "close" || !options.manifest || options.manifest.entries.length === 0) return undefined;
+	if (!options.succeeded || !isCloseCommand(options.command) || !options.manifest || options.manifest.entries.length === 0) return undefined;
 	const explicitEntries = options.manifest.entries.filter((entry) => entry.storageScope === "explicit-path");
 	const explicitArtifactPaths: string[] = [];
 	const seenPaths = new Set<string>();
@@ -505,7 +491,7 @@ async function collectElectronManagedSessionUrl(options: { cwd: string; sessionN
 	return urlResult.error ? { error: urlResult.error } : { url };
 }
 
-async function collectElectronManagedSessionTarget(options: { cwd: string; sessionName?: string; signal?: AbortSignal; timeoutMs?: number }): Promise<QaAttachedTarget | undefined> {
+export async function collectElectronManagedSessionTarget(options: { cwd: string; sessionName?: string; signal?: AbortSignal; timeoutMs?: number }): Promise<ElectronManagedSessionTarget | undefined> {
 	if (!options.sessionName) return undefined;
 	const [titleResult, urlResult] = await Promise.all([
 		collectManagedSessionCommandData({ args: ["get", "title"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs }),
@@ -647,11 +633,7 @@ export async function collectElectronHandoff(options: { cwd: string; handoff: "c
 function getTimeoutProgressSteps(compiledJob: CompiledAgentBrowserJob | undefined, command: string | undefined, stdin: string | undefined): Array<{ args: string[]; index: number }> {
 	if (compiledJob) return compiledJob.steps.map((step, index) => ({ args: step.args, index: index + 1 }));
 	if (command !== "batch" || !stdin) return [];
-	try {
-		const parsed = JSON.parse(stdin) as unknown;
-		if (!Array.isArray(parsed)) return [];
-		return parsed.flatMap((step, index) => Array.isArray(step) && step.every((token) => typeof token === "string") ? [{ args: step as string[], index: index + 1 }] : []);
-	} catch { return []; }
+	return parseValidBatchStepEntries(stdin).map(({ index, step }) => ({ args: step, index: index + 1 }));
 }
 
 function getLastPositionalToken(args: string[], startIndex = 1): string | undefined {
@@ -709,7 +691,7 @@ async function collectTimeoutArtifactEvidence(cwd: string, steps: Array<{ args:
 function getPlannedCurrentPageUrl(steps: Array<{ args: string[]; index: number }>): string | undefined {
 	for (let index = steps.length - 1; index >= 0; index -= 1) {
 		const args = steps[index]?.args ?? [];
-		if (args[0] === "open" || args[0] === "navigate" || args[0] === "pushstate") return getLastPositionalToken(args);
+		if (isOpenNavigationCommand(args[0]) || args[0] === "pushstate") return getLastPositionalToken(args);
 	}
 	return undefined;
 }

package/extensions/agent-browser/lib/orchestration/browser-run/final-result.ts

@@ -43,6 +43,7 @@ import {
 } from "../../session-page-state.js";
 import { extractExplicitSessionName, redactInvocationArgs, redactSensitiveText, redactSensitiveValue, type OpenResultTabCorrection } from "../../runtime.js";
 import { isRecord } from "../../parsing.js";
+import { buildClickDispatchNextActions, formatClickDispatchDiagnosticText } from "./click-dispatch.js";
 import {
 	buildComboboxFocusNextActions,
 	buildElectronBroadGetTextScopeNextActions,
@@ -212,7 +213,7 @@ export function buildElectronHostFailureResult(options: {
 	return { content: [{ type: "text", text: redactSensitiveText(text) }], details: redactToolDetails(details, []), isError: true };
 }
 
-function formatElectronTargetLines(targets: ElectronCdpTarget[], limit = 8): string[] {
+export function formatElectronTargetLines(targets: ElectronCdpTarget[], limit = 8): string[] {
 	const shownTargets = targets.slice(0, limit);
 	const lines = shownTargets.map((target) => {
 		const label = [target.type, target.title].filter(Boolean).join(" ") || target.id || "target";
@@ -319,6 +320,7 @@ function buildResultNextActions(options: FinalResultInput): AgentBrowserNextActi
 	if (options.selectorTextVisibilityDiagnostics.length > 0) nextActionCollector.append(buildSelectorTextVisibilityNextActions({ diagnostics: options.selectorTextVisibilityDiagnostics, sessionName: options.executionPlan.sessionName }));
 	if (options.electronBroadGetTextScopeDiagnostics.length > 0) nextActionCollector.append(buildElectronBroadGetTextScopeNextActions({ diagnostics: options.electronBroadGetTextScopeDiagnostics, sessionName: options.executionPlan.sessionName }));
 	if (options.sourceLookup?.electronContext) nextActionCollector.appendUnique(buildSourceLookupElectronNextActions(options.sourceLookup));
+	if (options.clickDispatchDiagnostic) nextActionCollector.append(buildClickDispatchNextActions({ commandTokens: options.commandTokens, sessionName: options.executionPlan.sessionName }));
 	if (options.scrollNoopDiagnostic) nextActionCollector.append(buildScrollNoopNextActions(options.executionPlan.sessionName));
 	if (options.comboboxFocusDiagnostic) nextActionCollector.append(buildComboboxFocusNextActions(options.executionPlan.sessionName));
 	if (options.categoryDetails.failureCategory === "stale-ref" && options.redactedCompiledSemanticAction && isCompiledSemanticActionFindCommand(options.compiledSemanticAction)) nextActionCollector.append([{ id: "retry-semantic-action-after-stale-ref", params: { args: options.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 }]);
@@ -369,6 +371,7 @@ function buildAgentBrowserResultDetails(options: FinalResultInput, nextActions:
 		imagePaths: options.presentation.imagePaths,
 		nextActions,
 		pageChangeSummary,
+		clickDispatch: options.clickDispatchDiagnostic,
 		overlayBlockers: options.overlayBlockerDiagnostic,
 		fillVerification: options.fillVerificationDiagnostic,
 		visibleRefFallback: publicVisibleRefFallbackDiagnostic,
@@ -411,6 +414,7 @@ export function buildFinalAgentBrowserToolResult(options: FinalResultInput): Age
 	const visibleRefFallbackText = formatVisibleRefFallbackText(options.visibleRefFallbackDiagnostic);
 	const richInputRecoveryText = formatRichInputRecoveryText(options.richInputRecoveryDiagnostic);
 	const semanticActionCandidateText = nextActions ? formatSemanticActionCandidateText(nextActions) : undefined;
+	const clickDispatchText = options.clickDispatchDiagnostic ? formatClickDispatchDiagnosticText(options.clickDispatchDiagnostic) : undefined;
 	const overlayBlockerText = options.overlayBlockerDiagnostic ? formatOverlayBlockerText(options.overlayBlockerDiagnostic) : undefined;
 	const fillVerificationText = formatFillVerificationText(options.fillVerificationDiagnostic);
 	const electronRefFreshnessText = formatElectronRefFreshnessText(options.electronRefFreshnessDiagnostic);
@@ -423,7 +427,7 @@ export function buildFinalAgentBrowserToolResult(options: FinalResultInput): Age
 	const artifactCleanupText = formatArtifactCleanupGuidanceText(options.artifactCleanup);
 	const timeoutPartialProgressText = options.timeoutPartialProgress ? formatTimeoutPartialProgressText(options.timeoutPartialProgress) : undefined;
 	const managedSessionOutcomeText = formatManagedSessionOutcomeText(options.managedSessionOutcome);
-	const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
+	const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, clickDispatchText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
 	const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, options.exactSensitiveValues));
 	const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!options.userRequestedJson || options.plainTextInspection);
 	let content = shouldAppendDiagnosticText && options.redactedContent[0]?.type === "text" ? [{ ...options.redactedContent[0], text: `${options.redactedContent[0].text}\n\n${appendedDiagnosticText}` }, ...options.redactedContent.slice(1)] : options.redactedContent;

package/extensions/agent-browser/lib/orchestration/browser-run/index.ts

@@ -1,11 +1,13 @@
 import { runAgentBrowserProcess } from "../../process.js";
+import { cleanupClickDispatchProbe } from "./click-dispatch.js";
 import { applyBrowserRunStatePatch } from "./session-state.js";
 import { buildMissingBinaryFailureResult } from "./final-result.js";
 import { prepareBrowserRun } from "./prepare.js";
 import { processBrowserOutput } from "./process-output.js";
 import type { AgentBrowserToolResult, BrowserRunOptions } from "./types.js";
 
-export type { BrowserRunOptions, BrowserRunState } from "./types.js";
+export { closeManagedSession } from "./session-state.js";
+export type { AgentBrowserToolResult, BrowserRunOptions, BrowserRunState, TraceOwner } from "./types.js";
 
 export async function runAgentBrowserTool(options: BrowserRunOptions): Promise<AgentBrowserToolResult> {
 	const preparedResult = await prepareBrowserRun(options);
@@ -15,32 +17,36 @@ export async function runAgentBrowserTool(options: BrowserRunOptions): Promise<A
 	}
 
 	const { prepared } = preparedResult;
-	const processResult = await runAgentBrowserProcess({
-		args: prepared.processArgs,
-		cwd: options.cwd,
-		env: prepared.executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined,
-		signal: options.signal,
-		stdin: prepared.processStdin,
-	});
+	try {
+		const processResult = await runAgentBrowserProcess({
+			args: prepared.processArgs,
+			cwd: options.cwd,
+			env: prepared.executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined,
+			signal: options.signal,
+			stdin: prepared.processStdin,
+		});
 
-	const missingBinaryResult = await buildMissingBinaryFailureResult({
-		compatibilityWorkaround: prepared.compatibilityWorkaround,
-		electronLaunch: prepared.electronLaunch,
-		executionPlan: prepared.executionPlan,
-		implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
-		managedSessionActive: options.state.managedSessionActive,
-		managedSessionName: options.state.managedSessionName,
-		processResult,
-		redactedArgs: prepared.redactedArgs,
-		redactedProcessArgs: prepared.redactedProcessArgs,
-		sessionMode: prepared.sessionMode,
-		sessionTabCorrection: prepared.sessionTabCorrection,
-	});
-	if (missingBinaryResult) {
-		return missingBinaryResult;
-	}
+		const missingBinaryResult = await buildMissingBinaryFailureResult({
+			compatibilityWorkaround: prepared.compatibilityWorkaround,
+			electronLaunch: prepared.electronLaunch,
+			executionPlan: prepared.executionPlan,
+			implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
+			managedSessionActive: options.state.managedSessionActive,
+			managedSessionName: options.state.managedSessionName,
+			processResult,
+			redactedArgs: prepared.redactedArgs,
+			redactedProcessArgs: prepared.redactedProcessArgs,
+			sessionMode: prepared.sessionMode,
+			sessionTabCorrection: prepared.sessionTabCorrection,
+		});
+		if (missingBinaryResult) {
+			return missingBinaryResult;
+		}
 
-	const output = await processBrowserOutput({ ...options, prepared, processResult });
-	applyBrowserRunStatePatch(options.state, output.statePatch);
-	return output.result;
+		const output = await processBrowserOutput({ ...options, prepared, processResult });
+		applyBrowserRunStatePatch(options.state, output.statePatch);
+		return output.result;
+	} finally {
+		await cleanupClickDispatchProbe({ cwd: options.cwd, probe: prepared.clickDispatchProbe, sessionName: prepared.executionPlan.sessionName });
+	}
 }