@f5-sales-demo/xcsh 19.72.0 → 19.73.0

package/package.json

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

package/src/browser/extension-bridge-tools.ts

@@ -69,3 +69,31 @@ export function createExtensionBridgeTools(bridge: BridgeServer): CustomTool<TSc
 export const EXTENSION_AGENT_TOOL_NAMES: readonly string[] = EXTENSION_CAPABILITIES.tools
 	.filter(def => !INTERNAL_TOOLS.has(def.name))
 	.map(def => def.name);
+
+/**
+ * Builtin agent tools scoped into a headless browser-bridge session (the Chrome
+ * extension worker and the Office `serve` bridge). Shared so both bootstraps use
+ * one list. Office document tools are NOT here — the pane advertises those over
+ * the bridge via `set_host_tools`, registered at runtime by the ChatHandler.
+ */
+export const BROWSER_TOOL_NAMES: readonly string[] = [
+	"catalog_workflow_runner",
+	"navigate",
+	"click",
+	"click_element",
+	"fill",
+	"type_text",
+	"screenshot",
+	"login",
+	"read_ax",
+	"get_page_context",
+	"query_dom",
+	"find",
+	"wait_for",
+	"key_press",
+	"select_option",
+	"label_select",
+	"scroll_to",
+	"annotate",
+	"set_explain_mode",
+];

package/src/browser/headless-bridge.ts

