pi-agent-browser-native 0.2.31 → 0.2.32

package/extensions/agent-browser/lib/electron/launch.ts

@@ -0,0 +1,553 @@
+/**
+ * Purpose: Launch wrapper-owned Electron applications and discover their CDP endpoint.
+ * Responsibilities: Resolve Electron targets, enforce caller-owned allow/deny policy, create isolated userDataDir profiles, launch with remote debugging on an OS-chosen port, poll DevToolsActivePort, and read bounded CDP version/target metadata.
+ * Scope: Host-side Electron lifecycle setup only; upstream agent-browser attach/presentation stays in the extension entrypoint.
+ * Usage: Called by the agent_browser electron.launch shorthand before routing through upstream `connect`.
+ * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, and never accepts a caller-supplied remote debugging port.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import {
+	discoverElectronApps,
+	inspectElectronAppPath,
+	inspectElectronExecutablePath,
+	type ElectronAppDiscovery,
+} from "./discovery.js";
+import { createSecureTempDirectory } from "../temp.js";
+
+export const ELECTRON_LAUNCH_RECORD_VERSION = 1;
+export const ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS = 15_000;
+export const ELECTRON_LAUNCH_MAX_TIMEOUT_MS = 120_000;
+
+const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
+export const ELECTRON_PROFILE_DIR_PREFIX = "electron-profile-";
+const ELECTRON_DEFAULT_APP_ARGS = ["--disable-extensions", "--no-first-run", "--no-default-browser-check"] as const;
+const ELECTRON_DEVTOOLS_POLL_INTERVAL_MS = 100;
+const ELECTRON_CDP_FETCH_TIMEOUT_MS = 1_000;
+
+export interface ElectronDevToolsActivePortRead {
+	error?: string;
+	found: boolean;
+	path: string;
+	port?: number;
+}
+
+export interface ElectronLaunchFailureDiagnostics {
+	cdpVersionReached?: boolean;
+	devToolsActivePort?: ElectronDevToolsActivePortRead;
+	elapsedMs?: number;
+	exitCode?: number | null;
+	exitSignal?: NodeJS.Signals | null;
+	outputCaptured: false;
+	pid?: number;
+	pidAlive?: boolean;
+	port?: number;
+	timeoutMs?: number;
+	userDataDir?: string;
+}
+
+export type ElectronLaunchCleanupState = "active" | "cleaned" | "dead" | "failed" | "partial";
+export type ElectronLaunchFailureReason =
+	| "non-electron-target"
+	| "policy-blocked"
+	| "port-not-found"
+	| "single-instance-conflict"
+	| "spawn-error"
+	| "timeout";
+
+export interface ElectronCdpVersion {
+	browser?: string;
+	protocolVersion?: string;
+	userAgent?: string;
+	v8Version?: string;
+	webKitVersion?: string;
+	webSocketDebuggerUrl?: string;
+}
+
+export interface ElectronCdpTarget {
+	id?: string;
+	title?: string;
+	type?: string;
+	url?: string;
+	webSocketDebuggerUrl?: string;
+}
+
+export interface ElectronLaunchRecord {
+	appName: string;
+	appPath?: string;
+	bundleId?: string;
+	cleanupState: ElectronLaunchCleanupState;
+	createdAtMs: number;
+	desktopId?: string;
+	executablePath: string;
+	launchId: string;
+	launchedByWrapper: true;
+	packageSource?: string;
+	pid?: number;
+	platform?: string;
+	port: number;
+	processGroupId?: number;
+	sessionName?: string;
+	targetType?: "any" | "page" | "webview";
+	userDataDir: string;
+	version: typeof ELECTRON_LAUNCH_RECORD_VERSION;
+	webSocketDebuggerUrl?: string;
+}
+
+export interface ElectronPolicyBlock {
+	entry?: string;
+	list: "allow" | "deny";
+	message: string;
+}
+
+export interface ElectronLaunchSuccess {
+	appArgs: string[];
+	child: ChildProcess;
+	connectArg: string;
+	record: ElectronLaunchRecord;
+	target: ElectronAppDiscovery;
+	targets: ElectronCdpTarget[];
+	version: ElectronCdpVersion;
+}
+
+export interface ElectronLaunchFailure {
+	appArgs: string[];
+	cleanupError?: string;
+	diagnostics?: ElectronLaunchFailureDiagnostics;
+	error: string;
+	policy?: ElectronPolicyBlock;
+	reason: ElectronLaunchFailureReason;
+	target?: ElectronAppDiscovery;
+	userDataDir?: string;
+}
+
+export type ElectronLaunchResult = { ok: true; value: ElectronLaunchSuccess } | { ok: false; failure: ElectronLaunchFailure };
+
+export interface ResolveElectronTargetOptions {
+	appName?: string;
+	appPath?: string;
+	bundleId?: string;
+	executablePath?: string;
+}
+
+function normalizeTimeoutMs(timeoutMs: number | undefined): number {
+	if (!Number.isSafeInteger(timeoutMs) || (timeoutMs ?? 0) <= 0) return ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS;
+	return Math.min(timeoutMs as number, ELECTRON_LAUNCH_MAX_TIMEOUT_MS);
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeIdentifier(value: string | undefined): string | undefined {
+	const trimmed = value?.trim().toLowerCase();
+	return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+
+function appIdentifiers(app: ElectronAppDiscovery): string[] {
+	return [app.name, app.bundleId, app.desktopId, app.appPath, app.executablePath]
+		.filter((value): value is string => typeof value === "string" && value.trim().length > 0);
+}
+
+function policyEntryMatchesApp(entry: string, app: ElectronAppDiscovery): boolean {
+	const normalizedEntry = normalizeIdentifier(entry);
+	if (!normalizedEntry) return false;
+	return appIdentifiers(app).some((identifier) => identifier.toLowerCase().includes(normalizedEntry));
+}
+
+export function evaluateElectronLaunchPolicy(options: {
+	allow?: string[];
+	deny?: string[];
+	target: ElectronAppDiscovery;
+}): ElectronPolicyBlock | undefined {
+	const denyEntry = options.deny?.find((entry) => policyEntryMatchesApp(entry, options.target));
+	if (denyEntry) {
+		return {
+			entry: denyEntry,
+			list: "deny",
+			message: `Electron launch blocked by caller deny policy: ${denyEntry}`,
+		};
+	}
+	if (options.allow && options.allow.length > 0) {
+		const allowEntry = options.allow.find((entry) => policyEntryMatchesApp(entry, options.target));
+		if (!allowEntry) {
+			return {
+				list: "allow",
+				message: "Electron launch blocked because the resolved app did not match caller allow policy.",
+			};
+		}
+	}
+	return undefined;
+}
+
+export async function resolveElectronLaunchTarget(options: ResolveElectronTargetOptions): Promise<ElectronAppDiscovery | undefined> {
+	if (options.appPath) return inspectElectronAppPath(options.appPath);
+	if (options.executablePath) return inspectElectronExecutablePath(options.executablePath);
+	const query = options.bundleId ?? options.appName;
+	const discovery = await discoverElectronApps({ maxResults: 200, query });
+	if (options.bundleId) {
+		const normalizedBundleId = normalizeIdentifier(options.bundleId);
+		return discovery.apps.find((app) => normalizeIdentifier(app.bundleId) === normalizedBundleId);
+	}
+	if (options.appName) {
+		const normalizedName = normalizeIdentifier(options.appName);
+		return discovery.apps.find((app) => normalizeIdentifier(app.name) === normalizedName) ?? discovery.apps[0];
+	}
+	return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function parseCdpVersion(value: unknown): ElectronCdpVersion | undefined {
+	if (!isRecord(value)) return undefined;
+	return {
+		browser: asString(value.Browser) ?? asString(value.browser),
+		protocolVersion: asString(value["Protocol-Version"]) ?? asString(value.protocolVersion),
+		userAgent: asString(value["User-Agent"]) ?? asString(value.userAgent),
+		v8Version: asString(value["V8-Version"]) ?? asString(value.v8Version),
+		webKitVersion: asString(value["WebKit-Version"]) ?? asString(value.webKitVersion),
+		webSocketDebuggerUrl: asString(value.webSocketDebuggerUrl),
+	};
+}
+
+function parseCdpTargets(value: unknown): ElectronCdpTarget[] {
+	if (!Array.isArray(value)) return [];
+	return value.filter(isRecord).map((target) => ({
+		id: asString(target.id),
+		title: asString(target.title),
+		type: asString(target.type),
+		url: asString(target.url),
+		webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
+	}));
+}
+
+function targetMatchesType(target: ElectronCdpTarget, targetType: "any" | "page" | "webview" | undefined): boolean {
+	return targetType === undefined || targetType === "any" || target.type === targetType;
+}
+
+function selectElectronConnectArg(options: {
+	port: number;
+	targets: ElectronCdpTarget[];
+	targetType?: "any" | "page" | "webview";
+	version: ElectronCdpVersion;
+}): string {
+	const targetWebSocket = options.targets.find((target) => targetMatchesType(target, options.targetType) && target.webSocketDebuggerUrl)?.webSocketDebuggerUrl;
+	return targetWebSocket ?? options.version.webSocketDebuggerUrl ?? String(options.port);
+}
+
+async function fetchJson(url: string): Promise<unknown | undefined> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, { signal: controller.signal });
+		if (!response.ok) return undefined;
+		return await response.json() as unknown;
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+async function readDevToolsActivePort(userDataDir: string): Promise<ElectronDevToolsActivePortRead> {
+	const path = `${userDataDir}/${DEVTOOLS_ACTIVE_PORT_FILE}`;
+	try {
+		const text = await readFile(path, "utf8");
+		const [portLine] = text.split(/\r?\n/);
+		const port = Number(portLine?.trim());
+		return {
+			found: true,
+			path,
+			port: Number.isSafeInteger(port) && port > 0 && port <= 65_535 ? port : undefined,
+			...(Number.isSafeInteger(port) && port > 0 && port <= 65_535 ? {} : { error: "DevToolsActivePort did not contain a valid TCP port." }),
+		};
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		return {
+			error: code && code !== "ENOENT" ? `${code}: ${error instanceof Error ? error.message : String(error)}` : undefined,
+			found: false,
+			path,
+		};
+	}
+}
+
+async function pollDevToolsActivePort(options: {
+	deadlineMs: number;
+	getChildExit: () => { code: number | null; signal: NodeJS.Signals | null };
+	getSpawnError: () => Error | undefined;
+	userDataDir: string;
+}): Promise<{ devToolsActivePort?: ElectronDevToolsActivePortRead; failure?: ElectronLaunchFailureReason; port?: number; spawnError?: Error }> {
+	let devToolsActivePort: ElectronDevToolsActivePortRead | undefined;
+	while (Date.now() <= options.deadlineMs) {
+		const spawnError = options.getSpawnError();
+		if (spawnError) return { devToolsActivePort, failure: "spawn-error", spawnError };
+		devToolsActivePort = await readDevToolsActivePort(options.userDataDir);
+		if (devToolsActivePort.port) return { devToolsActivePort, port: devToolsActivePort.port };
+		const exit = options.getChildExit();
+		if (exit.code !== null || exit.signal !== null) {
+			return { devToolsActivePort, failure: exit.code === 0 ? "single-instance-conflict" : "spawn-error" };
+		}
+		await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);
+	}
+	return { devToolsActivePort, failure: "timeout" };
+}
+
+async function pollCdpMetadata(port: number, deadlineMs: number): Promise<{ targets: ElectronCdpTarget[]; version: ElectronCdpVersion } | undefined> {
+	while (Date.now() <= deadlineMs) {
+		const version = parseCdpVersion(await fetchJson(`http://127.0.0.1:${port}/json/version`));
+		if (version) {
+			const targets = parseCdpTargets(await fetchJson(`http://127.0.0.1:${port}/json/list`));
+			return { targets, version };
+		}
+		await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);
+	}
+	return undefined;
+}
+
+function buildLaunchArgs(userDataDir: string, appArgs: string[]): string[] {
+	return [
+		...appArgs,
+		`--user-data-dir=${userDataDir}`,
+		"--remote-debugging-port=0",
+		...ELECTRON_DEFAULT_APP_ARGS,
+	];
+}
+
+async function waitForLaunchChildExit(child: ChildProcess, deadlineMs: number): Promise<boolean> {
+	while (Date.now() <= deadlineMs) {
+		if (child.exitCode !== null || child.signalCode !== null) return true;
+		await sleep(50);
+	}
+	return child.exitCode !== null || child.signalCode !== null;
+}
+
+function isLaunchChildPidAlive(child: ChildProcess): boolean | undefined {
+	if (!child.pid) return undefined;
+	if (child.exitCode !== null || child.signalCode !== null) return false;
+	try {
+		process.kill(child.pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+async function terminateLaunchChild(child: ChildProcess): Promise<string | undefined> {
+	if (!child.pid || child.exitCode !== null || child.signalCode !== null) return undefined;
+	try {
+		child.kill("SIGTERM");
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	if (await waitForLaunchChildExit(child, Date.now() + 1_000)) return undefined;
+	try {
+		child.kill("SIGKILL");
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	if (await waitForLaunchChildExit(child, Date.now() + 1_000)) return undefined;
+	return `PID ${child.pid} remained alive after failed Electron launch cleanup.`;
+}
+
+function buildLaunchRecord(options: {
+	createdAtMs: number;
+	pid?: number;
+	port: number;
+	target: ElectronAppDiscovery;
+	targetType?: "any" | "page" | "webview";
+	userDataDir: string;
+	version: ElectronCdpVersion;
+}): ElectronLaunchRecord {
+	return {
+		appName: options.target.name,
+		appPath: options.target.appPath,
+		bundleId: options.target.bundleId,
+		cleanupState: "active",
+		createdAtMs: options.createdAtMs,
+		desktopId: options.target.desktopId,
+		executablePath: options.target.executablePath,
+		launchId: `electron-${randomUUID()}`,
+		launchedByWrapper: true,
+		packageSource: options.target.packageSource,
+		pid: options.pid,
+		platform: options.target.platform,
+		port: options.port,
+		processGroupId: process.platform === "win32" ? undefined : options.pid,
+		targetType: options.targetType,
+		userDataDir: options.userDataDir,
+		version: ELECTRON_LAUNCH_RECORD_VERSION,
+		webSocketDebuggerUrl: options.version.webSocketDebuggerUrl,
+	};
+}
+
+function launchFailureMessage(reason: ElectronLaunchFailureReason, target: ElectronAppDiscovery | undefined, detail?: string): string {
+	const label = target ? `${target.name} (${target.appPath ?? target.executablePath})` : "target";
+	switch (reason) {
+		case "non-electron-target":
+			return `Electron launch rejected: ${label} does not have Electron framework evidence.`;
+		case "policy-blocked":
+			return detail ?? `Electron launch blocked by caller policy for ${label}.`;
+		case "single-instance-conflict":
+			return `Electron launch did not expose a debug port for ${label}; the app may already be running as a single-instance Electron app. Quit the running app and retry.`;
+		case "port-not-found":
+			return `Electron launch found a DevToolsActivePort for ${label}, but /json/version never returned a valid CDP payload.`;
+		case "spawn-error":
+			return `Electron launch failed while starting ${label}${detail ? `: ${detail}` : "."}`;
+		case "timeout":
+			return `Electron launch timed out waiting for DevToolsActivePort for ${label}.`;
+	}
+}
+
+export async function launchElectronApp(options: {
+	allow?: string[];
+	appArgs?: string[];
+	deny?: string[];
+	appName?: string;
+	appPath?: string;
+	bundleId?: string;
+	executablePath?: string;
+	targetType?: "any" | "page" | "webview";
+	timeoutMs?: number;
+}): Promise<ElectronLaunchResult> {
+	const appArgs = options.appArgs ?? [];
+	const target = await resolveElectronLaunchTarget(options);
+	if (!target) {
+		return {
+			ok: false,
+			failure: {
+				appArgs,
+				error: launchFailureMessage("non-electron-target", undefined),
+				reason: "non-electron-target",
+			},
+		};
+	}
+
+	const policy = evaluateElectronLaunchPolicy({ allow: options.allow, deny: options.deny, target });
+	if (policy) {
+		return {
+			ok: false,
+			failure: {
+				appArgs,
+				error: launchFailureMessage("policy-blocked", target, policy.message),
+				policy,
+				reason: "policy-blocked",
+				target,
+			},
+		};
+	}
+
+	const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+	const startedAtMs = Date.now();
+	const deadlineMs = startedAtMs + timeoutMs;
+	const userDataDir = await createSecureTempDirectory(ELECTRON_PROFILE_DIR_PREFIX);
+	let cleanupError: string | undefined;
+	let spawnError: Error | undefined;
+	let exitCode: number | null = null;
+	let exitSignal: NodeJS.Signals | null = null;
+	const args = buildLaunchArgs(userDataDir, appArgs);
+	const child = spawn(target.executablePath, args, {
+		cwd: dirname(target.executablePath),
+		detached: process.platform !== "win32",
+		stdio: "ignore",
+	});
+	child.once("error", (error) => {
+		spawnError = error;
+	});
+	child.once("exit", (code, signal) => {
+		exitCode = code;
+		exitSignal = signal;
+	});
+	child.unref();
+
+	const buildFailureDiagnostics = (options: {
+		cdpVersionReached?: boolean;
+		devToolsActivePort?: ElectronDevToolsActivePortRead;
+		port?: number;
+	} = {}): ElectronLaunchFailureDiagnostics => ({
+		cdpVersionReached: options.cdpVersionReached,
+		devToolsActivePort: options.devToolsActivePort,
+		elapsedMs: Math.max(0, Date.now() - startedAtMs),
+		exitCode,
+		exitSignal,
+		outputCaptured: false,
+		pid: child.pid,
+		pidAlive: isLaunchChildPidAlive(child),
+		port: options.port ?? options.devToolsActivePort?.port,
+		timeoutMs,
+		userDataDir,
+	});
+
+	const fail = async (reason: ElectronLaunchFailureReason, detail?: string, diagnosticOptions?: Parameters<typeof buildFailureDiagnostics>[0]): Promise<ElectronLaunchResult> => {
+		const diagnostics = buildFailureDiagnostics(diagnosticOptions);
+		const processCleanupError = await terminateLaunchChild(child);
+		try {
+			await rm(userDataDir, { force: true, recursive: true });
+		} catch (error) {
+			cleanupError = error instanceof Error ? error.message : String(error);
+		}
+		cleanupError = [processCleanupError, cleanupError].filter((value): value is string => value !== undefined).join("; ") || undefined;
+		return {
+			ok: false,
+			failure: {
+				appArgs,
+				cleanupError,
+				diagnostics,
+				error: launchFailureMessage(reason, target, detail),
+				reason,
+				target,
+				userDataDir,
+			},
+		};
+	};
+
+	const portResult = await pollDevToolsActivePort({
+		deadlineMs,
+		getChildExit: () => ({ code: exitCode, signal: exitSignal }),
+		getSpawnError: () => spawnError,
+		userDataDir,
+	});
+	if (!portResult.port) {
+		return fail(portResult.failure ?? "timeout", portResult.spawnError?.message, { devToolsActivePort: portResult.devToolsActivePort });
+	}
+	const metadata = await pollCdpMetadata(portResult.port, deadlineMs);
+	if (!metadata) {
+		return fail("port-not-found", undefined, { cdpVersionReached: false, devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
+	}
+	const record = buildLaunchRecord({
+		createdAtMs: Date.now(),
+		pid: child.pid,
+		port: portResult.port,
+		target,
+		targetType: options.targetType,
+		userDataDir,
+		version: metadata.version,
+	});
+	const connectArg = selectElectronConnectArg({
+		port: portResult.port,
+		targets: metadata.targets,
+		targetType: options.targetType,
+		version: metadata.version,
+	});
+	return {
+		ok: true,
+		value: {
+			appArgs,
+			child,
+			connectArg,
+			record,
+			target,
+			targets: metadata.targets,
+			version: metadata.version,
+		},
+	};
+}

package/extensions/agent-browser/lib/playbook.ts

@@ -18,11 +18,11 @@ export function buildInstalledDocsGuideline(paths: { readmePath: string; command
 }
 
 export const QUICK_START_GUIDELINES = [
-	"Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin shorthand compiled to find argv for locator actions or select argv for native dropdowns), job (a constrained short-workflow schema compiled to batch), qa (a lightweight QA preset built on job/batch), or the experimental sourceLookup / networkSourceLookup helpers (each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and other command/stdin combinations are rejected before launch; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device state.",
+	"Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin shorthand compiled to find argv for locator actions or select argv for native dropdowns), job (a constrained short-workflow schema compiled to batch), qa (a lightweight QA preset built on job/batch, including qa.attached for current sessions), electron (desktop Electron list/launch/status/cleanup/probe), or the experimental sourceLookup / networkSourceLookup helpers (each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and is rejected with electron; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device state.",
 	"There is no first-class reusable named browser recipe runtime above top-level job, the qa preset, and raw batch stdin; keep recurring flows in documentation examples or those inputs (closed RQ-0068; see docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet).",
 	"Common first calls: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
 	"Locator-first clicks/fills and native select changes without hand-building argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } }, { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }, or { semanticAction: { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } }; add semanticAction.session when targeting a named upstream browser session; details.compiledSemanticAction shows the semantic target, while details.effectiveArgs may show a resolved current @ref for active-session role/name click/check/uncheck actions to avoid hidden duplicate matches; selector-not-found failures may append bounded try-*-candidate next actions (and an Agent-browser candidate fallbacks prose block) for specific placeholder/text/label shapes, and stale-ref failures can return retry-semantic-action-after-stale-ref for compiled find actions when retry safety is provable.",
-	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { job: { steps: [{ action: \"open\", url: \"https://example.com\" }, { action: \"assertText\", text: \"Example Domain\" }, { action: \"screenshot\", path: \".dogfood/example.png\" }] } }, { qa: { url: \"https://example.com\", expectedText: \"Example Domain\", screenshotPath: \".dogfood/qa-example.png\" } }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, { args: [\"auth\", \"save\", \"name\", \"--password-stdin\"], stdin: \"<password from user-approved secret source>\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], sessionMode: \"fresh\" }. For app pages with a native dropdown, job steps can include { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } before the dependent assertion.",
+	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { job: { steps: [{ action: \"open\", url: \"https://example.com\" }, { action: \"assertText\", text: \"Example Domain\" }, { action: \"screenshot\", path: \".dogfood/example.png\" }] } }, { qa: { url: \"https://example.com\", expectedText: \"Example Domain\", screenshotPath: \".dogfood/qa-example.png\" } }, { electron: { action: \"list\", query: \"code\" } }, { electron: { action: \"launch\", appName: \"Visual Studio Code\", handoff: \"snapshot\" } }, { electron: { action: \"probe\" } }, { qa: { attached: true, expectedText: \"Explorer\" } }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, { args: [\"auth\", \"save\", \"name\", \"--password-stdin\"], stdin: \"<password from user-approved secret source>\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], sessionMode: \"fresh\" }. For app pages with a native dropdown, job steps can include { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } before the dependent assertion.",
 	"High-value command reference: select <selector> <value...> changes native dropdown values; download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree/inspect/renders/suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation.",
 	"For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step.",
 	"When details.nextActions is present, prefer those exact native agent_browser follow-up payloads over prose guidance; they may include args, stdin, sessionMode, networkSourceLookup, safety notes, or artifactPath for saved files.",
@@ -46,6 +46,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"For stateful browser context work, prefer purpose-specific page actions before dumping browser data: use auth save --password-stdin with the tool stdin field for credentials, state save/load for portable test state, cookies get/set/clear and storage local|session only when the task needs those values, and expect cookie/storage/auth/state summaries to redact credential-like fields.",
 	"For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command, redacted result or scrubbed error text) built from the same presentation rules as standalone calls.",
 	"For non-core families, pass current upstream commands through the native tool directly: network route/requests/har, diff snapshot/screenshot/url, trace/profiler/record, console/errors/highlight/inspect/clipboard, stream enable/disable/status, dashboard start/stop, and chat. For compact network requests output, prefer details.nextActions for request detail, actionable failed-request networkSourceLookup, filtering, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done.",
+	"For Electron desktop apps, prefer top-level electron for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: \"tabs\" is the safer diagnostic starting point, use electron.probe or snapshot -i/qa.attached for current-session state, and always cleanup the returned launchId when done. electron.launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; leave shutdown/profile cleanup to the host owner.",
 	"For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox through the native tool. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.",
 	"For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; when --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.",
 	"If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load <state>, --url <matcher>, --fn <js>, or --text <matcher>.",
@@ -90,12 +91,12 @@ export function buildSharedBrowserPlaybookGuidelines(options: { includeBraveSear
 }
 
 const RUNTIME_PROMPT_GUIDELINES = [
-	"Use exactly one input mode: args, semanticAction, job, qa, sourceLookup, or networkSourceLookup. Use stdin only for batch, eval --stdin, auth save --password-stdin, or wrapper-generated batch modes.",
+	"Use exactly one input mode: args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron. Use stdin only for batch, eval --stdin, auth save --password-stdin, or wrapper-generated batch modes; electron rejects caller stdin.",
 	"Common flow: open, snapshot -i, interact with current @refs or semanticAction, then re-snapshot after navigation, scrolling, rerenders, or DOM changes. For ordinary forms, batch same-snapshot fill @refs before the submit/click step; split if a fill may autosubmit, navigate, or rerender later fields. Respect explicit stop boundaries: if the user says to stop before order/post/purchase/submit, do not click that final action.",
 	"Prefer stable locators for visible text/names: semanticAction or upstream find with role/text/label/placeholder/alt/title/testid. For native selects, prefer select <selector> <value...> or semanticAction/job select over clicking option refs. Use current @refs only from the latest same-page snapshot.",
-	"For tasks that explicitly require the user's signed-in/account-specific content, start with --profile Default plus sessionMode=fresh unless the user asks otherwise; visible page content is model-visible. Use sessionMode=fresh for other launch-scoped state such as --session-name, --cdp, --state, --auto-connect, --init-script, --enable, providers, or iOS devices; otherwise let the implicit session carry continuity.",
-	"For requested screenshots, recordings, downloads, PDFs, or HARs, save the exact user path and read details.artifactVerification before claiming success; report unavailable/missing artifacts instead of silently substituting paths. record stop needs ffmpeg on PATH. close does not delete saved files; cleanup is host-owned.",
-	"When details.nextActions is present, prefer those exact follow-up payloads over prose or guessed selectors; network request diagnostics may include request-detail, actionable failed-request networkSourceLookup, filter, or HAR-capture follow-ups.",
+	"For signed-in/account-specific content on the web, start with --profile Default plus sessionMode=fresh unless asked otherwise; visible content is model-visible. For desktop/local Electron apps, use electron.list first, not web open; electron.launch is isolated. For signed-in desktop content, if not running, host-launch with --remote-debugging-port then agent_browser connect; if running without a port, ask before relaunch. Use sessionMode=fresh for other launch-scoped state; otherwise keep implicit continuity.",
+	"For requested screenshots, recordings, downloads, PDFs, or HARs, save the exact user path and read details.artifactVerification before claiming success; report unavailable/missing artifacts instead of silently substituting paths. record stop needs ffmpeg on PATH. close does not delete saved files; cleanup is host-owned. Electron cleanup only covers wrapper-launched Electron processes/profiles for the returned launchId, not explicit artifacts or externally launched apps.",
+	"When details.nextActions is present, prefer those exact follow-up payloads over prose or guessed selectors; network request diagnostics may include request-detail, actionable failed-request networkSourceLookup, filter, or HAR-capture follow-ups, and Electron lifecycle results may include status/cleanup/tab/snapshot actions keyed to the wrapper launchId/session.",
 	"For dense snapshots, check Omitted high-value controls and details.data.highValueControlRefIds before opening large spill files.",
 	"For dashboards, verify scroll with screenshot/snapshot; if nothing moved, use scrollintoview <@ref> or target the real scroll region. For native selects use select/semanticAction/job select instead of option refs; custom combobox clicks may only focus, so re-snapshot and fall back to type, Enter/arrows, or visible option refs.",
 	"For extraction, prefer get title/url/text/html/value/attr/count or eval --stdin with a plain expression in the tool stdin field; do not rely on console.log. When reading several known refs/selectors, use batch with JSON-array stdin (for example [[\"get\",\"text\",\"@e1\"]]) or eval --stdin instead of many serial get calls. If selector visibility warnings appear, prefer visible @refs or nextActions.",

package/extensions/agent-browser/lib/results/presentation.ts

@@ -1704,6 +1704,33 @@ function buildUnknownCommandSuggestionActions(suggestions: CommandSuggestion[],
 	return actions.length > 0 ? actions : undefined;
 }
 
+function isWaitTextAssertionCommand(command: string[] | undefined): boolean {
+	return command?.[0] === "wait" && command.includes("--text");
+}
+
+function buildWaitTextAssertionFailureNextAction(sessionName: string | undefined): AgentBrowserNextAction {
+	return {
+		id: "inspect-after-text-assertion-failure",
+		params: { args: withSessionPrefix(sessionName, ["snapshot", "-i"]) },
+		reason: "Inspect the current page after the text assertion failed before concluding the expected text is absent.",
+		safety: "Read-only snapshot; use current refs or visible text from this page before retrying the assertion.",
+		tool: "agent_browser",
+	};
+}
+
+function mergePresentationNextActions(...groups: Array<AgentBrowserNextAction[] | undefined>): AgentBrowserNextAction[] | undefined {
+	const actions: AgentBrowserNextAction[] = [];
+	const seen = new Set<string>();
+	for (const group of groups) {
+		for (const action of group ?? []) {
+			if (seen.has(action.id)) continue;
+			actions.push(action);
+			seen.add(action.id);
+		}
+	}
+	return actions.length > 0 ? actions : undefined;
+}
+
 function appendSelectorRecoveryHint(errorText: string): string {
 	const hint = getSelectorRecoveryHint(errorText);
 	if (!hint || errorText.includes("Agent-browser hint:")) {
@@ -1785,13 +1812,16 @@ async function buildBatchStepPresentation(options: {
 			errorText,
 		});
 		const confirmationRequired = detectConfirmationRequired(item.error);
-		const nextActions = buildAgentBrowserNextActions({
-			args: command,
-			command: command?.[0],
-			confirmationId: confirmationRequired?.id,
-			failureCategory,
-			resultCategory: "failure",
-		});
+		const nextActions = mergePresentationNextActions(
+			buildAgentBrowserNextActions({
+				args: command,
+				command: command?.[0],
+				confirmationId: confirmationRequired?.id,
+				failureCategory,
+				resultCategory: "failure",
+			}),
+			isWaitTextAssertionCommand(command) ? [buildWaitTextAssertionFailureNextAction(sessionName)] : undefined,
+		);
 		const presentation: ToolPresentation = {
 			content: [{ type: "text", text: errorText }],
 			failureCategory,