pi-agent-browser-native 0.2.48 → 0.2.49

package/extensions/agent-browser/lib/json-schema.ts

@@ -1,73 +0,0 @@
-/**
- * Purpose: Build the small JSON Schema subset used by Pi tool schemas without importing TypeBox at runtime.
- * Responsibilities: Preserve plain JSON Schema objects Pi consumes while keeping extension startup cheap.
- * Scope: Schema construction only; runtime validation still belongs to Pi and the tool input compilers.
- */
-
-import type { TSchema, TSchemaOptions, TUnsafe } from "typebox";
-
-const OPTIONAL_SCHEMA = Symbol("pi-agent-browser-optional-schema");
-
-type SchemaObject = TSchema & { [OPTIONAL_SCHEMA]?: true };
-type SchemaProperties = Record<string, TSchema>;
-
-function withOptions(schema: Record<string, unknown>, options?: TSchemaOptions): TSchema {
-	return { ...schema, ...(options ?? {}) } as TSchema;
-}
-
-function literalType(value: unknown): "boolean" | "number" | "string" | undefined {
-	const valueType = typeof value;
-	return valueType === "string" || valueType === "number" || valueType === "boolean" ? valueType : undefined;
-}
-
-function propertySchema(schema: TSchema): TSchema {
-	const clone = { ...(schema as SchemaObject & Record<PropertyKey, unknown>) };
-	delete clone[OPTIONAL_SCHEMA];
-	return clone as TSchema;
-}
-
-export const JsonSchema = {
-	Array(items: TSchema, options?: TSchemaOptions): TSchema {
-		return withOptions({ type: "array", items }, options);
-	},
-	Boolean(options?: TSchemaOptions): TSchema {
-		return withOptions({ type: "boolean" }, options);
-	},
-	Integer(options?: TSchemaOptions): TSchema {
-		return withOptions({ type: "integer" }, options);
-	},
-	Literal(value: unknown, options?: TSchemaOptions): TSchema {
-		const type = literalType(value);
-		return withOptions(type ? { type, const: value } : { const: value }, options);
-	},
-	Number(options?: TSchemaOptions): TSchema {
-		return withOptions({ type: "number" }, options);
-	},
-	Object(properties: SchemaProperties, options?: TSchemaOptions): TSchema {
-		const required = globalThis.Object.entries(properties)
-			.filter(([, schema]) => (schema as SchemaObject)[OPTIONAL_SCHEMA] !== true)
-			.map(([key]) => key);
-		return withOptions({
-			type: "object",
-			properties: globalThis.Object.fromEntries(
-				globalThis.Object.entries(properties).map(([key, schema]) => [key, propertySchema(schema)]),
-			),
-			...(required.length > 0 ? { required } : {}),
-		}, options);
-	},
-	Optional(schema: TSchema): TSchema {
-		return { ...(schema as SchemaObject), [OPTIONAL_SCHEMA]: true } as TSchema;
-	},
-	String(options?: TSchemaOptions): TSchema {
-		return withOptions({ type: "string" }, options);
-	},
-	Union(types: TSchema[], options?: TSchemaOptions): TSchema {
-		return withOptions({ anyOf: types }, options);
-	},
-	Unsafe<Value>(schema: TSchema): TUnsafe<Value> {
-		return schema as TUnsafe<Value>;
-	},
-};
-
-export type JsonSchemaBuilder = typeof JsonSchema;
-export type { TSchema, TSchemaOptions, TUnsafe };

package/extensions/agent-browser/lib/launch-scoped-flags.ts

