@f5xc-salesdemos/xcsh 19.37.0 → 19.38.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "19.37.0",
+	"version": "19.38.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -51,13 +51,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "19.37.0",
-		"@f5xc-salesdemos/pi-agent-core": "19.37.0",
-		"@f5xc-salesdemos/pi-ai": "19.37.0",
-		"@f5xc-salesdemos/pi-natives": "19.37.0",
-		"@f5xc-salesdemos/pi-resource-management": "19.37.0",
-		"@f5xc-salesdemos/pi-tui": "19.37.0",
-		"@f5xc-salesdemos/pi-utils": "19.37.0",
+		"@f5xc-salesdemos/xcsh-stats": "19.38.0",
+		"@f5xc-salesdemos/pi-agent-core": "19.38.0",
+		"@f5xc-salesdemos/pi-ai": "19.38.0",
+		"@f5xc-salesdemos/pi-natives": "19.38.0",
+		"@f5xc-salesdemos/pi-resource-management": "19.38.0",
+		"@f5xc-salesdemos/pi-tui": "19.38.0",
+		"@f5xc-salesdemos/pi-utils": "19.38.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/acquire.ts

@@ -1,10 +1,11 @@
+import { execFileSync } from "node:child_process";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { Browser, Page } from "puppeteer";
 import { assertLoopbackBrowserUrl, pickCoDrivePage, resolveBrowserConnectUrl } from "../tools/browser";
 import { locateChrome } from "./chrome-locate";
 
-export type AcquireMode = "attached" | "launched-default" | "launched-dedicated";
+export type AcquireMode = "attached" | "launched-default" | "launched-dedicated" | "relaunched-default";
 
 const DEFAULT_DEBUG_PORT = 9222;
 
@@ -48,11 +49,46 @@ async function withLaunchTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
 }
 
 export function buildLaunchArgs(opts: { profileDir?: string; debugPort: number }): string[] {
-	const args = [`--remote-debugging-port=${opts.debugPort}`, "--no-first-run", "--no-default-browser-check"];
+	const args = [
+		`--remote-debugging-port=${opts.debugPort}`,
+		"--remote-debugging-address=127.0.0.1",
+		"--no-first-run",
+		"--no-default-browser-check",
+	];
 	if (opts.profileDir) args.push(`--user-data-dir=${opts.profileDir}`);
 	return args;
 }
 
+export type AcquireAction = "attach" | "launch" | "relaunch" | "dedicated" | "no-chrome";
+
+export function decideAcquireAction(state: {
+	debuggableNow: boolean;
+	chromeRunning: boolean;
+	chromeInstalled: boolean;
+	allowRelaunch: boolean;
+}): AcquireAction {
+	if (!state.chromeInstalled) return "no-chrome";
+	if (state.debuggableNow) return "attach";
+	if (!state.chromeRunning) return "launch";
+	return state.allowRelaunch ? "relaunch" : "dedicated";
+}
+
+/** Graceful (never force) quit command for the user's Chrome, per OS. */
+export function quitChromeCommand(
+	platform: NodeJS.Platform = process.platform,
+): { cmd: string; args: string[] } | null {
+	switch (platform) {
+		case "darwin":
+			return { cmd: "osascript", args: ["-e", 'quit app "Google Chrome"'] };
+		case "linux":
+			return { cmd: "pkill", args: ["-TERM", "-x", "chrome"] };
+		case "win32":
+			return { cmd: "taskkill", args: ["/IM", "chrome.exe"] };
+		default:
+			return null;
+	}
+}
+
 export function isProfileLockError(message: string): boolean {
 	// Chrome's own SingletonLock messages, plus Puppeteer's message when an
 	// explicit --user-data-dir is already held by a running browser
@@ -62,6 +98,39 @@ export function isProfileLockError(message: string): boolean {
 	);
 }
 