@@ -0,0 +1,164 @@
+/**
+ * Headless chat bridge — the no-TUI extension-bridge host used by `xcsh office
+ * serve` so one command yields a working task pane (pane files + a live chat/
+ * host-tool bridge). It mirrors the proven `xcsh worker` bootstrap
+ * (`commands/worker.ts`) MINUS the fleet concerns (manager keepalive, pre-warm
+ * IPC bind, TTFT spans): set the browser-provider env, init Settings + Context,
+ * quiet startup, provision the wss cert, start the bridge, publish session info,
+ * create ONE agent session scoped to the browser tools, and attach the
+ * `ChatHandler`. Office document tools (Excel/Word/PPT) are advertised by the
+ * pane at runtime over the bridge (`set_host_tools`), so they need no scoping here.
+ *
+ * The heavy / socket / network calls are injected (defaulting to the real ones)
+ * so the wiring is unit-testable without opening real listeners or a session.
+ *
+ * NOT browser-safe (node/bun): runs inside the full xcsh binary, never the pane.
+ */
+import { getProjectDir, getXCSHConfigDir } from "@f5-sales-demo/pi-utils";
+import { createAgentSession } from "../sdk";
+import { ContextService } from "../services/xcsh-context";
+import { deriveTenantEnv } from "../services/xcsh-env";
+import { resolveBridgeTls } from "./bridge-cert";
+import { ChatHandler } from "./chat-handler";
+import { type BridgeServer, startBridgeServer } from "./extension-bridge";
+import { BROWSER_TOOL_NAMES, createExtensionBridgeTools, EXTENSION_AGENT_TOOL_NAMES } from "./extension-bridge-tools";
+import { setSharedBridgeServer } from "./provider";
+
+/** A running headless bridge + a teardown that disposes the chat handler and
+ *  closes the bridge (both ws + wss listeners). */
+export interface HeadlessChatBridge {
+	bridge: BridgeServer;
+	dispose: () => Promise<void>;
+}
+
+/**
+ * Tenant identity for the `hello` handshake, contextless-friendly: the active
+ * `/context` wins (its apiUrl + name), otherwise fall back to the `XCSH_API_URL`/
+ * `XCSH_SESSION_TENANT` env so the pane still learns which tenant this process
+ * serves. Sync — the bridge calls it while answering `hello`. Mirrors the
+ * interactive path in `main.ts` (there is no per-tab session id here).
+ */
+export function sessionInfoForOfficeServe(): {
+	tenant: string | null;
+	env: string | null;
+	apiUrl: string | null;
+	contextBound: boolean;
+	sessionId: string | null;
+} {
+	let apiUrl: string | null = null;
+	let contextBound = false;
+	try {
+		apiUrl = ContextService.instance.activeApiUrl;
+		contextBound = ContextService.instance.getStatus().activeContextName != null;
+	} catch {
+		/* ContextService not initialized — env-only mode. */
+	}
+	apiUrl = apiUrl ?? process.env.XCSH_API_URL ?? null;
+	const tenantKey = process.env.XCSH_SESSION_TENANT ?? null;
+	const { tenant, env } = deriveTenantEnv(apiUrl, tenantKey);
+	return { tenant, env, apiUrl, contextBound, sessionId: null };
+}
+
+/** Injectable seams (defaulted to the real ones) so the bootstrap is testable. */
+export interface HeadlessBridgeDeps {
+	/** Set the browser-provider env, init Settings + ContextService + provider
+	 *  persistence, and quiet startup; returns the project cwd for the session. */
+	initEnv: () => Promise<{ cwd: string }>;
+	resolveBridgeTls: typeof resolveBridgeTls;
+	startBridgeServer: typeof startBridgeServer;
+	setSharedBridgeServer: typeof setSharedBridgeServer;
+	createExtensionBridgeTools: typeof createExtensionBridgeTools;
+	createAgentSession: typeof createAgentSession;
+	ChatHandlerCtor: typeof ChatHandler;
+}
+
+const defaultDeps: HeadlessBridgeDeps = {
+	initEnv: async () => {
+		process.env.XCSH_BROWSER_PROVIDER = "extension";
+		const cwd = getProjectDir();
+		const { Settings, settings } = await import("../config/settings");
+		await Settings.init({ cwd });
+		// Init the ContextService singleton so sessionInfoForOfficeServe can read the
+		// active apiUrl once a /context is bound.
+		try {
+			ContextService.init(getXCSHConfigDir());
+		} catch {
+			/* already initialized / unavailable — continue. */
+		}
+		// Provider persistence for model discovery (parity with main.ts / worker.ts).
+		const { initializeWithSettings } = await import("../discovery");
+		initializeWithSettings(settings);
+		// Quiet startup: skip the welcome screen + blocking plugin "Fix now?" prompts.
+		settings.override("startup.quiet", true);
+		return { cwd };
+	},
+	resolveBridgeTls,
+	startBridgeServer,
+	setSharedBridgeServer,
+	createExtensionBridgeTools,
+	createAgentSession,
+	ChatHandlerCtor: ChatHandler,
+};
+
+/**
+ * Start the headless chat bridge and return it with a teardown. Fully awaits the
+ * session + ChatHandler.attach() before resolving, so once this resolves the pane
+ * can connect and chat immediately (no warm-up race). A `configure`-less pane
+ * chats over xcsh's already-configured provider.
+ */
+export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = defaultDeps): Promise<HeadlessChatBridge> {
+	const { cwd } = await deps.initEnv();
+
+	// Provision the wss cert before binding (warm boot = on-disk cache hit);
+	// `undefined` (offline) → the bridge starts ws-only.
+	const tls = await deps.resolveBridgeTls();
+	const bridge = await deps.startBridgeServer(undefined, tls ? { tls } : undefined);
+	// Reuse this bridge for any in-process selectProvider() (no conflicting second bridge).
+	deps.setSharedBridgeServer(bridge);
+	bridge.setSessionInfo(sessionInfoForOfficeServe);
+	// Re-announce the tenant when the active context changes (best-effort).
+	try {
+		ContextService.onContextChange(() => bridge.broadcastTenantChanged());
+	} catch {
+		/* ContextService not initialized (tests) — the tenant is static. */
+	}
+
+	// Everything past the bind can throw (createAgentSession on a misconfigured
+	// provider, etc.). If it does, close the already-bound bridge and clear the
+	// shared-bridge global before rethrowing — otherwise the ws/wss listeners leak
+	// (keeping the event loop alive so Ctrl+C can't exit) and a later in-process
+	// selectProvider() reuses a dead bridge. The caller (startOfficeServe) treats
+	// the rethrow as a non-fatal "pane only" fallback.
+	try {
+		// Turn the extension's browser actions into bridge-proxying CustomTools, then
+		// create ONE headless session scoped to the browser tools (Office document
+		// tools arrive at runtime via set_host_tools).
+		const extensionTools = deps.createExtensionBridgeTools(bridge);
+		const { session } = await deps.createAgentSession({
+			cwd,
+			hasUI: false,
+			toolNames: [...new Set([...BROWSER_TOOL_NAMES, ...EXTENSION_AGENT_TOOL_NAMES])],
+			customTools: extensionTools,
+			// Headless: no MCP/LSP/extension discovery — lean, no network/blocking prompts.
+			enableMCP: false,
+			enableLsp: false,
+			disableExtensionDiscovery: true,
+		});
+
+		const chatHandler = new deps.ChatHandlerCtor(bridge, session);
+		chatHandler.attach();
+
+		return {
+			bridge,
+			dispose: async () => {
+				chatHandler.dispose();
+				deps.setSharedBridgeServer(null);
+				await bridge.close();
+			},
+		};
+	} catch (err) {
+		deps.setSharedBridgeServer(null);
+		await bridge.close();
+		throw err;
+	}
+}

