pi-agent-browser-native 0.2.33 → 0.2.35

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

@@ -4,6 +4,7 @@
  * Scope: Job and QA modes only.
  */
 
+import type { ArtifactVerificationSummary } from "../results/contracts.js";
 import { isRecord } from "../parsing.js";
 import { summarizeNetworkFailures } from "../results/network.js";
 import { getBatchResultItems, getCommandNameFromBatchItem, getSelectValues } from "./shared.js";
@@ -93,6 +94,67 @@ export function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAge
 	return { compiled: { args: ["batch"], stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
 }
 
+export function isHttpOrHttpsUrl(url: string): boolean {
+	try {
+		const protocol = new URL(url).protocol;
+		return protocol === "http:" || protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+
+function describeQaChecksRun(checks: CompiledAgentBrowserQaPreset["checks"]): string {
+	const parts = [`load:${checks.loadState}`];
+	if (checks.expectedText.length > 0) parts.push(`text×${checks.expectedText.length}`);
+	if (checks.expectedSelector) parts.push("selector");
+	if (checks.checkNetwork) parts.push("network");
+	if (checks.checkConsole) parts.push("console");
+	if (checks.checkErrors) parts.push("errors");
+	if (checks.screenshotPath) parts.push("screenshot");
+	return parts.join(", ");
+}
+
+export function extractQaPageContext(options: {
+	attachedTarget?: { title?: string; url?: string };
+	batchData?: unknown;
+	compiled?: CompiledAgentBrowserQaPreset;
+}): { title?: string; url?: string } {
+	if (options.attachedTarget?.title || options.attachedTarget?.url) {
+		return { title: options.attachedTarget.title, url: options.attachedTarget.url };
+	}
+	for (const item of getBatchResultItems(options.batchData)) {
+		if (getCommandNameFromBatchItem(item) !== "open" || !isRecord(item.result)) continue;
+		const url = typeof item.result.url === "string" ? item.result.url : undefined;
+		const title = typeof item.result.title === "string" ? item.result.title : undefined;
+		if (url || title) return { title, url };
+	}
+	if (options.compiled?.checks.url) {
+		return { url: options.compiled.checks.url };
+	}
+	return {};
+}
+
+export function buildQaCompactPassText(options: {
+	artifactVerification?: ArtifactVerificationSummary;
+	batchStepCount: number;
+	checks: CompiledAgentBrowserQaPreset["checks"];
+	page?: { title?: string; url?: string };
+	qaPreset: AgentBrowserQaPresetAnalysis;
+}): string {
+	const lines = [options.qaPreset.summary];
+	const pageParts = [options.page?.title, options.page?.url].filter((part): part is string => typeof part === "string" && part.length > 0);
+	if (pageParts.length > 0) lines.push(`Page: ${pageParts.join(" — ")}`);
+	lines.push(`Checks run: ${describeQaChecksRun(options.checks)} (${options.batchStepCount} batch step${options.batchStepCount === 1 ? "" : "s"})`);
+	if (options.checks.screenshotPath) {
+		const verification = options.artifactVerification;
+		lines.push(verification
+			? `Screenshot: ${options.checks.screenshotPath} (${verification.verifiedCount}/${verification.artifacts.length} verified on disk)`
+			: `Screenshot: ${options.checks.screenshotPath}`);
+	}
+	lines.push("Full diagnostic matrix: see details.qaPreset and details.batchSteps.");
+	return lines.join("\n");
+}
+
 export function analyzeQaPresetResults(data: unknown): AgentBrowserQaPresetAnalysis | undefined {
 	const items = getBatchResultItems(data);
 	if (items.length === 0) return undefined;

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

@@ -25,8 +25,8 @@ import {
 export const AGENT_BROWSER_PARAMS = Type.Object({
 
 	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, networkSourceLookup, or electron is provided.",
+		Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name. Do not pass --json; the wrapper injects it. First-call recipe: open → snapshot -i → click/fill @eN → snapshot -i." }), {
+			description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators. Required unless semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron is provided. Do not include --json (wrapper injects it). Typical first calls: open, snapshot -i, click/fill current @refs, then snapshot -i again after navigation or DOM changes.",
 			minItems: 1,
 		}),
 	),
@@ -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 })),
-		}),
+		}, { 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 })),
-		}),
+		}, { 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/input-modes.ts

@@ -7,8 +7,11 @@
 export { AGENT_BROWSER_PARAMS } from "./input-modes/params.js";
 export {
 	analyzeQaPresetResults,
+	buildQaCompactPassText,
 	compileAgentBrowserJob,
 	compileAgentBrowserQaPreset,
+	extractQaPageContext,
+	isHttpOrHttpsUrl,
 } from "./input-modes/job.js";
 export {
 	analyzeNetworkSourceLookupResults,

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);
+}