@@ -1,67 +0,0 @@
-/**
- * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
- * Responsibilities: Define which upstream flags require a fresh launch, explain why, and expose stable guidance labels.
- * Scope: Metadata only; argv parsing and execution planning live in runtime.ts.
- */
-
-export interface LaunchScopedFlagDefinition {
-	flag: string;
-	reason: string;
-}
-
-export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
-	{
-		flag: "--auto-connect",
-		reason: "attaches to an already-running browser at launch time instead of reusing an existing named session",
-	},
-	{
-		flag: "--cdp",
-		reason: "selects the browser/CDP endpoint used when an upstream session is launched",
-	},
-	{
-		flag: "--enable",
-		reason: "selects built-in page init scripts before the upstream browser session is launched",
-	},
-	{
-		flag: "--executable-path",
-		reason: "selects the browser executable used for the upstream launch",
-	},
-	{
-		flag: "--init-script",
-		reason: "registers page init scripts before the upstream browser session is launched",
-	},
-	{
-		flag: "--device",
-		reason: "selects the provider device for the upstream launch",
-	},
-	{
-		flag: "--profile",
-		reason: "selects Chrome profile state for the upstream launch",
-	},
-	{
-		flag: "--provider",
-		reason: "selects the upstream browser provider for the launch",
-	},
-	{
-		flag: "-p",
-		reason: "selects the upstream browser provider for the launch",
-	},
-	{
-		flag: "--session-name",
-		reason: "selects upstream saved auth/session state for the launch",
-	},
-	{
-		flag: "--state",
-		reason: "loads persisted upstream browser/auth state at launch time",
-	},
-] as const satisfies readonly LaunchScopedFlagDefinition[];
-
-export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
-export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
-
-/**
- * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
- * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
- * tab-correction (the `tab list` + re-select cycle).
- */
-export const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"] as const);

package/extensions/agent-browser/lib/navigation-policy.ts

@@ -1,95 +0,0 @@
-/**
- * Purpose: Keep wrapper-side navigation policy parsing and evaluation small and explicit.
- * Responsibilities: Parse allowed-domain argv values and detect final-page host escapes.
- * Scope: Wrapper diagnostics only; upstream remains responsible for browser-time enforcement.
- */
-
-export interface AllowedDomainsPolicy {
-	allowedDomains: string[];
-	display: string;
-}
-
-export interface AllowedDomainsViolation {
-	allowedDomains: string[];
-	allowedDisplay: string;
-	observedHost: string;
-	observedUrl: string;
-	summary: string;
-}
-
-function normalizeDomainEntry(value: string): string | undefined {
-	let candidate = value.trim().toLowerCase();
-	if (!candidate) return undefined;
-	try {
-		if (/^[a-z][a-z0-9+.-]*:\/\//i.test(candidate)) {
-			candidate = new URL(candidate).hostname;
-		}
-	} catch {
-		return undefined;
-	}
-	candidate = candidate.replace(/^\*\./, "").replace(/\.$/, "");
-	if (candidate.includes("/")) candidate = candidate.split("/")[0] ?? "";
-	if (candidate.includes(":")) candidate = candidate.split(":")[0] ?? "";
-	return candidate.length > 0 ? candidate : undefined;
-}
-
-function splitAllowedDomainsValue(value: string): string[] {
-	return value.split(/[,\s]+/).map((entry) => entry.trim()).filter(Boolean);
-}
-
-export function parseAllowedDomainsPolicyFromArgs(args: readonly string[]): AllowedDomainsPolicy | undefined {
-	const domains: string[] = [];
-	for (let index = 0; index < args.length; index += 1) {
-		const arg = args[index];
-		if (arg === "--allowed-domains") {
-			const value = args[index + 1];
-			if (value && !value.startsWith("-")) {
-				domains.push(...splitAllowedDomainsValue(value));
-				index += 1;
-			}
-			continue;
-		}
-		if (arg?.startsWith("--allowed-domains=")) {
-			domains.push(...splitAllowedDomainsValue(arg.slice("--allowed-domains=".length)));
-		}
-	}
-	const allowedDomains = [...new Set(domains.flatMap((domain) => {
-		const normalized = normalizeDomainEntry(domain);
-		return normalized ? [normalized] : [];
-	}))];
-	if (allowedDomains.length === 0) return undefined;
-	return { allowedDomains, display: allowedDomains.join(", ") };
-}
-
-function normalizeObservedHost(url: string): string | undefined {
-	try {
-		const parsed = new URL(url);
-		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return undefined;
-		return parsed.hostname.toLowerCase().replace(/\.$/, "");
-	} catch {
-		return undefined;
-	}
-}
-
-export function isHostAllowedByDomains(host: string, allowedDomains: readonly string[]): boolean {
-	const normalizedHost = host.toLowerCase().replace(/\.$/, "");
-	return allowedDomains.some((domain) => normalizedHost === domain || normalizedHost.endsWith(`.${domain}`));
-}
-
-export function getAllowedDomainsViolation(options: {
-	policy?: AllowedDomainsPolicy;
-	url?: string;
-}): AllowedDomainsViolation | undefined {
-	if (!options.policy || !options.url) return undefined;
-	const observedHost = normalizeObservedHost(options.url);
-	if (!observedHost) return undefined;
-	if (isHostAllowedByDomains(observedHost, options.policy.allowedDomains)) return undefined;
-	const summary = `Navigation policy blocked: --allowed-domains ${options.policy.display} does not allow ${observedHost} (${options.url}).`;
-	return {
-		allowedDomains: options.policy.allowedDomains,
-		allowedDisplay: options.policy.display,
-		observedHost,
-		observedUrl: options.url,
-		summary,
-	};
-}

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