package/src/browser/provider.ts

@@ -115,7 +115,10 @@ export class CdpBrowserProvider implements BrowserProvider {
  * instead of starting a conflicting second one on the same port.
  */
 let _sharedBridgeServer: import("./extension-bridge").BridgeServer | null = null;
-export function setSharedBridgeServer(server: import("./extension-bridge").BridgeServer): void {
+/** Publish (or, with `null`, clear) the process-shared bridge. Clearing is
+ *  required when a partially-started bridge is torn down (e.g. session bootstrap
+ *  failed after bind) so a later `selectProvider()` never reuses a closed bridge. */
+export function setSharedBridgeServer(server: import("./extension-bridge").BridgeServer | null): void {
 	_sharedBridgeServer = server;
 }
 

package/src/cli/office-cli.ts

@@ -9,7 +9,14 @@
  */
 import { spawnSync } from "node:child_process";
 import * as path from "node:path";
-import { getOfficePaneDir, readManifest, startOfficePaneServer } from "../browser/office-pane-server";
+import { LOCALIP_HOST } from "../browser/bridge-cert";
+import { type HeadlessChatBridge, startHeadlessChatBridge } from "../browser/headless-bridge";
+import {
+	getOfficePaneDir,
+	type OfficePaneServer,
+	readManifest,
+	startOfficePaneServer,
+} from "../browser/office-pane-server";
 
 /** The subcommands `xcsh office` accepts (also the Args `options` constraint). */
 export const OFFICE_ACTIONS = ["serve", "manifest", "sideload"] as const;
@@ -39,9 +46,53 @@ export async function writeManifest(outPath?: string): Promise<string> {
 	return text;
 }
 
-/** Start the :8444 listener, print the task-pane URL, and block until killed. */
+/** Injectable seams for {@link startOfficeServe} (defaulted to the real ones). */
+export interface OfficeServeDeps {
+	startOfficePaneServer: typeof startOfficePaneServer;
+	startHeadlessChatBridge: typeof startHeadlessChatBridge;
+}
+
+const defaultServeDeps: OfficeServeDeps = { startOfficePaneServer, startHeadlessChatBridge };
+
+/** A running `office serve`: the pane file server, the (optional) chat bridge, and
+ *  a teardown that disposes both. */
+export interface OfficeServeHandle {
+	server: OfficePaneServer;
+	chat: HeadlessChatBridge | null;
+	dispose: () => Promise<void>;
+}
+
+/**
+ * Start BOTH the :8444 pane file server AND the headless chat bridge, so one
+ * `xcsh office serve` yields a working pane (no separately-run bridge). A bridge
+ * failure is NON-fatal: the pane still serves and we warn, so `serve` degrades to
+ * "pane only" rather than failing outright. Returns a teardown that disposes both.
+ * Extracted from {@link runServe} so the start/teardown wiring is unit-testable.
+ */
+export async function startOfficeServe(deps: OfficeServeDeps = defaultServeDeps): Promise<OfficeServeHandle> {
+	const server = await deps.startOfficePaneServer();
+	let chat: HeadlessChatBridge | null = null;
+	try {
+		chat = await deps.startHeadlessChatBridge();
+	} catch (err) {
+		console.warn(
+			`Warning: the chat bridge could not start (${err instanceof Error ? err.message : String(err)}). ` +
+				"The task pane will load but chat is unavailable until a bridge is running.",
+		);
+	}
+	return {
+		server,
+		chat,
+		dispose: async () => {
+			if (chat) await chat.dispose();
+			server.stop();
+		},
+	};
+}
+
+/** Start the pane server + chat bridge, print status, and block until killed. */
 async function runServe(): Promise<void> {
-	const server = await startOfficePaneServer();
+	const { server, chat, dispose } = await startOfficeServe();
 	console.log(`Serving the xcsh Office task pane at ${server.taskpaneUrl}`);
 	if (!server.trusted) {
 		console.warn(
@@ -49,9 +100,26 @@ async function runServe(): Promise<void> {
 				"Office's WebView may refuse to load the page until the cert is trusted.",
 		);
 	}
+	if (chat) {
+		if (chat.bridge.wssPort) {
+			console.log(
+				`Chat bridge ready on wss://${LOCALIP_HOST}:${chat.bridge.wssPort} — the pane connects automatically.`,
+			);
+		} else {
+			console.warn(
+				"Warning: the chat bridge is ws-only (no wss cert). The pane connects over wss and may not reach it.",
+			);
+		}
+	}
 	console.log("Press Ctrl+C to stop.");
-	// Bun.serve holds the event loop open; block run() so the process stays alive.
-	await new Promise<never>(() => {});
+	// Block until a signal tears us down, then dispose the bridge + pane server.
+	await new Promise<void>(resolve => {
+		const shutdown = (): void => {
+			void dispose().finally(resolve);
+		};
+		process.once("SIGINT", shutdown);
+		process.once("SIGTERM", shutdown);
+	});
 }
 
 /** Run the Office sideload against the embedded bundle (best-effort). */

package/src/commands/worker.ts

@@ -20,7 +20,11 @@ import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { LOCALIP_HOST, resolveBridgeTls } from "../browser/bridge-cert";
 import { ChatHandler } from "../browser/chat-handler";
 import { startBridgeServer } from "../browser/extension-bridge";
-import { createExtensionBridgeTools, EXTENSION_AGENT_TOOL_NAMES } from "../browser/extension-bridge-tools";
+import {
+	BROWSER_TOOL_NAMES,
+	createExtensionBridgeTools,
+	EXTENSION_AGENT_TOOL_NAMES,
+} from "../browser/extension-bridge-tools";
 import { setSharedBridgeServer } from "../browser/provider";
 import { coldStartSpans, type SpanFrame, sessionBuildSpan } from "../browser/ttft-spans";
 import { initializeWithSettings } from "../discovery";
@@ -94,28 +98,6 @@ function managerSockPath(): string {
 /** Browser-automation tool set — identical scoping to `main.ts`'s extension path.
  * With scoped tools the ONLY way to create a resource is the form-driven workflow
  * runner, which is exactly what the human watching the browser wants. */
-const BROWSER_TOOL_NAMES = [
-	"catalog_workflow_runner",
-	"navigate",
-	"click",
-	"click_element",
-	"fill",
-	"type_text",
-	"screenshot",
-	"login",
-	"read_ax",
-	"get_page_context",
-	"query_dom",
-	"find",
-	"wait_for",
-	"key_press",
-	"select_option",
-	"label_select",
-	"scroll_to",
-	"annotate",
-	"set_explain_mode",
-];
-
 export default class Worker extends Command {
 	static description = "Run a headless extension-bridge worker (no TUI); blocks until SIGTERM";
 

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.72.0",
-	"commit": "43fbd3cf08806284c4d377bf883d684b838364ca",
-	"shortCommit": "43fbd3c",
+	"version": "19.73.0",
+	"commit": "3f32c968ef8b2a0c9fabbc1be3fbe5c7395a7dc9",
+	"shortCommit": "3f32c96",
 	"branch": "main",
-	"tag": "v19.72.0",
-	"commitDate": "2026-07-22T02:38:28Z",
-	"buildDate": "2026-07-22T03:07:27.733Z",
+	"tag": "v19.73.0",
+	"commitDate": "2026-07-22T04:58:36Z",
+	"buildDate": "2026-07-22T05:24:54.248Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/43fbd3cf08806284c4d377bf883d684b838364ca",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.72.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/3f32c968ef8b2a0c9fabbc1be3fbe5c7395a7dc9",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.73.0"
 };