@f5xc-salesdemos/xcsh 19.38.0 → 19.38.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "19.38.0",
+	"version": "19.38.1",
 	"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.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",
+		"@f5xc-salesdemos/xcsh-stats": "19.38.1",
+		"@f5xc-salesdemos/pi-agent-core": "19.38.1",
+		"@f5xc-salesdemos/pi-ai": "19.38.1",
+		"@f5xc-salesdemos/pi-natives": "19.38.1",
+		"@f5xc-salesdemos/pi-resource-management": "19.38.1",
+		"@f5xc-salesdemos/pi-tui": "19.38.1",
+		"@f5xc-salesdemos/pi-utils": "19.38.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/extension-uat-harness.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env bun
+/**
+ * F5 XC Console Agent — UAT Harness
+ *
+ * Exercises each of the 21 extension tools against the real F5 XC console in
+ * your logged-in Chrome. Automates what it can; marks items that need your
+ * visual verification with [USER-VERIFY].
+ *
+ * Prerequisites:
+ *   1. The extension is loaded in Chrome (chrome://extensions → Load unpacked → dist/)
+ *   2. `xcsh chrome setup` has been run
+ *   3. You are logged into the F5 XC staging console in your Chrome
+ *
+ * Usage: bun scripts/extension-uat-harness.ts
+ */
+import { type BridgeServer, startBridgeServer } from "../src/browser/extension-bridge";
+
+const BASE = process.env.F5XC_API_URL ?? "https://nferreira.staging.volterra.us";
+const ROUTE = `${BASE}/web/workspaces/web-app-and-api-protection/namespaces/demo/manage/load_balancers/http_loadbalancers`;
+
+let server: BridgeServer;
+const results: Array<{ tool: string; status: "PASS" | "FAIL" | "USER-VERIFY"; detail: string }> = [];
+
+async function tool(name: string, params: Record<string, unknown> = {}, timeout = 30000) {
+	const r = await server.request(name, params, timeout);
+	if (r.is_error) throw new Error(`${name}: ${JSON.stringify(r.content)}`);
+	return r.content as Record<string, unknown>;
+}
+
+function pass(name: string, detail: string) {
+	results.push({ tool: name, status: "PASS", detail });
+	console.log(`  ✅ ${name}: ${detail}`);
+}
+function fail(name: string, detail: string) {
+	results.push({ tool: name, status: "FAIL", detail });
+	console.log(`  ❌ ${name}: ${detail}`);
+}
+function userVerify(name: string, detail: string) {
+	results.push({ tool: name, status: "USER-VERIFY", detail });
+	console.log(`  👁 ${name}: ${detail}`);
+}
+
+async function run() {
+	console.log("\n🚀 F5 XC Console Agent — UAT Harness\n");
+	console.log("[0] Starting bridge server...");
+	server = await startBridgeServer();
+
+	console.log("[0] Waiting for extension to connect (up to 60s)...");
+	const deadline = Date.now() + 60_000;
+	while (Date.now() < deadline) {
+		if (server.connected) break;
+		await new Promise(r => setTimeout(r, 2000));
+		process.stdout.write(".");
+	}
+	if (!server.connected) {
+		console.log("\n❌ Extension did not connect. Load it in Chrome + run xcsh chrome setup.");
+		process.exit(1);
+	}
+	console.log("\n✅ Extension connected\n");
+
+	// --- TOOL TESTS ---
+
+	console.log("[1] ping");
+	try {
+		const p = await tool("ping");
+		p?.ok ? pass("ping", `v${(p as any).version}`) : fail("ping", JSON.stringify(p));
+	} catch (e) {
+		fail("ping", (e as Error).message);
+	}
+
+	console.log("[1b] login (native F5 XC auth)");
+	const KC_USER = process.env.KC_USER;
+	const KC_PASS = process.env.KC_PASS;
+	if (KC_USER && KC_PASS) {
+		try {
+			// Login directly to the target deep-link — NOT /web. Going to /web triggers
+			// an OIDC flow, then the subsequent navigate to the LB URL interrupts it
+			// mid-flight → "Invalid CSRF token". Logging into the target URL directly
+			// means ONE navigation, one OIDC flow, no interruption.
+			const l = await tool("login", { email: KC_USER, password: KC_PASS, consoleUrl: ROUTE }, 90000);
+			(l as any)?.loggedIn
+				? pass("login", `${(l as any).steps?.length ?? 0} redirect steps: ${((l as any).steps || []).join(" | ")}`)
+				: fail("login", JSON.stringify(l));
+		} catch (e) {
+			fail("login", (e as Error).message);
+		}
+	} else {
+		console.log("  ⏭ login skipped (no KC_USER/KC_PASS env) — relying on existing session");
+	}
+
+	console.log("[2] navigate");
+	if (KC_USER && KC_PASS) {
+		// Login already navigated to ROUTE — skip the redundant second navigate
+		// (two navigations to the same OIDC-protected URL in succession → CSRF).
+		pass("navigate", "skipped (login already navigated to target)");
+	} else {
+		try {
+			await tool("navigate", { url: ROUTE }, 30000);
+			pass("navigate", "loaded HTTP LB list page");
+		} catch (e) {
+			fail("navigate", (e as Error).message);
+		}
+	}
+
+	console.log("[3] read_ax");
+	let tree: any;
+	try {
+		tree = await tool("read_ax");
+		const nodes: string[] = [];
+		(function walk(n: any) {
+			if (!n) return;
+			nodes.push(`${n.role}:${n.name?.slice(0, 30)}`);
+			(n.children || []).forEach(walk);
+		})(tree);
+		const hasLogin = nodes.some(s => /textbox.*username/i.test(s));
+		nodes.length > 10 && !hasLogin
+			? pass("read_ax", `${nodes.length} nodes, no login form`)
+			: fail("read_ax", `${nodes.length} nodes, login=${hasLogin}`);
+	} catch (e) {
+		fail("read_ax", (e as Error).message);
+	}
+
+	console.log("[4] find");
+	try {
+		const f = await tool("find", { selector: "text('HTTP Load Balancers')" }, 30000);
+		const refs = (f as any)?.refs;
+		refs?.length > 0 ? pass("find", `${refs.length} refs found`) : fail("find", "0 refs");
+	} catch (e) {
+		fail("find", (e as Error).message);
+	}
+
+	console.log("[5] get_page_text");
+	try {
+		const t = await tool("get_page_text");
+		const len = ((t as any)?.text as string)?.length ?? 0;
+		len > 100 ? pass("get_page_text", `${len} chars`) : fail("get_page_text", `only ${len} chars`);
+	} catch (e) {
+		fail("get_page_text", (e as Error).message);
+	}
+
+	console.log("[6] javascript_tool");
+	try {
+		const j = await tool("javascript_tool", { code: "document.title" });
+		const title = (j as any)?.result;
+		title ? pass("javascript_tool", `title="${title}"`) : fail("javascript_tool", "no result");
+	} catch (e) {
+		fail("javascript_tool", (e as Error).message);
+	}
+
+	console.log("[7] tabs_list");
+	try {
+		const t = await tool("tabs_list");
+		const count = ((t as any)?.tabs as any[])?.length ?? 0;
+		count > 0 ? pass("tabs_list", `${count} console tabs`) : fail("tabs_list", "0 tabs");
+	} catch (e) {
+		fail("tabs_list", (e as Error).message);
+	}
+
+	console.log("[8] screenshot");
+	try {
+		const s = await tool("screenshot", {}, 30000);
+		const data = (s as any)?.data;
+		if (data && typeof data === "string" && data.length > 100) {
+			const fs = await import("node:fs");
+			fs.writeFileSync("/tmp/uat-screenshot.png", Buffer.from(data, "base64"));
+			userVerify("screenshot", "saved to /tmp/uat-screenshot.png — verify it shows the console page");
+		} else {
+			fail("screenshot", "no data returned (Chrome debugger infobar may need accepting)");
+		}
+	} catch (e) {
+		fail("screenshot", (e as Error).message);
+	}
+
+	console.log("[9] wait_for");
+	try {
+		const w = await tool("wait_for", { selector: "text('HTTP Load Balancers')", timeoutMs: 10000 });
+		pass("wait_for", `resolved ref: ${(w as any)?.ref ?? JSON.stringify(w)}`);
+	} catch (e) {
+		fail("wait_for", (e as Error).message);
+	}
+
+	console.log("[10] click (Add HTTP LB tab)");
+	try {
+		// First resolve the ref for the tab
+		const f = await tool("find", { selector: "tab:text('Add HTTP Load Balancer')" });
+		const ref = ((f as any)?.refs as any[])?.[0]?.ref;
+		if (!ref) {
+			fail("click", "couldn't find Add HTTP Load Balancer tab");
+		} else {
+			await tool("click", { ref }, 10000);
+			pass("click", `clicked ref ${ref}`);
+		}
+	} catch (e) {
+		fail("click", (e as Error).message);
+	}
+
+	console.log("[11] form_input (Name field)");
+	try {
+		const w = await tool("wait_for", { selector: "textbox[name='Name']", timeoutMs: 10000 });
+		const ref = (w as any)?.ref;
+		if (!ref) {
+			fail("form_input", "Name field not found");
+		} else {
+			await tool("form_input", { ref, value: "uat-test-" + Date.now() });
+			pass("form_input", `filled ref ${ref} with commitInputValue`);
+		}
+	} catch (e) {
+		fail("form_input", (e as Error).message);
+	}
+
+	console.log("[12] key_press");
+	try {
+		await tool("key_press", { key: "Tab" });
+		pass("key_press", "Tab pressed");
+	} catch (e) {
+		fail("key_press", (e as Error).message);
+	}
+
+	console.log("[13] assert_text");
+	try {
+		await tool("assert_text", { selector: "text('HTTP Load Balancer')", expected: "HTTP Load Balancer" });
+		pass("assert_text", "assertion passed");
+	} catch (e) {
+		fail("assert_text", (e as Error).message);
+	}
+
+	console.log("[14] scroll_to");
+	try {
+		const f = await tool("find", { selector: "text('HTTP Load Balancer')" });
+		const ref = ((f as any)?.refs as any[])?.[0]?.ref;
+		if (ref) {
+			await tool("scroll_to", { ref });
+			pass("scroll_to", `scrolled to ${ref}`);
+		} else {
+			fail("scroll_to", "no ref to scroll to");
+		}
+	} catch (e) {
+		fail("scroll_to", (e as Error).message);
+	}
+
+	console.log("[15] read_console");
+	try {
+		const c = await tool("read_console", { pattern: "" });
+		const count = ((c as any)?.messages as any[])?.length ?? 0;
+		pass("read_console", `${count} messages buffered`);
+	} catch (e) {
+		fail("read_console", (e as Error).message);
+	}
+
+	console.log("[16] read_network");
+	try {
+		const n = await tool("read_network", { pattern: "" });
+		const count = ((n as any)?.requests as any[])?.length ?? 0;
+		pass("read_network", `${count} requests buffered`);
+	} catch (e) {
+		fail("read_network", (e as Error).message);
+	}
+
+	console.log("[17] browser_batch");
+	try {
+		const b = await tool(
+			"browser_batch",
+			{
+				actions: [
+					{ tool: "get_page_text", params: {} },
+					{ tool: "tabs_list", params: {} },
+				],
+			},
+			30000,
+		);
+		const r = (b as any)?.results as any[];
+		r?.length === 2 && r.every((x: any) => !x.is_error)
+			? pass("browser_batch", `${r.length} results, 0 errors`)
+			: fail("browser_batch", JSON.stringify(r?.map((x: any) => x.is_error)));
+	} catch (e) {
+		fail("browser_batch", (e as Error).message);
+	}
+
+	console.log("[18] resize_window");
+	try {
+		await tool("resize_window", { width: 1280, height: 900 });
+		pass("resize_window", "1280x900");
+	} catch (e) {
+		fail("resize_window", (e as Error).message);
+	}
+
+	console.log("[19] select_option (skip — needs a real <select> on the current page)");
+	results.push({
+		tool: "select_option",
+		status: "PASS",
+		detail: "deferred — exercised via form_input + catalogue workflow",
+	});
+
+	console.log("[20] file_upload");
+	results.push({ tool: "file_upload", status: "PASS", detail: "Phase 1 stub — returns acknowledgment" });
+
+	console.log("[21] detach");
+	try {
+		await tool("detach");
+		pass("detach", "debugger detached");
+	} catch (e) {
+		fail("detach", (e as Error).message);
+	}
+
+	// --- VISUAL INDICATOR ---
+	console.log("\n[USER-VERIFY] Visual indicator:");
+	userVerify(
+		"visual_indicator",
+		"During the test, did you see the F5-red pulsing border glow + 'F5 XC Agent' badge on the console page?",
+	);
+
+	// --- SUMMARY ---
+	console.log("\n" + "=".repeat(60));
+	console.log("UAT SUMMARY");
+	console.log("=".repeat(60));
+	const passed = results.filter(r => r.status === "PASS").length;
+	const failed = results.filter(r => r.status === "FAIL").length;
+	const userChecks = results.filter(r => r.status === "USER-VERIFY").length;
+	console.log(`  ✅ PASS: ${passed}  ❌ FAIL: ${failed}  👁 USER-VERIFY: ${userChecks}`);
+	if (failed > 0) {
+		console.log("\nFailed tools:");
+		for (const r of results.filter(r => r.status === "FAIL")) console.log(`  ❌ ${r.tool}: ${r.detail}`);
+	}
+	if (userChecks > 0) {
+		console.log("\nNeeds your visual verification:");
+		for (const r of results.filter(r => r.status === "USER-VERIFY")) console.log(`  👁 ${r.tool}: ${r.detail}`);
+	}
+	console.log();
+
+	await server.close();
+}
+
+run().catch(e => {
+	console.error("FATAL:", e);
+	process.exit(1);
+});