@@ -1,65 +0,0 @@
-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/artifact-paths.ts

@@ -1,44 +0,0 @@
-import { extname, isAbsolute } from "node:path";
-
-const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
-const SCREENSHOT_IMAGE_EXTENSIONS = new Set([".jpeg", ".jpg", ".png", ".webp"]);
-
-function isImagePathToken(token: string): boolean {
-	const extension = extname(token).toLowerCase();
-	return SCREENSHOT_IMAGE_EXTENSIONS.has(extension);
-}
-
-export function getScreenshotPathTokenIndex(commandTokens: string[]): number | undefined {
-	if (commandTokens[0] !== "screenshot") {
-		return undefined;
-	}
-
-	const positionalIndices: number[] = [];
-	for (let index = 1; index < commandTokens.length; index += 1) {
-		const token = commandTokens[index];
-		if (token === "--") {
-			for (let positionalIndex = index + 1; positionalIndex < commandTokens.length; positionalIndex += 1) {
-				positionalIndices.push(positionalIndex);
-			}
-			break;
-		}
-		if (token.startsWith("-")) {
-			const normalizedToken = token.split("=", 1)[0] ?? token;
-			if (SCREENSHOT_VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
-				index += 1;
-			}
-			continue;
-		}
-		positionalIndices.push(index);
-	}
-
-	if (positionalIndices.length === 0) {
-		return undefined;
-	}
-	const candidateIndex = positionalIndices[positionalIndices.length - 1];
-	const candidate = commandTokens[candidateIndex];
-	if (positionalIndices.length >= 2 || isImagePathToken(candidate) || isAbsolute(candidate) || candidate.startsWith("./") || candidate.startsWith("../")) {
-		return candidateIndex;
-	}
-	return undefined;
-}

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

