@f5-sales-demo/xcsh 19.51.2

package/src/browser/extension-provider.ts

@@ -0,0 +1,373 @@
+import { type AxNode, matchNode } from "./ax";
+import { type BridgeServer, startBridgeServer, type ToolResult } from "./extension-bridge";
+import { ExtensionPageActions } from "./extension-page-actions";
+import type { AcquiredBrowser, BrowserProvider, BrowserProviderStatus } from "./provider";
+import { parseLocator } from "./selector";
+
+/** The extension's AX tree shape: an {@link AxNode} carrying a `ref` handle. */
+export type AxRefNode = AxNode & { ref?: string; children?: AxRefNode[] };
+
+/**
+ * Pure adapter: resolve a selector to the extension's `ref` handle by reusing
+ * xcsh's existing AX matcher. Throws if nothing matches (via {@link matchNode})
+ * or the matched node carries no `ref`.
+ */
+export function resolveRef(tree: AxRefNode, selector: string): string {
+	const node = matchNode(tree as AxNode, parseLocator(selector)) as AxRefNode;
+	if (!node.ref) throw new Error(`matched node for "${selector}" has no ref handle`);
+	return node.ref;
+}
+
+/** Thin wrapper over the bridge for the page-level operations the agent needs. */
+export interface ExtensionPage {
+	navigate(url: string): Promise<void>;
+	login(
+		email: string,
+		password: string,
+		consoleUrl: string,
+	): Promise<{ loggedIn: boolean; finalUrl: string; steps: string[] }>;
+	readAx(): Promise<AxRefNode>;
+	click(ref: string): Promise<void>;
+	screenshot(): Promise<string>;
+	// Phase 1 additions:
+	formInput(ref: string, value: string): Promise<void>;
+	keyPress(key: string): Promise<void>;
+	selectOption(ref: string, value: string): Promise<void>;
+	scrollTo(ref: string): Promise<void>;
+	waitFor(selector: string, context?: string, timeoutMs?: number): Promise<string>;
+	assertText(selector: string, expected: string, context?: string): Promise<void>;
+	find(selector: string): Promise<Array<{ ref: string; role: string; name: string }>>;
+	getPageText(): Promise<string>;
+	javascriptTool(code: string): Promise<unknown>;
+	tabsList(): Promise<Array<{ id: number; url: string; title: string; active: boolean }>>;
+	tabsCreate(url: string): Promise<number>;
+	tabsClose(tabId: number): Promise<void>;
+	resizeWindow(width: number, height: number): Promise<void>;
+	readConsole(pattern?: string): Promise<Array<{ type: string; text: string }>>;
+	readNetwork(pattern?: string): Promise<Array<{ method: string; url: string; status?: number }>>;
+	fileUpload(ref: string, files: Array<{ data: string; name: string; mimeType: string }>): Promise<void>;
+	browserBatch(
+		actions: Array<{ tool: string; params: unknown }>,
+	): Promise<Array<{ tool: string; content: unknown; is_error: boolean }>>;
+	/** Trusted CDP click at viewport coordinates. Last-resort primitive for points
+	 * with no backing element (e.g. a computed portal point); prefer clickElement. */
+	clickXy(x: number, y: number): Promise<void>;
+	/** Deterministic click: `js` is an expression returning an Element (or null).
+	 * The extension derives the clickable point from the renderer's layout
+	 * (DOM.getContentQuads) and hit-tests it (document.elementFromPoint) before
+	 * dispatching — no JS getBoundingClientRect, no silent mis-clicks. `waitMs`
+	 * polls for the element (async portals). Throws loudly on occlusion. */
+	clickElement(js: string, waitMs?: number): Promise<{ x: number; y: number; hit: boolean }>;
+	/** CDP Input.insertText into the focused element (genuine trusted input events). */
+	typeText(text: string): Promise<void>;
+	/** Atomically type into a CDK-portal typeahead + click the matching option.
+	 * Keeps the input focused throughout (uses plain Runtime.evaluate, not the
+	 * evaluateWithRecovery path that defocuses by detaching the debugger). */
+	labelSelect(
+		selector: string,
+		value: string,
+		waitMs?: number,
+	): Promise<{
+		selected: string;
+		matchedKind: string;
+		value: string;
+		optionCount: number;
+	}>;
+}
+
+/** Unwrap a {@link ToolResult}, throwing on the error flag. */
+function unwrap(result: ToolResult, tool: string): unknown {
+	if (result.is_error) {
+		throw new Error(`extension tool "${tool}" failed: ${JSON.stringify(result.content)}`);
+	}
+	return result.content;
+}
+
+class BridgeExtensionPage implements ExtensionPage {
+	#server: BridgeServer;
+
+	constructor(server: BridgeServer) {
+		this.#server = server;
+	}
+
+	async navigate(url: string): Promise<void> {
+		unwrap(await this.#server.request("navigate", { url }), "navigate");
+	}
+
+	async login(
+		email: string,
+		password: string,
+		consoleUrl: string,
+	): Promise<{ loggedIn: boolean; finalUrl: string; steps: string[] }> {
+		// Defense-in-depth: validate the console URL before sending credentials
+		// over the bridge — only https F5 XC console domains are allowed, so a
+		// bad consoleUrl can never carry credentials to a foreign host.
+		const parsed = new URL(consoleUrl); // throws on malformed
+		if (parsed.protocol !== "https:") {
+			throw new Error(`login: consoleUrl must use https, got ${parsed.protocol}`);
+		}
+		if (!/\.volterra\.us$|\.console\.ves\.volterra\.io$/.test(parsed.hostname)) {
+			throw new Error(`login: consoleUrl host "${parsed.hostname}" is not an allowed F5 XC console domain`);
+		}
+		return unwrap(
+			await this.#server.request("login", { email, password, consoleUrl: parsed.toString() }, 90_000),
+			"login",
+		) as { loggedIn: boolean; finalUrl: string; steps: string[] };
+	}
+
+	async readAx(): Promise<AxRefNode> {
+		return unwrap(await this.#server.request("read_ax", {}), "read_ax") as AxRefNode;
+	}
+
+	async click(ref: string): Promise<void> {
+		unwrap(await this.#server.request("click", { ref }), "click");
+	}
+
+	async screenshot(): Promise<string> {
+		return unwrap(await this.#server.request("screenshot", {}), "screenshot") as string;
+	}
+
+	async formInput(ref: string, value: string): Promise<void> {
+		unwrap(await this.#server.request("form_input", { ref, value }), "form_input");
+	}
+
+	async keyPress(key: string): Promise<void> {
+		unwrap(await this.#server.request("key_press", { key }), "key_press");
+	}
+
+	async selectOption(ref: string, value: string): Promise<void> {
+		unwrap(await this.#server.request("select_option", { ref, value }), "select_option");
+	}
+
+	async scrollTo(ref: string): Promise<void> {
+		unwrap(await this.#server.request("scroll_to", { ref }), "scroll_to");
+	}
+
+	async waitFor(selector: string, context?: string, timeoutMs?: number): Promise<string> {
+		return unwrap(await this.#server.request("wait_for", { selector, context, timeoutMs }), "wait_for") as string;
+	}
+
+	async assertText(selector: string, expected: string, context?: string): Promise<void> {
+		unwrap(await this.#server.request("assert_text", { selector, expected, context }), "assert_text");
+	}
+
+	async find(selector: string): Promise<Array<{ ref: string; role: string; name: string }>> {
+		return unwrap(await this.#server.request("find", { selector }), "find") as Array<{
+			ref: string;
+			role: string;
+			name: string;
+		}>;
+	}
+
+	async getPageText(): Promise<string> {
+		return unwrap(await this.#server.request("get_page_text", {}), "get_page_text") as string;
+	}
+
+	async javascriptTool(code: string): Promise<unknown> {
+		return unwrap(await this.#server.request("javascript_tool", { code }), "javascript_tool");
+	}
+
+	async tabsList(): Promise<Array<{ id: number; url: string; title: string; active: boolean }>> {
+		return unwrap(await this.#server.request("tabs_list", {}), "tabs_list") as Array<{
+			id: number;
+			url: string;
+			title: string;
+			active: boolean;
+		}>;
+	}
+
+	async tabsCreate(url: string): Promise<number> {
+		return unwrap(await this.#server.request("tabs_create", { url }), "tabs_create") as number;
+	}
+
+	async tabsClose(tabId: number): Promise<void> {
+		unwrap(await this.#server.request("tabs_close", { tabId }), "tabs_close");
+	}
+
+	async resizeWindow(width: number, height: number): Promise<void> {
+		unwrap(await this.#server.request("resize_window", { width, height }), "resize_window");
+	}
+
+	async readConsole(pattern?: string): Promise<Array<{ type: string; text: string }>> {
+		return unwrap(await this.#server.request("read_console", { pattern }), "read_console") as Array<{
+			type: string;
+			text: string;
+		}>;
+	}
+
+	async readNetwork(pattern?: string): Promise<Array<{ method: string; url: string; status?: number }>> {
+		return unwrap(await this.#server.request("read_network", { pattern }), "read_network") as Array<{
+			method: string;
+			url: string;
+			status?: number;
+		}>;
+	}
+
+	async fileUpload(ref: string, files: Array<{ data: string; name: string; mimeType: string }>): Promise<void> {
+		unwrap(await this.#server.request("file_upload", { ref, files }), "file_upload");
+	}
+
+	async browserBatch(
+		actions: Array<{ tool: string; params: unknown }>,
+	): Promise<Array<{ tool: string; content: unknown; is_error: boolean }>> {
+		return unwrap(await this.#server.request("browser_batch", { actions }), "browser_batch") as Array<{
+			tool: string;
+			content: unknown;
+			is_error: boolean;
+		}>;
+	}
+
+	async clickXy(x: number, y: number): Promise<void> {
+		unwrap(await this.#server.request("click_xy", { x, y }), "click_xy");
+	}
+
+	async clickElement(js: string, waitMs?: number): Promise<{ x: number; y: number; hit: boolean }> {
+		const timeout = Math.max(30_000, (waitMs ?? 0) + 5_000);
+		return unwrap(await this.#server.request("click_element", { js, wait_ms: waitMs }, timeout), "click_element") as {
+			x: number;
+			y: number;
+			hit: boolean;
+		};
+	}
+
+	async typeText(text: string): Promise<void> {
+		unwrap(await this.#server.request("type_text", { text }), "type_text");
+	}
+
+	async labelSelect(
+		selector: string,
+		value: string,
+		waitMs?: number,
+	): Promise<{ selected: string; matchedKind: string; value: string; optionCount: number }> {
+		// Request timeout must exceed the handler's internal poll budget.
+		const timeout = Math.max(30_000, (waitMs ?? 8_000) + 5_000);
+		return unwrap(
+			await this.#server.request("label_select", { selector, value, wait_ms: waitMs }, timeout),
+			"label_select",
+		) as { selected: string; matchedKind: string; value: string; optionCount: number };
+	}
+}
+
+const CONNECT_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 100;
+
+/** Wait (bounded) for the extension to connect to the bridge server. */
+async function waitForConnection(server: BridgeServer, timeoutMs: number): Promise<void> {
+	if (server.connected) return;
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (server.connected) return;
+		await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+	}
+	if (!server.connected) {
+		throw new Error(
+			`extension did not connect within ${timeoutMs}ms — is the Chrome extension installed and running?`,
+		);
+	}
+}
+
+/**
+ * BrowserProvider that drives the page through the Chrome extension over the
+ * bridge socket. Acquires by ensuring the bridge is up, waiting for the
+ * extension to connect, pinging, and navigating to the console URL.
+ */
+export class ExtensionBrowserProvider implements BrowserProvider {
+	readonly name = "extension";
+	#server: BridgeServer | null;
+
+	constructor(opts?: { server?: BridgeServer }) {
+		this.#server = opts?.server ?? null;
+	}
+
+	/**
+	 * Acquire the extension-driven page. The returned `page` is an
+	 * {@link ExtensionPageActions} wrapping the runtime {@link ExtensionPage},
+	 * satisfying the {@link AcquiredBrowser.page} {@link PageActions} contract.
+	 * The extension seam substitutes a thin `ExtensionPage` for puppeteer's
+	 * `Page` behind the shared `PageActions` surface.
+	 */
+	async acquire(consoleUrl: string): Promise<AcquiredBrowser> {
+		const server = this.#server ?? (await startBridgeServer());
+		this.#server = server;
+		await waitForConnection(server, CONNECT_TIMEOUT_MS);
+		unwrap(await server.request("ping", {}), "ping");
+
+		const page: ExtensionPage = new BridgeExtensionPage(server);
+
+		// Auto-login: if XCSH_USERNAME + XCSH_CONSOLE_PASSWORD are available (set by
+		// ContextService from the context's env map), login automatically — the login
+		// tool handles "already authenticated" (instant return) so calling it every
+		// time is cheap and guarantees a valid session. Falls back to navigate-only
+		// (co-drive) if credentials aren't available.
+		const email = process.env.XCSH_USERNAME;
+		const password = process.env.XCSH_CONSOLE_PASSWORD;
+		if (email && password) {
+			await page.login(email, password, consoleUrl);
+		} else {
+			unwrap(await server.request("navigate", { url: consoleUrl }), "navigate");
+		}
+
+		return {
+			page: new ExtensionPageActions(page),
+			mode: "extension",
+			release: async () => {
+				await server.request("detach", {}).catch(() => {});
+			},
+		};
+	}
+
+	async status(): Promise<BrowserProviderStatus & { extensionConnected: boolean }> {
+		const extensionConnected = this.#server?.connected === true;
+		let detail: string;
+		if (extensionConnected) {
+			detail = "Chrome extension is connected to the xcsh bridge.";
+		} else if (chromeDeveloperModeEnabled() === false) {
+			// An unpacked (Load-unpacked) extension only runs while Chrome's
+			// Developer Mode is ON. If it's off, the extension is loaded but inert,
+			// so it never connects — surface that specific, common cause.
+			detail =
+				"Chrome extension is not connected — Chrome Developer Mode appears to be OFF, so the unpacked xcsh extension won't run. Enable it: chrome://extensions → toggle 'Developer mode' (top-right), then reload the extension.";
+		} else {
+			detail =
+				"Chrome extension is not connected — ensure it's loaded/enabled, Chrome is running, and `xcsh chrome setup` has run.";
+		}
+		return {
+			debuggableNow: false,
+			chromeRunning: false,
+			chromeInstalled: false,
+			plannedAction: "no-chrome",
+			detail,
+			extensionConnected,
+		};
+	}
+}
+
+/**
+ * Best-effort read of whether Chrome's Developer Mode is enabled, from the
+ * profile Preferences (`extensions.ui.developer_mode`). Unpacked extensions
+ * require Developer Mode to actually run. Returns null if it can't be read.
+ */
+export function chromeDeveloperModeEnabled(): boolean | null {
+	const candidates =
+		process.platform === "darwin"
+			? [
+					"Library/Application Support/Google/Chrome/Default/Preferences",
+					"Library/Application Support/Google/Chrome/Profile 1/Preferences",
+				]
+			: process.platform === "win32"
+				? ["AppData/Local/Google/Chrome/User Data/Default/Preferences"]
+				: [".config/google-chrome/Default/Preferences"];
+	for (const rel of candidates) {
+		try {
+			const fs = require("node:fs") as typeof import("node:fs");
+			const os = require("node:os") as typeof import("node:os");
+			const p = `${os.homedir()}/${rel}`;
+			if (!fs.existsSync(p)) continue;
+			const prefs = JSON.parse(fs.readFileSync(p, "utf8"));
+			return prefs?.extensions?.ui?.developer_mode === true;
+		} catch {
+			/* try next candidate */
+		}
+	}
+	return null;
+}

package/src/browser/index.ts

@@ -0,0 +1,17 @@
+export * from "./acquire";
+export * from "./actions";
+export * from "./auth";
+export * from "./ax";
+export * from "./cdp-core";
+export * from "./cdp-page-actions";
+export * from "./chrome-locate";
+export * from "./dom-context";
+export * from "./extension-bridge";
+export * from "./extension-page-actions";
+export * from "./extension-provider";
+export * from "./input-commit";
+export * from "./native-messaging";
+export * from "./page-actions";
+export * from "./provider";
+export * from "./resolver";
+export * from "./selector";

package/src/browser/input-commit.ts

@@ -0,0 +1,74 @@
+/**
+ * Commit a value into a form control so that a framework which patched the
+ * element's `value` descriptor still observes the change.
+ *
+ * Why this exists: the XCSH console's `vsui-input` (e.g. over the HTTP-LB
+ * "Domains" ngx-datatable cell) overrides the native `<input>` `value`
+ * descriptor with its own accessor. Typing real keystrokes — or assigning
+ * `el.value = …` directly — leaves the text in the DOM but never reaches the
+ * Angular reactive-form model, so the form reports the field as still empty.
+ *
+ * The fix, verified live against the staging console: write through the
+ * *prototype's* native value setter (skipping any instance-level patch), then
+ * dispatch bubbling `input` and `change` events so the framework's own change
+ * detection runs.
+ *
+ * This module is intentionally dependency-free (DOM only) so it can be both
+ * unit-tested (linkedom/fakes) and DRY-injected into the live page via
+ * `.toString()` — the same pattern used by dom-context/dt-context.
+ */
+
+/** Minimal KeyboardEvent constructor shape — typed loosely because this module
+ * is type-checked under the webworker lib (no DOM `KeyboardEvent` global) but is
+ * injected into and runs in the page, where `view.KeyboardEvent` exists. */
+type KeyboardEventCtor = new (type: string, init?: { bubbles?: boolean; key?: string; code?: string }) => unknown;
+
+interface CommittableElement {
+	value: string;
+	ownerDocument?: { defaultView?: { Event?: typeof Event; KeyboardEvent?: KeyboardEventCtor } | null } | null;
+	dispatchEvent(event: unknown): unknown;
+	closest?(selector: string): unknown;
+}
+
+export function commitInputValue(el: CommittableElement, value: string): void {
+	// Walk the prototype chain (starting ABOVE the instance) for the `value`
+	// setter. Starting above the instance is what bypasses a framework's
+	// instance-level patch and reaches the real (native) accessor.
+	let descriptor: PropertyDescriptor | undefined;
+	let proto: object | null = Object.getPrototypeOf(el);
+	while (proto) {
+		descriptor = Object.getOwnPropertyDescriptor(proto, "value");
+		if (descriptor) break;
+		proto = Object.getPrototypeOf(proto);
+	}
+	if (descriptor?.set) descriptor.set.call(el, value);
+	else el.value = value;
+
+	const view = el.ownerDocument?.defaultView ?? undefined;
+	const EventCtor = view?.Event ?? (typeof Event !== "undefined" ? Event : undefined);
+	if (EventCtor) {
+		// `input`/`change` cover controls that update on value change; `blur`/
+		// `focusout` cover Angular controls configured `updateOn: 'blur'` (the
+		// console's vsui-input commits to the model on blur, not on keystroke).
+		el.dispatchEvent(new EventCtor("input", { bubbles: true }));
+		el.dispatchEvent(new EventCtor("change", { bubbles: true }));
+		// ngx-datatable inline-edit cells that persist on Enter (ip-prefix-set
+		// "IPv4 Prefix") revert on a bare blur. For inputs inside a datatable,
+		// dispatch Enter BEFORE blur so the row commits first; http-lb "Domains"
+		// (commits on blur) is unaffected because blur still fires afterwards.
+		// Only the page provides KeyboardEvent (this module type-checks under the
+		// webworker lib, which has no DOM KeyboardEvent global) — if absent, skip
+		// the best-effort Enter and let the blur below carry the commit.
+		const KeyCtor = view?.KeyboardEvent;
+		const inGrid =
+			typeof el.closest === "function" &&
+			!!el.closest("ngx-datatable,datatable-body-cell,datatable-body-row,[class*=datatable]");
+		if (inGrid && KeyCtor) {
+			for (const t of ["keydown", "keypress", "keyup"] as const) {
+				el.dispatchEvent(new KeyCtor(t, { bubbles: true, key: "Enter", code: "Enter" }));
+			}
+		}
+		el.dispatchEvent(new EventCtor("blur", { bubbles: false }));
+		el.dispatchEvent(new EventCtor("focusout", { bubbles: true }));
+	}
+}

package/src/browser/native-messaging.ts

@@ -0,0 +1,20 @@
+export function encodeNm(msg: unknown): Uint8Array {
+	const json = new TextEncoder().encode(JSON.stringify(msg));
+	const out = new Uint8Array(4 + json.length);
+	new DataView(out.buffer).setUint32(0, json.length, true); // little-endian
+	out.set(json, 4);
+	return out;
+}
+
+export function decodeNm(buf: Uint8Array): { messages: unknown[]; rest: Uint8Array } {
+	const messages: unknown[] = [];
+	let offset = 0;
+	while (buf.length - offset >= 4) {
+		const len = new DataView(buf.buffer, buf.byteOffset + offset, 4).getUint32(0, true);
+		if (buf.length - offset - 4 < len) break;
+		const json = new TextDecoder().decode(buf.subarray(offset + 4, offset + 4 + len));
+		messages.push(JSON.parse(json));
+		offset += 4 + len;
+	}
+	return { messages, rest: buf.subarray(offset) };
+}

package/src/browser/page-actions.ts

@@ -0,0 +1,18 @@
+/**
+ * Backend-agnostic page-driving abstraction.
+ *
+ * Lets the catalog-workflow-runner drive both a CDP (Puppeteer) page and the
+ * Chrome extension through one identical surface. Implementations: `CdpPageActions`
+ * (./cdp-page-actions) and the extension-backed equivalent.
+ */
+export interface PageActions {
+	goto(url: string, opts?: { waitUntil?: string; timeout?: number }): Promise<void>;
+	click(selector: string, context?: string): Promise<void>;
+	fill(selector: string, value: string, context?: string): Promise<void>;
+	selectOption(selector: string, value: string, context?: string): Promise<void>;
+	scrollIntoView(selector: string, context?: string): Promise<void>;
+	pressKey(key: string): Promise<void>;
+	assertText(selector: string, expected: string, context?: string): Promise<void>;
+	waitFor(selector: string, context?: string, timeoutMs?: number): Promise<void>;
+	screenshot(file: string): Promise<void>;
+}

package/src/browser/provider.ts

@@ -0,0 +1,155 @@
+import { type AcquireAction, acquirePage, decideAcquireAction, isChromeRunning } from "./acquire";
+import { ensureAuthenticated } from "./auth";
+import { CdpPageActions } from "./cdp-page-actions";
+import { locateChrome } from "./chrome-locate";
+import { startBridgeServer } from "./extension-bridge";
+import { ExtensionBrowserProvider } from "./extension-provider";
+import type { PageActions } from "./page-actions";
+
+export interface AcquiredBrowser {
+	page: PageActions;
+	mode: string;
+	release(): Promise<void>;
+}
+
+export interface BrowserProviderStatus {
+	debuggableNow: boolean;
+	chromeRunning: boolean;
+	chromeInstalled: boolean;
+	plannedAction: AcquireAction;
+	detail: string;
+}
+
+export interface BrowserProvider {
+	readonly name: string;
+	acquire(consoleUrl: string): Promise<AcquiredBrowser>;
+	status(): Promise<BrowserProviderStatus>;
+}
+
+type Settings = { get(key: string): unknown };
+const DEBUG_PORT = 9222;
+
+/** Probe the loopback debug endpoint without attaching. */
+async function probeDebuggableDefault(): Promise<boolean> {
+	try {
+		const r = await fetch(`http://127.0.0.1:${DEBUG_PORT}/json/version`);
+		return r.ok;
+	} catch {
+		return false;
+	}
+}
+
+const DETAIL: Record<AcquireAction, string> = {
+	attach: "A debuggable Chrome is reachable on 127.0.0.1:9222 — xcsh will attach and co-drive it.",
+	launch: "Chrome is installed and not running — xcsh will launch it on your real profile with a loopback debug port.",
+	relaunch:
+		"Your Chrome is running without a debug port — xcsh will gracefully quit and reopen it on your real profile (consent granted).",
+	dedicated:
+		"Your Chrome is running without a debug port and relaunch is off — xcsh will use an isolated profile (run `/chrome relaunch` or set browser.allowChromeRelaunch to use your real session).",
+	"no-chrome": "Google Chrome was not found — install it or set browser.chromePath.",
+};
+
+export class CdpBrowserProvider implements BrowserProvider {
+	readonly name = "cdp";
+	#settings: Settings;
+	#probes: { probeDebuggable: () => Promise<boolean>; chromeRunning: () => boolean; chromeInstalled: () => boolean };
+
+	constructor(
+		settings: Settings,
+		probes?: {
+			probeDebuggable: () => Promise<boolean>;
+			chromeRunning: () => boolean;
+			chromeInstalled: () => boolean;
+		},
+	) {
+		this.#settings = settings;
+		this.#probes = probes ?? {
+			probeDebuggable: probeDebuggableDefault,
+			chromeRunning: () => isChromeRunning(),
+			chromeInstalled: () => locateChrome({ settings }) != null,
+		};
+	}
+
+	async status(): Promise<BrowserProviderStatus> {
+		const debuggableNow = await this.#probes.probeDebuggable();
+		const chromeRunning = this.#probes.chromeRunning();
+		const chromeInstalled = this.#probes.chromeInstalled();
+		const allowRelaunch = this.#settings.get("browser.allowChromeRelaunch") === true;
+		const plannedAction = decideAcquireAction({ debuggableNow, chromeRunning, chromeInstalled, allowRelaunch });
+		return { debuggableNow, chromeRunning, chromeInstalled, plannedAction, detail: DETAIL[plannedAction] };
+	}
+
+	async acquire(consoleUrl: string): Promise<AcquiredBrowser> {
+		const { browser, page, mode } = await acquirePage({ settings: this.#settings, debugPort: DEBUG_PORT });
+		await ensureAuthenticated(page, consoleUrl);
+		const dropPort = this.#settings.get("browser.dropPortAfter") === true;
+		const relaunched = mode === "relaunched-default";
+		return {
+			page: new CdpPageActions(page),
+			mode,
+			release: async () => {
+				await browser.disconnect().catch(() => {});
+				// dropPortAfter: only meaningful when WE opened the port via relaunch; reopening
+				// the real profile without the flag is itself a relaunch — gate it tightly.
+				if (dropPort && relaunched) {
+					// Best-effort: leave to a follow-up; never force-kill. (No-op stub acceptable here —
+					// the port closes when the user next restarts Chrome. See spec "dropPortAfter".)
+				}
+			},
+		};
+	}
+}
+
+/**
+ * Select the best available browser provider: if the Chrome extension bridge is
+ * reachable (the extension is loaded + xcsh chrome setup ran), use it (real profile,
+ * no debug port needed). Otherwise fall back to CDP (dedicated profile).
+ *
+ * The probe is bounded: if the extension doesn't connect within `probeTimeoutMs`,
+ * the CDP provider is used — so this never blocks a session indefinitely.
+ */
+export async function selectProvider(
+	settings: Settings,
+	opts?: { probeTimeoutMs?: number; bridgeServer?: import("./extension-bridge").BridgeServer },
+): Promise<BrowserProvider> {
+	// `XCSH_BROWSER_PROVIDER=extension` forces the extension (real Chrome) and
+	// disables the CDP fallback — required for the NL-driven console automation
+	// flagship, where falling back to a separate CDP profile is never wanted.
+	// `XCSH_BROWSER_PROVIDER=cdp` forces CDP. The probe timeout is configurable
+	// via `XCSH_BRIDGE_PROBE_MS` (default 5s) — the extension can take a few
+	// seconds to (re)connect after the bridge socket is (re)bound, and 5s races
+	// that reconnect, so callers expecting the extension should raise it.
+	const forced = process.env.XCSH_BROWSER_PROVIDER?.toLowerCase();
+	const envProbe = Number(process.env.XCSH_BRIDGE_PROBE_MS);
+	// Forced-extension default is 45s: the MV3 service worker can suspend between
+	// runs, after which only its ~30s reconnect alarm re-attaches it — a shorter
+	// probe races (and loses to) that alarm. 45s clears the alarm + reconnect.
+	const probeMs =
+		opts?.probeTimeoutMs ??
+		(Number.isFinite(envProbe) && envProbe > 0 ? envProbe : forced === "extension" ? 45_000 : 5_000);
+
+	if (forced === "cdp") return new CdpBrowserProvider(settings);
+
+	try {
+		const server = opts?.bridgeServer ?? (await startBridgeServer());
+		const deadline = Date.now() + probeMs;
+		while (Date.now() < deadline) {
+			if (server.connected) {
+				return new ExtensionBrowserProvider({ server });
+			}
+			await new Promise(r => setTimeout(r, 300));
+		}
+		if (forced === "extension") {
+			// Don't tear down the bridge or fall back — keep waiting for the extension.
+			throw new Error(
+				`XCSH_BROWSER_PROVIDER=extension but the Chrome extension did not connect within ${probeMs}ms. ` +
+					`Ensure the extension is loaded and \`xcsh chrome setup\` has run.`,
+			);
+		}
+		await server.close();
+	} catch (err) {
+		if (forced === "extension") throw err; // never silently fall back to CDP when extension is required
+		// Bridge server failed to start — fall back silently.
+	}
+	return new CdpBrowserProvider(settings);
+}