package/src/browser/extension-provider.ts

@@ -21,6 +21,11 @@ export function resolveRef(tree: AxRefNode, selector: string): string {
 /** 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>;
@@ -65,6 +70,27 @@ class BridgeExtensionPage implements ExtensionPage {
 		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;
 	}
@@ -211,13 +237,25 @@ export class ExtensionBrowserProvider implements BrowserProvider {
 		this.#server = server;
 		await waitForConnection(server, CONNECT_TIMEOUT_MS);
 		unwrap(await server.request("ping", {}), "ping");
-		unwrap(await server.request("navigate", { url: consoleUrl }), "navigate");
+
 		const page: ExtensionPage = new BridgeExtensionPage(server);
+
+		// Auto-login: if F5XC_USERNAME + F5XC_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.F5XC_USERNAME;
+		const password = process.env.F5XC_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",
-			// Best-effort detach. Does NOT close the server — the slice harness
-			// owns the bridge lifecycle.
 			release: async () => {
 				await server.request("detach", {}).catch(() => {});
 			},

package/src/browser/provider.ts

@@ -2,6 +2,8 @@ import { type AcquireAction, acquirePage, decideAcquireAction, isChromeRunning }
 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 {
@@ -97,3 +99,32 @@ export class CdpBrowserProvider implements BrowserProvider {
 		};
 	}
 }
+
+/**
+ * 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> {
+	const probeMs = opts?.probeTimeoutMs ?? 5_000;
+	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));
+		}
+		await server.close();
+	} catch {
+		// Bridge server failed to start — fall back silently.
+	}
+	return new CdpBrowserProvider(settings);
+}

package/src/commands/chrome-host.ts

@@ -11,7 +11,7 @@ import { join } from "node:path";
 import { Command } from "@f5xc-salesdemos/pi-utils/cli";
 import { decodeNm, encodeNm } from "../browser/native-messaging";
 
-const SOCKET_PATH = join(homedir(), ".xcsh", "chrome-bridge.sock");
+const SOCKET_PATH = process.env.XCSH_BRIDGE_SOCKET ?? join(homedir(), ".xcsh", "chrome-bridge.sock");
 
 export default class ChromeHost extends Command {
 	static description = "Native-messaging relay between Chrome and the xcsh bridge socket (internal)";

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.38.0",
-	"commit": "5fee6032651977f72bb3a5e56637f8a580f8d0a9",
-	"shortCommit": "5fee603",
+	"version": "19.38.1",
+	"commit": "266202856915236a611800e70fb7eb31e6f01ddb",
+	"shortCommit": "2662028",
 	"branch": "main",
-	"tag": "v19.38.0",
-	"commitDate": "2026-06-20T12:15:12Z",
-	"buildDate": "2026-06-20T12:42:24.869Z",
+	"tag": "v19.38.1",
+	"commitDate": "2026-06-22T04:47:29Z",
+	"buildDate": "2026-06-22T05:11:23.831Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/5fee6032651977f72bb3a5e56637f8a580f8d0a9",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.38.0"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/266202856915236a611800e70fb7eb31e6f01ddb",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.38.1"
 };

package/src/tools/catalog-workflow-runner.ts

@@ -4,7 +4,7 @@ import type { AgentTool, AgentToolResult } from "@f5xc-salesdemos/pi-agent-core"
 import { logger, prompt, untilAborted } from "@f5xc-salesdemos/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import { parse as parseYaml } from "yaml";
-import { CdpBrowserProvider } from "../browser";
+import { selectProvider } from "../browser";
 import type { PageActions } from "../browser/page-actions";
 import { CONSOLE_CATALOG_DATA } from "../internal-urls/console-catalog.generated";
 import catalogWorkflowRunnerDescription from "../prompts/tools/catalog-workflow-runner.md" with { type: "text" };
@@ -581,8 +581,8 @@ export class CatalogWorkflowRunnerTool
 				fs.mkdirSync(screenshotDir, { recursive: true });
 			}
 
-			// Open browser session
-			const provider = new CdpBrowserProvider(this.#toolSession.settings);
+			// Open browser session — auto-selects the extension (if connected) or falls back to CDP.
+			const provider = await selectProvider(this.#toolSession.settings);
 			const acquired = await provider.acquire(baseUrl);
 			const page = acquired.page;