@@ -1,280 +0,0 @@
-import { isRecord } from "../../parsing.js";
-import { redactSensitiveText } from "../../runtime.js";
-import { withOptionalSessionArgs, type AgentBrowserNextAction } from "../../results/next-actions.js";
-import type { SessionRefSnapshot } from "../../session-page-state.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;
-const ACCESSIBLE_REF_CLICK_DISPATCH_ROLES = new Set(["button", "checkbox", "menuitem", "radio", "switch", "tab"]);
-
-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 normalizeAccessibleName(name: string): string {
-	return name.replace(/\s+/g, " ").trim().toLowerCase();
-}
-
-function getAccessibleRefDuplicateIndex(refSnapshot: SessionRefSnapshot | undefined, refId: string, role: string, name: string): number | undefined {
-	if (!refSnapshot?.refs) return undefined;
-	const normalizedRole = role.toLowerCase();
-	const normalizedName = normalizeAccessibleName(name);
-	const matchingRefIds = refSnapshot.refIds.filter((candidateRefId) => {
-		const candidate = refSnapshot.refs?.[candidateRefId];
-		return candidate?.role.toLowerCase() === normalizedRole && normalizeAccessibleName(candidate.name) === normalizedName;
-	});
-	if (matchingRefIds.length <= 1) return undefined;
-	const duplicateIndex = matchingRefIds.indexOf(refId);
-	return duplicateIndex >= 0 ? duplicateIndex : undefined;
-}
-
-function getClickDispatchProbeTarget(commandTokens: string[], refSnapshot?: SessionRefSnapshot): ClickDispatchProbeTarget | undefined {
-	if (commandTokens[0] !== "click" || commandTokens.includes("--new-tab")) return undefined;
-	const selector = commandTokens[1];
-	if (!selector || selector.startsWith("-")) return undefined;
-	const refId = parseClickRefId(selector);
-	if (refId) {
-		const ref = refSnapshot?.refs?.[refId];
-		if (!ref || !ACCESSIBLE_REF_CLICK_DISPATCH_ROLES.has(ref.role)) return undefined;
-		const duplicateIndex = getAccessibleRefDuplicateIndex(refSnapshot, refId, ref.role, ref.name);
-		return { ...(duplicateIndex === undefined ? {} : { duplicateIndex }), kind: "accessible", name: ref.name, refId, role: ref.role };
-	}
-	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; } })()`
-		: target.kind === "xpath"
-			? `(() => { try { return document.evaluate(${JSON.stringify(target.selector)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue; } catch { return null; } })()`
-			: `(() => {
-  const normalize = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
-  const expectedRole = ${JSON.stringify(target.role)};
-  const expectedName = normalize(${JSON.stringify(target.name)});
-  const duplicateIndex = ${JSON.stringify(target.duplicateIndex)};
-  const inferRole = (element) => {
-    const explicit = element.getAttribute("role");
-    if (explicit) return explicit;
-    const tagName = element.tagName.toLowerCase();
-    if (tagName === "button" || tagName === "select" || tagName === "textarea") return tagName;
-    if (tagName === "a" && element.hasAttribute("href")) return "link";
-    if (tagName === "input") {
-      const type = (element.getAttribute("type") || "text").toLowerCase();
-      if (["button", "submit", "reset", "image"].includes(type)) return "button";
-      if (type === "checkbox") return "checkbox";
-      if (type === "radio") return "radio";
-      return "textbox";
-    }
-    return "";
-  };
-  const inferName = (element) => normalize(element.getAttribute("aria-label") || element.getAttribute("title") || element.value || element.textContent || "");
-  const isVisible = (element) => {
-    const style = window.getComputedStyle(element);
-    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
-    return element.getClientRects().length > 0;
-  };
-  const candidates = Array.from(document.querySelectorAll("button,a[href],input,select,textarea,summary,[role],[onclick],[tabindex]")).filter((element) => inferRole(element) === expectedRole && inferName(element) === expectedName && isVisible(element));
-  if (typeof duplicateIndex === "number") return candidates[duplicateIndex] || null;
-  return candidates.length === 1 ? candidates[0] : null;
-})()`;
-	return `(() => {
-const marker = ${JSON.stringify(probe.marker)};
-const element = ${resolveTarget};
-if (!element) return { status: "target-not-found", marker };
-const cssEscape = (value) => {
-  if (window.CSS && typeof window.CSS.escape === "function") return window.CSS.escape(value);
-  return String(value).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
-};
-const getSelector = (node) => {
-  if (!(node instanceof Element)) return undefined;
-  if (node.id) return "#" + cssEscape(node.id);
-  const testId = node.getAttribute("data-testid") || node.getAttribute("data-test-id");
-  if (testId) return '[data-testid="' + cssEscape(testId) + '"]';
-  const parts = [];
-  let current = node;
-  while (current && current !== document.body && parts.length < 4) {
-    const tag = current.tagName.toLowerCase();
-    const parent = current.parentElement;
-    if (!parent) break;
-    const siblings = Array.from(parent.children).filter((child) => child.tagName === current.tagName);
-    const index = siblings.indexOf(current) + 1;
-    parts.unshift(siblings.length > 1 ? tag + ':nth-of-type(' + index + ')' : tag);
-    current = parent;
-  }
-  return parts.length > 0 ? parts.join(" > ") : undefined;
-};
-const rectInfo = (rect) => ({ bottom: rect.bottom, left: rect.left, right: rect.right, top: rect.top });
-const targetRect = element ? element.getBoundingClientRect() : undefined;
-const targetOutsideViewport = targetRect ? targetRect.bottom < 0 || targetRect.right < 0 || targetRect.top > window.innerHeight || targetRect.left > window.innerWidth : undefined;
-let nearestScrollContainer;
-if (element && targetRect) {
-  for (let current = element.parentElement; current && current !== document.body; current = current.parentElement) {
-    if (current.scrollHeight > current.clientHeight + 1 || current.scrollWidth > current.clientWidth + 1) {
-      const containerRect = current.getBoundingClientRect();
-      nearestScrollContainer = {
-        selector: getSelector(current),
-        tagName: current.tagName.toLowerCase(),
-        targetOutsideContainer: targetRect.bottom < containerRect.top || targetRect.top > containerRect.bottom || targetRect.right < containerRect.left || targetRect.left > containerRect.right,
-        targetOutsideViewport,
-        rect: rectInfo(containerRect),
-        scrollLeft: current.scrollLeft,
-        scrollTop: current.scrollTop,
-      };
-      break;
-    }
-  }
-}
-const state = { events: [], target: { tagName: element.tagName.toLowerCase(), nearestScrollContainer, rect: rectInfo(targetRect), targetOutsideViewport } };
-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 {
-	if (target.kind === "selector" || target.kind === "xpath") {
-		return { ...target, selector: redactSensitiveText(target.selector) };
-	}
-	return { ...target, name: redactSensitiveText(target.name) };
-}
-
-export function formatClickDispatchDiagnosticText(diagnostic: ClickDispatchDiagnostic): string {
-	return `Click dispatch diagnostic: ${diagnostic.summary}`;
-}
-
-export function buildClickDispatchNextActions(options: { commandTokens: string[]; diagnostic?: ClickDispatchDiagnostic; sessionName?: string }): AgentBrowserNextAction[] {
-	const retryArgs = options.commandTokens[0] === "click" || options.commandTokens[0] === "find" ? options.commandTokens : ["click", ...options.commandTokens];
-	const actions: AgentBrowserNextAction[] = [
-		{
-			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",
-		},
-	];
-	if (options.diagnostic?.scrollContainer) {
-		actions.push({
-			id: "scroll-target-into-view-after-dispatch-miss",
-			params: { args: withOptionalSessionArgs(options.sessionName, ["scrollintoview", retryArgs[1]].filter((item): item is string => typeof item === "string")) },
-			reason: options.diagnostic.scrollContainer.selector
-				? `The target may be outside nested scroll container ${options.diagnostic.scrollContainer.selector}; scroll the target into view before retrying the click.`
-				: "The target may be inside an offscreen nested scroll container; scroll the target into view before retrying the click.",
-			safety: "Use only for the same current page and target; run snapshot -i again if the page rerendered.",
-			tool: "agent_browser",
-		});
-	}
-	actions.push({
-		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",
-	});
-	return actions;
-}
-
-export async function prepareClickDispatchProbe(options: { commandTokens: string[]; cwd: string; refSnapshot?: SessionRefSnapshot; sessionName?: string; signal?: AbortSignal }): Promise<ClickDispatchProbe | undefined> {
-	if (!options.sessionName || options.commandTokens[0] !== "click" || options.commandTokens.includes("--new-tab")) return undefined;
-	const target = getClickDispatchProbeTarget(options.commandTokens, options.refSnapshot);
-	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;
-}
-
-function getClickDispatchScrollContainerDiagnostic(result: Record<string, unknown>): ClickDispatchDiagnostic["scrollContainer"] {
-	const target = isRecord(result.target) ? result.target : undefined;
-	const scrollContainer = isRecord(target?.nearestScrollContainer) ? target.nearestScrollContainer : undefined;
-	const targetOutsideViewport = typeof target?.targetOutsideViewport === "boolean" ? target.targetOutsideViewport : undefined;
-	const targetOutsideContainer = typeof scrollContainer?.targetOutsideContainer === "boolean" ? scrollContainer.targetOutsideContainer : undefined;
-	if (!scrollContainer && !targetOutsideViewport) return undefined;
-	if (targetOutsideContainer !== true && targetOutsideViewport !== true) return undefined;
-	const selector = typeof scrollContainer?.selector === "string" ? redactSensitiveText(scrollContainer.selector) : undefined;
-	const summary = selector
-		? `Target appears outside nested scroll container ${selector}; use scrollintoview on the target or scroll that container before retrying.`
-		: "Target appears outside the viewport or a nested scroll container; use scrollintoview on the target before retrying.";
-	return { selector, summary, targetOutsideContainer, targetOutsideViewport };
-}
-
-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 scrollContainer = getClickDispatchScrollContainerDiagnostic(result);
-	const targetLabel = "no trusted DOM event reached the selected element";
-	const summary = scrollContainer
-		? `Upstream click reported success but ${targetLabel}. ${scrollContainer.summary}`
-		: `Upstream click reported success but ${targetLabel}. 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",
-		...(scrollContainer ? { scrollContainer } : {}),
-		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);
-}