+function defaultExec(cmd: string, args: string[]): { code: number } {
+	try {
+		execFileSync(cmd, args, { stdio: "ignore" });
+		return { code: 0 };
+	} catch (e) {
+		const code = (e as { status?: number }).status;
+		return { code: typeof code === "number" ? code : 1 };
+	}
+}
+
+export function isChromeRunning(
+	opts: { platform?: NodeJS.Platform; exec?: (cmd: string, args: string[]) => { code: number } } = {},
+): boolean {
+	const platform = opts.platform ?? process.platform;
+	const exec = opts.exec ?? defaultExec;
+	if (platform === "win32") {
+		// tasklist always exits 0; use FILTER so a no-match is a non-zero/empty result.
+		return exec("tasklist", ["/FI", "IMAGENAME eq chrome.exe", "/NH"]).code === 0;
+	}
+	// darwin/linux: pgrep exits 0 when a match exists, 1 otherwise.
+	const pattern = platform === "darwin" ? "Google Chrome" : "chrome";
+	return exec("pgrep", ["-x", pattern]).code === 0;
+}
+
+async function waitForChromeExit(timeoutMs = 8000, pollMs = 300): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (!isChromeRunning()) return true;
+		await new Promise(r => setTimeout(r, pollMs));
+	}
+	return false;
+}
+
 async function tryAttach(browserURL: string): Promise<{ browser: Browser; page: Page } | null> {
 	const puppeteer = (await import("puppeteer")).default;
 	try {
@@ -82,6 +151,7 @@ async function launch(executablePath: string, args: string[]): Promise<Browser>
 export async function acquirePage(opts: {
 	settings: { get(key: string): unknown };
 	debugPort?: number;
+	allowRelaunch?: boolean;
 }): Promise<{ browser: Browser; page: Page; mode: AcquireMode }> {
 	const debugPort = opts.debugPort ?? DEFAULT_DEBUG_PORT;
 	const configuredUrl = resolveBrowserConnectUrl(opts.settings);
@@ -127,10 +197,35 @@ export async function acquirePage(opts: {
 			// Profile locked (Chrome already running) or the launch timed out (handoff to a
 			// running instance) → fall through to a dedicated, xcsh-owned profile.
 			if (!isProfileLockError(msg) && !msg.includes("launch timed out")) throw err;
+
+			// Resolve relaunch consent: explicit opt, else the setting.
+			const allowRelaunch = opts.allowRelaunch ?? opts.settings.get("browser.allowChromeRelaunch") === true;
+			// 3) Chrome running without the port → consented quit + relaunch on the real profile.
+			if (allowRelaunch) {
+				const quit = quitChromeCommand();
+				if (quit) {
+					try {
+						execFileSync(quit.cmd, quit.args, { stdio: "ignore" });
+					} catch {
+						/* ignore quit errors; verify via waitForChromeExit */
+					}
+					const exited = await waitForChromeExit();
+					if (exited) {
+						const browser = await withLaunchTimeout(
+							launch(located.path, buildLaunchArgs({ debugPort, profileDir: defaultDir })),
+							12_000,
+						);
+						const pages = await browser.pages();
+						const page = pages.length ? pages[0]! : await browser.newPage();
+						return { browser, page, mode: "relaunched-default" };
+					}
+					// quit timed out → DO NOT relaunch (avoid two instances / data loss); fall through to dedicated.
+				}
+			}
 		}
 	}
 
-	// 3) Default profile unavailable (locked / handoff / unsupported platform) → dedicated
+	// 4) Default profile unavailable (locked / handoff / unsupported platform) → dedicated
 	// xcsh-owned profile. A previous xcsh-launched Chrome on this profile may still be
 	// running (close() only disconnects, never terminates), so this launch can hit the
 	// same SingletonLock/handoff and hang. Guard it with a timeout; there is no further

package/src/browser/cdp-page-actions.ts

@@ -0,0 +1,51 @@
+import type { Page } from "puppeteer";
+import * as actions from "./actions";
+import type { PageActions } from "./page-actions";
+
+/** CDP-backed `PageActions`: wraps a Puppeteer `Page` and delegates to `actions.ts`. */
+export class CdpPageActions implements PageActions {
+	#page: Page;
+	constructor(page: Page) {
+		this.#page = page;
+	}
+
+	async goto(url: string, opts?: { waitUntil?: string; timeout?: number }): Promise<void> {
+		type GotoOptions = NonNullable<Parameters<Page["goto"]>[1]>;
+		await this.#page.goto(url, {
+			waitUntil: (opts?.waitUntil as GotoOptions["waitUntil"]) ?? "networkidle2",
+			timeout: opts?.timeout,
+		});
+	}
+
+	async click(selector: string, context?: string): Promise<void> {
+		await actions.click(this.#page, selector, context);
+	}
+
+	async fill(selector: string, value: string, context?: string): Promise<void> {
+		await actions.fill(this.#page, selector, value, context);
+	}
+
+	async selectOption(selector: string, value: string, context?: string): Promise<void> {
+		await actions.selectOption(this.#page, selector, value, context);
+	}
+
+	async scrollIntoView(selector: string, context?: string): Promise<void> {
+		await actions.scrollIntoView(this.#page, selector, context);
+	}
+
+	async pressKey(key: string): Promise<void> {
+		await actions.pressKey(this.#page, key);
+	}
+
+	async assertText(selector: string, expected: string, context?: string): Promise<void> {
+		await actions.assertText(this.#page, selector, expected, context);
+	}
+
+	async waitFor(selector: string, context?: string, timeoutMs?: number): Promise<void> {
+		await actions.waitFor(this.#page, selector, context, timeoutMs);
+	}
+
+	async screenshot(file: string): Promise<void> {
+		await actions.screenshot(this.#page, file);
+	}
+}

package/src/browser/extension-bridge.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Socket, UnixSocketListener } from "bun";
+
+export interface ToolResult {
+	content: unknown;
+	is_error: boolean;
+}
+
+/**
+ * Id-correlated pending-request registry. Pure (no socket I/O) so it can be
+ * unit-tested directly. Each {@link create} returns a fresh id and a promise
+ * that is settled by a later {@link resolve} (matching id) or {@link rejectAll}.
+ */
+export class PendingRequests {
+	#m = new Map<
+		string,
+		{
+			resolve: (r: ToolResult) => void;
+			reject: (e: Error) => void;
+			timer: ReturnType<typeof setTimeout>;
+		}
+	>();
+
+	create(timeoutMs: number): { id: string; promise: Promise<ToolResult> } {
+		const id = randomUUID();
+		let resolve!: (r: ToolResult) => void;
+		let reject!: (e: Error) => void;
+		const promise = new Promise<ToolResult>((res, rej) => {
+			resolve = res;
+			reject = rej;
+		});
+		const timer = setTimeout(() => {
+			if (this.#m.delete(id)) reject(new Error(`bridge request ${id} timed out`));
+		}, timeoutMs);
+		this.#m.set(id, { resolve, reject, timer });
+		return { id, promise };
+	}
+
+	resolve(id: string, result: ToolResult): boolean {
+		const e = this.#m.get(id);
+		if (!e) return false;
+		clearTimeout(e.timer);
+		this.#m.delete(id);
+		e.resolve(result);
+		return true;
+	}
+
+	rejectAll(err: Error): void {
+		for (const e of this.#m.values()) {
+			clearTimeout(e.timer);
+			e.reject(err);
+		}
+		this.#m.clear();
+	}
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+type BridgeData = { buf: string };
+
+/**
+ * Unix-socket server bridging xcsh to the Chrome extension's native-messaging
+ * host. Speaks newline-delimited JSON: requests `{type:"tool_request",...}`,
+ * replies `{type:"tool_result",...}`, plus `{type:"ping"|"pong"}`. Tracks a
+ * single connected client and correlates replies via {@link PendingRequests}.
+ */
+export class BridgeServer {
+	#pending = new PendingRequests();
+	#listener: UnixSocketListener<BridgeData> | null = null;
+	#client: Socket<BridgeData> | null = null;
+	#onConnected: Array<() => void> = [];
+	#onDisconnected: Array<() => void> = [];
+
+	get connected(): boolean {
+		return this.#client !== null;
+	}
+
+	onConnected(cb: () => void): void {
+		this.#onConnected.push(cb);
+	}
+
+	onDisconnected(cb: () => void): void {
+		this.#onDisconnected.push(cb);
+	}
+
+	/** Bind the server to a Unix socket path. Called by {@link startBridgeServer}. */
+	listen(socketPath: string): void {
+		this.#listener = Bun.listen<BridgeData>({
+			unix: socketPath,
+			socket: {
+				open: socket => {
+					socket.data = { buf: "" };
+					this.#client = socket;
+					for (const cb of this.#onConnected) cb();
+				},
+				data: (socket, chunk) => {
+					this.#onData(socket, chunk);
+				},
+				close: socket => {
+					this.#onClose(socket);
+				},
+				error: socket => {
+					this.#onClose(socket);
+				},
+			},
+		});
+	}
+
+	#onData(socket: Socket<BridgeData>, chunk: Buffer): void {
+		socket.data.buf += chunk.toString("utf8");
+		let idx = socket.data.buf.indexOf("\n");
+		while (idx !== -1) {
+			const line = socket.data.buf.slice(0, idx);
+			socket.data.buf = socket.data.buf.slice(idx + 1);
+			if (line.length > 0) this.#handleLine(socket, line);
+			idx = socket.data.buf.indexOf("\n");
+		}
+	}
+
+	#handleLine(socket: Socket<BridgeData>, line: string): void {
+		let msg: { type?: string; id?: string; content?: unknown; is_error?: boolean };
+		try {
+			msg = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (msg.type === "tool_result" && typeof msg.id === "string") {
+			this.#pending.resolve(msg.id, {
+				content: msg.content,
+				is_error: msg.is_error === true,
+			});
+		} else if (msg.type === "ping") {
+			this.#write(socket, { type: "pong" });
+		}
+	}
+
+	#onClose(socket: Socket<BridgeData>): void {
+		if (this.#client !== socket) return;
+		this.#client = null;
+		this.#pending.rejectAll(new Error("bridge client disconnected"));
+		for (const cb of this.#onDisconnected) cb();
+	}
+
+	#write(socket: Socket<BridgeData>, msg: unknown): void {
+		socket.write(`${JSON.stringify(msg)}\n`);
+	}
+
+	/** Send a `tool_request` to the connected client and await its `tool_result`. */
+	request(tool: string, params: unknown, timeoutMs: number = DEFAULT_TIMEOUT_MS): Promise<ToolResult> {
+		const client = this.#client;
+		if (!client) return Promise.reject(new Error("bridge: no client connected"));
+		const { id, promise } = this.#pending.create(timeoutMs);
+		this.#write(client, { type: "tool_request", id, tool, params });
+		return promise;
+	}
+
+	async close(): Promise<void> {
+		this.#pending.rejectAll(new Error("bridge server closed"));
+		this.#client?.end();
+		this.#client = null;
+		this.#listener?.stop(true);
+		this.#listener = null;
+	}
+}
+
+/**
+ * Resolve the default socket path (`~/.xcsh/chrome-bridge.sock`), ensure the
+ * directory exists, remove any stale socket, start the {@link BridgeServer},
+ * and tighten the socket permissions to owner-only (0600).
+ */
+export async function startBridgeServer(socketPath?: string): Promise<BridgeServer> {
+	const resolved = socketPath ?? path.join(os.homedir(), ".xcsh", "chrome-bridge.sock");
+	fs.mkdirSync(path.dirname(resolved), { recursive: true });
+	fs.rmSync(resolved, { force: true });
+	const server = new BridgeServer();
+	server.listen(resolved);
+	fs.chmodSync(resolved, 0o600);
+	return server;
+}

package/src/browser/extension-page-actions.ts

@@ -0,0 +1,94 @@
+/**
+ * Extension-backed {@link PageActions} implementation.
+ *
+ * Wraps an {@link ExtensionPage} (the Chrome extension bridge surface) so the
+ * catalogue-workflow runner can drive the extension through the exact same
+ * `PageActions` interface it uses for CDP. For tools that operate on a `ref`
+ * handle (`click`/`fill`/`selectOption`/`scrollIntoView`), resolution happens
+ * xcsh-side: read the AX tree, {@link resolveRef} the selector to a `ref`, then
+ * call the bridge tool. `assertText`/`waitFor` resolve selectors on the bridge
+ * (service-worker) side, so they pass through directly.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type ExtensionPage, resolveRef } from "./extension-provider";
+import type { PageActions } from "./page-actions";
+
+const ALLOWED_SCHEMES = new Set(["https:"]);
+const CONSOLE_DOMAIN_RE = /\.(volterra\.us|console\.ves\.volterra\.io)$/;
+
+export class ExtensionPageActions implements PageActions {
+	#ext: ExtensionPage;
+
+	constructor(ext: ExtensionPage) {
+		this.#ext = ext;
+	}
+
+	async goto(url: string): Promise<void> {
+		// Defense-in-depth: validate URL scheme + console-domain scope before sending to the extension.
+		// The extension SW also validates, but rejecting early is cleaner + prevents SSRF.
+		const parsed = new URL(url); // throws on malformed
+		if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+			throw new Error(`Disallowed URL scheme: ${parsed.protocol} (only https: is allowed)`);
+		}
+		if (!CONSOLE_DOMAIN_RE.test(parsed.hostname)) {
+			throw new Error(`URL "${parsed.hostname}" is not an F5 XC console domain`);
+		}
+		await this.#ext.navigate(url);
+	}
+
+	async click(selector: string, _context?: string): Promise<void> {
+		const tree = await this.#ext.readAx();
+		const ref = resolveRef(tree, selector);
+		await this.#ext.click(ref);
+	}
+
+	async fill(selector: string, value: string, _context?: string): Promise<void> {
+		const tree = await this.#ext.readAx();
+		const ref = resolveRef(tree, selector);
+		await this.#ext.formInput(ref, value);
+	}
+
+	async selectOption(selector: string, value: string, _context?: string): Promise<void> {
+		const tree = await this.#ext.readAx();
+		const ref = resolveRef(tree, selector);
+		await this.#ext.selectOption(ref, value);
+	}
+
+	async scrollIntoView(selector: string, _context?: string): Promise<void> {
+		const tree = await this.#ext.readAx();
+		const ref = resolveRef(tree, selector);
+		await this.#ext.scrollTo(ref);
+	}
+
+	async pressKey(key: string): Promise<void> {
+		await this.#ext.keyPress(key);
+	}
+
+	async assertText(selector: string, expected: string, context?: string): Promise<void> {
+		await this.#ext.assertText(selector, expected, context);
+	}
+
+	async waitFor(selector: string, context?: string, timeoutMs?: number): Promise<void> {
+		await this.#ext.waitFor(selector, context, timeoutMs);
+	}
+
+	async screenshot(file: string): Promise<void> {
+		// Defense-in-depth: resolve symlinks via realpathSync so a symlinked parent
+		// can't bypass the cwd containment check and write outside the working directory.
+		const cwdReal = fs.realpathSync(process.cwd());
+		const lexical = path.resolve(file);
+		let parentReal: string;
+		try {
+			parentReal = fs.realpathSync(path.dirname(lexical));
+		} catch {
+			throw new Error(`Screenshot directory does not exist: ${path.dirname(lexical)}`);
+		}
+		const resolved = path.join(parentReal, path.basename(lexical));
+		if (!resolved.startsWith(cwdReal + path.sep) && resolved !== cwdReal) {
+			throw new Error(`Screenshot path "${file}" resolves outside the working directory`);
+		}
+		const b64 = await this.#ext.screenshot();
+		await Bun.write(resolved, Buffer.from(b64, "base64"));
+	}
+}