@f5-sales-demo/xcsh 19.64.3 → 19.66.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.64.3",
+	"version": "19.66.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",
@@ -31,7 +31,7 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
-		"build": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && bun run generate-console-catalog && bun run generate-console-field-metadata && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset",
+		"build": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && bun run generate-console-catalog && bun run generate-console-field-metadata && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../office-pane scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset && bun --cwd=../office-pane scripts/generate-client-bundle.ts --reset",
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
 		"check:types": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.64.3",
-		"@f5-sales-demo/pi-agent-core": "19.64.3",
-		"@f5-sales-demo/pi-ai": "19.64.3",
-		"@f5-sales-demo/pi-natives": "19.64.3",
-		"@f5-sales-demo/pi-resource-management": "19.64.3",
-		"@f5-sales-demo/pi-tui": "19.64.3",
-		"@f5-sales-demo/pi-utils": "19.64.3",
+		"@f5-sales-demo/xcsh-stats": "19.66.0",
+		"@f5-sales-demo/pi-agent-core": "19.66.0",
+		"@f5-sales-demo/pi-ai": "19.66.0",
+		"@f5-sales-demo/pi-natives": "19.66.0",
+		"@f5-sales-demo/pi-resource-management": "19.66.0",
+		"@f5-sales-demo/pi-tui": "19.66.0",
+		"@f5-sales-demo/pi-utils": "19.66.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/capabilities.generated.ts

@@ -26,7 +26,7 @@ export interface ExtensionCapabilities {
 
 export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	"version": "0.1.0",
-	"contractVersion": "1.8.0",
+	"contractVersion": "1.9.0",
 	"multiPortDiscovery": true,
 	"protocol": "tool_request/result",
 	"tools": [
@@ -832,7 +832,10 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 				"host_tool_call",
 				"host_tool_update",
 				"host_tool_result",
-				"host_tool_cancel"
+				"host_tool_cancel",
+				"configure",
+				"configure_ack",
+				"configure_error"
 			],
 			"description": "User ↔ xcsh chat over the bridge. The extension side panel sends chat_request (with mode and page-context snapshot); xcsh streams chat_delta tokens then a terminal chat_done (with reference links) or chat_error. Chat ids are prefixed \"c-\". Tool calls during a turn use the normal tool_request flow. chat_stop halts a streaming response. chat_tool_notice is emitted by the EXTENSION (the service worker) to the panel as a best-effort UI signal when a tool runs during a turn — it is NOT sent by xcsh; xcsh must not produce it to avoid double-rendering in the panel.",
 			"promptHints": {
@@ -852,6 +855,6 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.8.0";
+export const EXTENSION_CONTRACT_VERSION = "1.9.0";
 
 export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","diag_bridges","diag_activation","diag_ttft","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];

package/src/browser/capabilities.json

@@ -1,6 +1,6 @@
 {
   "version": "0.1.0",
-  "contractVersion": "1.8.0",
+  "contractVersion": "1.9.0",
   "multiPortDiscovery": true,
   "protocol": "tool_request/result",
   "tools": [
@@ -740,7 +740,10 @@
         "host_tool_call",
         "host_tool_update",
         "host_tool_result",
-        "host_tool_cancel"
+        "host_tool_cancel",
+        "configure",
+        "configure_ack",
+        "configure_error"
       ],
       "description": "User ↔ xcsh chat over the bridge. The extension side panel sends chat_request (with mode and page-context snapshot); xcsh streams chat_delta tokens then a terminal chat_done (with reference links) or chat_error. Chat ids are prefixed \"c-\". Tool calls during a turn use the normal tool_request flow. chat_stop halts a streaming response. chat_tool_notice is emitted by the EXTENSION (the service worker) to the panel as a best-effort UI signal when a tool runs during a turn — it is NOT sent by xcsh; xcsh must not produce it to avoid double-rendering in the panel.",
       "promptHints": {

package/src/browser/chat-conformance.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.8.0",
+  "contractVersion": "1.9.0",
   "schemas": {
     "chat_request": {
       "type": "object",
@@ -356,6 +356,52 @@
         }
       }
     },
+    "configure": {
+      "type": "object",
+      "required": ["type", "token"],
+      "properties": {
+        "type": {
+          "const": "configure",
+          "type": "string"
+        },
+        "baseUrl": {
+          "type": "string"
+        },
+        "token": {
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "type": "string"
+        }
+      }
+    },
+    "configure_ack": {
+      "type": "object",
+      "required": ["type", "model"],
+      "properties": {
+        "type": {
+          "const": "configure_ack",
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        }
+      }
+    },
+    "configure_error": {
+      "type": "object",
+      "required": ["type", "error"],
+      "properties": {
+        "type": {
+          "const": "configure_error",
+          "type": "string"
+        },
+        "error": {
+          "type": "string"
+        }
+      }
+    },
     "host_tool_call": {
       "type": "object",
       "required": ["type", "id", "toolCallId", "toolName", "arguments"],
@@ -713,6 +759,24 @@
         "type": "set_host_tools_error",
         "error": "Host tool \"office_read_range\" must provide a non-empty description"
       },
+      "configure": {
+        "type": "configure",
+        "baseUrl": "https://f5ai.pd.f5net.com/anthropic",
+        "token": "sk-example-token-123",
+        "model": "claude-opus-4-8"
+      },
+      "configure_no_baseUrl": {
+        "type": "configure",
+        "token": "sk-example-token-123"
+      },
+      "configure_ack": {
+        "type": "configure_ack",
+        "model": "claude-opus-4-8"
+      },
+      "configure_error": {
+        "type": "configure_error",
+        "error": "No model anthropic/claude-opus-4-8 available"
+      },
       "host_tool_call": {
         "type": "host_tool_call",
         "id": "7295551234567890",
@@ -933,6 +997,23 @@
             "content": "nope"
           }
         }
+      },
+      {
+        "schema": "configure",
+        "why": "token missing",
+        "value": {
+          "type": "configure",
+          "baseUrl": "https://f5ai.pd.f5net.com/anthropic",
+          "model": "claude-opus-4-8"
+        }
+      },
+      {
+        "schema": "configure",
+        "why": "token empty",
+        "value": {
+          "type": "configure",
+          "token": ""
+        }
       }
     ]
   }

package/src/browser/chat-handler.ts

@@ -1,4 +1,5 @@
 import type { AssistantMessage } from "@f5-sales-demo/pi-ai";
+import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
 import {
 	isRpcHostToolResult,
 	isRpcHostToolUpdate,
@@ -14,11 +15,15 @@ import {
 	type ChatKeepalive,
 	type ChatReference,
 	type ChatRequest,
+	type Configure,
+	type ConfigureAck,
+	type ConfigureError,
 	type HostToolResult,
 	type HostToolUpdate,
 	type InteractionMode,
 	isChatRequest,
 	isChatStop,
+	isConfigure,
 	isSetHostTools,
 	type PageContextSnapshot,
 	type SetHostTools,
@@ -92,6 +97,9 @@ export class ChatHandler {
 			// Host-tool channel (#2046): register client tools, then route the client's
 			// result/update frames back to the correlated pending call in the bridge.
 			else if (isSetHostTools(msg)) this.#handleSetHostTools(msg as unknown as SetHostTools);
+			// Provider configuration channel (#2095): swap the LLM provider/model in
+			// session memory at runtime (never persisted), then ack or nack.
+			else if (isConfigure(msg)) this.#handleConfigure(msg as unknown as Configure);
 			else if (isRpcHostToolResult(msg)) this.#hostToolBridge.handleResult(msg as unknown as HostToolResult);
 			else if (isRpcHostToolUpdate(msg)) this.#hostToolBridge.handleUpdate(msg as unknown as HostToolUpdate);
 		});
@@ -287,6 +295,70 @@ export class ChatHandler {
 		}
 	}
 
+	/** Configure the LLM provider at runtime from a bridge client (#2095), then ack
+	 * with the selected model so the client can await it before its first prompt.
+	 * SESSION/RUNTIME MEMORY ONLY — the token is never written to models.yml or the
+	 * SQLite credential store. Mirrors #handleSetHostTools's try/ack-or-nack shape;
+	 * never throws out of the handler (a nack keeps a waiting client from hanging).
+	 *
+	 * The baked F5 gateway registers its models under the "anthropic" provider
+	 * (DEFAULT_MODEL_ROLE = "anthropic/claude-opus-4-8"), so that is the provider we
+	 * (re)configure here. */
+	async #handleConfigure(msg: Configure): Promise<void> {
+		try {
+			const registry = this.#session.modelRegistry;
+			const [provider, defaultModelId] = DEFAULT_MODEL_ROLE.split("/");
+
+			if (msg.baseUrl) {
+				// SSRF guard: only an `https:` gateway URL may be dialed. Validate BEFORE
+				// registerProvider so a bad URL becomes a configure_error nack (never a
+				// silently-ignored frame that hangs the client). We deliberately do NOT
+				// block loopback/RFC-1918 targets: an operator-chosen INTERNAL gateway is
+				// the whole point (the F5 LiteLLM gateway, and the claude-office CORS proxy
+				// at https://127-0-0-1.local-ip.sh:8443 are legitimate targets).
+				//
+				// Accepted residual (user-requested tradeoff): the operator points xcsh at
+				// THEIR OWN gateway with THEIR OWN token over a loopback-only, TLS,
+				// Origin-checked bridge (extension-bridge `isAllowedBridgeOrigin`), https is
+				// enforced here, and the token is session-only (never persisted to disk).
+				const baseUrl = requireHttpsUrl(msg.baseUrl);
+
+				// baseUrl + apiKey, no models[] → sets the in-memory runtime API key AND
+				// overrides the existing provider models' baseUrl/headers (reusing their
+				// metadata). Nothing is persisted to disk.
+				registry.registerProvider(
+					provider,
+					{
+						baseUrl,
+						apiKey: msg.token,
+						headers: { "anthropic-beta": "context-1m-2025-08-07" },
+					},
+					"office-configure",
+				);
+			} else {
+				// Key-only: reuse the baked F5 gateway; set just the non-persistent runtime key.
+				registry.authStorage.setRuntimeApiKey(provider, msg.token);
+			}
+
+			const modelId = msg.model ?? this.#session.model?.id ?? defaultModelId;
+			const model = registry.find(provider, modelId);
+			if (!model) {
+				throw new Error(`No model ${provider}/${modelId} available`);
+			}
+			// setModel validates the API key and throws if missing → becomes configure_error.
+			await this.#session.setModel(model);
+
+			this.#server.send({ type: "configure_ack", model: model.id } satisfies ConfigureAck);
+		} catch (err) {
+			// Nack instead of throwing (set_host_tools parity): a client awaiting
+			// configure_ack would otherwise hang on a bad frame or missing key.
+			this.#server.send({
+				type: "configure_error",
+				error: err instanceof Error ? err.message : String(err),
+			} satisfies ConfigureError);
+		}
+	}
+
 	#handleChatStop(stop: { id: string }): void {
 		const chat = this.#activeChats.get(stop.id);
 		if (!chat) return;
@@ -322,6 +394,24 @@ export class ChatHandler {
 	}
 }
 
+/** SSRF guard for the `configure` frame's optional gateway `baseUrl`: the URL must
+ * parse and use `https:`. Returns the ORIGINAL string unchanged on success (no
+ * normalization — the operator's exact gateway path is preserved); throws (→ becomes
+ * a `configure_error` nack) for a malformed or non-https URL. Loopback/private hosts
+ * are intentionally NOT blocked — the target is an operator-chosen internal gateway. */
+export function requireHttpsUrl(raw: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		throw new Error(`configure baseUrl is not a valid URL: ${raw}`);
+	}
+	if (parsed.protocol !== "https:") {
+		throw new Error(`configure baseUrl must use https (got "${parsed.protocol}")`);
+	}
+	return raw;
+}
+
 /** Best-effort classification of an upstream/provider error message into a
  * ChatErrorReason so the panel can pick a distinct, actionable message. Returns
  * undefined for an unclassified error (the panel then shows the raw error text).

package/src/browser/chat-protocol.ts

@@ -3,15 +3,17 @@
  * Contract source of truth: capabilities.json v1.2.0.
  */
 
-import {
-	isRpcHostToolResult,
-	isRpcHostToolUpdate,
-	type RpcHostToolCallRequest,
-	type RpcHostToolCancelRequest,
-	type RpcHostToolDefinition,
-	type RpcHostToolResult,
-	type RpcHostToolUpdate,
-} from "../host-tools";
+// Import the guards + wire types from the PURE leaf modules (not the `../host-tools`
+// barrel), so this browser-safe contract can be consumed by a lib.dom (React)
+// TypeScript program without pulling the RpcHostToolBridge's theme/tool-proxy graph.
+import { isRpcHostToolResult, isRpcHostToolUpdate } from "../host-tools/guards";
+import type {
+	RpcHostToolCallRequest,
+	RpcHostToolCancelRequest,
+	RpcHostToolDefinition,
+	RpcHostToolResult,
+	RpcHostToolUpdate,
+} from "../host-tools/types";
 
 // ---------------------------------------------------------------------------
 // Page context snapshot (auto-attached by extension to every chat_request)
@@ -176,6 +178,43 @@ export interface SetHostToolsError {
 	error: string;
 }
 
+// ---------------------------------------------------------------------------
+// Provider configuration channel (contract 1.9.0)
+//
+// Lets a bridge client (the Chrome extension, the office-xcsh add-in) configure
+// xcsh's LLM provider at runtime — after the socket is connected — without
+// restarting the worker and WITHOUT persisting the token to disk. xcsh stays the
+// intelligence engine; this only swaps the provider credentials/model in session
+// memory. Single config in-flight, so — like `set_host_tools` — there is no `id`
+// correlation field. Mirrors the set_host_tools ack/nack shape exactly.
+// ---------------------------------------------------------------------------
+
+/** Inbound: the client configures the LLM provider. `token` is required and
+ * non-empty. `baseUrl` (optional) is an Anthropic-compatible gateway base; when
+ * omitted, the baked F5 gateway is reused and only the runtime API key is set.
+ * `model` (optional) selects the model id; when omitted, the session default is
+ * kept. The token lives in session/runtime memory only — never written to disk. */
+export interface Configure {
+	type: "configure";
+	baseUrl?: string;
+	token: string;
+	model?: string;
+}
+
+/** Outbound: acks a `configure` with the model id actually selected, so the
+ * client can await configuration before its first prompt. */
+export interface ConfigureAck {
+	type: "configure_ack";
+	model: string;
+}
+
+/** Outbound: nacks a `configure` that failed (bad frame, unknown model, missing
+ * API key). Emitted instead of the ack so a client awaiting it never hangs. */
+export interface ConfigureError {
+	type: "configure_error";
+	error: string;
+}
+
 // ---------------------------------------------------------------------------
 // Validators
 // ---------------------------------------------------------------------------
@@ -202,6 +241,18 @@ export function isSetHostTools(msg: Record<string, unknown>): boolean {
 	return msg.type === "set_host_tools" && Array.isArray(msg.tools);
 }
 
+/** True for a well-formed `configure` frame: a non-empty string `token` is required;
+ * `baseUrl`/`model`, when present, must be strings. */
+export function isConfigure(msg: Record<string, unknown>): boolean {
+	return (
+		msg.type === "configure" &&
+		typeof msg.token === "string" &&
+		msg.token.length > 0 &&
+		(msg.baseUrl === undefined || typeof msg.baseUrl === "string") &&
+		(msg.model === undefined || typeof msg.model === "string")
+	);
+}
+
 /** Delegates to the neutral guard, which requires `result.content` to be an array. */
 export function isHostToolResult(msg: Record<string, unknown>): boolean {
 	return isRpcHostToolResult(msg);

package/src/browser/extension-bridge.ts

@@ -398,6 +398,7 @@ export class BridgeServer {
 					contextBound: info.contextBound,
 					pid: process.pid,
 					wssPort: this.wssPort,
+					canConfigureProvider: true,
 				}),
 			);
 		} else {

package/src/browser/office-pane-server.ts

@@ -0,0 +1,183 @@
+/**
+ * Static HTTPS listener for the embedded Office task pane.
+ *
+ * Serves the add-in's page shell + JS bundle + unified manifest + ribbon/app
+ * icons over a FIXED `https://127-0-0-1.local-ip.sh:8444` origin — the exact URL
+ * the manifest's `code.page` and ribbon icon URLs point at. TLS terminates with
+ * the SAME publicly-trusted `*.local-ip.sh` cert the `wss` extension bridge uses
+ * (via {@link resolveBridgeTls}), so Office's WebView loads the page with real
+ * TLS verification and no local trust / MDM step.
+ *
+ * This listener is SEPARATE from the extension bridge and serves ONLY static GET
+ * requests (no WebSocket). It never auto-starts — it is launched exclusively by
+ * `xcsh office serve`, keeping blast radius zero.
+ *
+ * Compiled vs dev (Option A — the pane is a build-time embedded asset of the
+ * binary, not a published library):
+ *  - COMPILED: the base64 tar.gz baked into `office-pane.generated.txt` is
+ *    extracted (once, path-traversal-guarded) to `os.tmpdir()/xcsh-office-pane/<hash>`.
+ *  - DEV: assets are read straight from `packages/office-pane/dist` via a
+ *    filesystem path — never a module import, so no dependency on the private
+ *    office-pane package is introduced.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { LOCALIP_HOST, resolveBridgeTls } from "./bridge-cert";
+import embeddedPaneArchiveTxt from "./office-pane.generated.txt";
+
+/** Fixed listener port — must match the manifest page + ribbon icon URLs. */
+export const OFFICE_PANE_PORT = 8444;
+/** Bind loopback only; the local-ip.sh SAN host resolves here for the WebView. */
+export const OFFICE_PANE_HOSTNAME = "127.0.0.1";
+/** The trusted-origin base URL the task pane is reachable at. */
+export const OFFICE_PANE_URL = `https://${LOCALIP_HOST}:${OFFICE_PANE_PORT}`;
+/** The task-pane page URL (the manifest `code.page`). */
+export const OFFICE_PANE_TASKPANE_URL = `${OFFICE_PANE_URL}/taskpane.html`;
+
+const IS_BUN_COMPILED =
+	Bun.env.PI_COMPILED ||
+	import.meta.url.includes("$bunfs") ||
+	import.meta.url.includes("~BUN") ||
+	import.meta.url.includes("%7EBUN");
+
+// Dev-mode assets: packages/coding-agent/src/browser → packages/office-pane/dist.
+const DEV_DIST_DIR = path.resolve(import.meta.dir, "..", "..", "..", "office-pane", "dist");
+const COMPILED_DIR_ROOT = path.join(os.tmpdir(), "xcsh-office-pane");
+
+const getEmbeddedArchive = (() => {
+	const txt = embeddedPaneArchiveTxt.replaceAll(/[\s\r\n]/g, "").trim();
+	if (!txt) return null;
+	return () => Buffer.from(txt, "base64");
+})();
+
+let compiledDirPromise: Promise<string> | null = null;
+
+/**
+ * Sanitize an archive-relative path, rejecting anything that would escape the
+ * extraction/serve root (`..`, absolute paths, empty/`.`). Returns the
+ * normalized forward-slash path, or `null` when the input is unsafe.
+ */
+export function sanitizeArchivePath(archivePath: string): string | null {
+	const normalized = archivePath.replaceAll("\\", "/").replace(/^\.\//, "");
+	if (!normalized || normalized === ".") return null;
+	if (normalized.includes("..") || path.isAbsolute(normalized)) return null;
+	return normalized;
+}
+
+async function extractEmbeddedArchive(archiveBytes: Buffer, outputDir: string): Promise<void> {
+	const archive = new Bun.Archive(archiveBytes);
+	const files = await archive.files();
+	const extractRoot = path.resolve(outputDir);
+
+	for (const [archivePath, file] of files) {
+		const sanitizedPath = sanitizeArchivePath(archivePath);
+		if (!sanitizedPath) continue;
+		const destinationPath = path.resolve(extractRoot, sanitizedPath);
+		if (!destinationPath.startsWith(extractRoot + path.sep)) {
+			throw new Error(`Archive entry escapes extraction directory: ${archivePath}`);
+		}
+		await Bun.write(destinationPath, file);
+	}
+}
+
+/**
+ * Resolve the directory the assets are served from: the extracted embedded
+ * bundle in a compiled binary, else `packages/office-pane/dist` in dev.
+ */
+export async function getOfficePaneDir(): Promise<string> {
+	if (!IS_BUN_COMPILED) return DEV_DIST_DIR;
+	if (compiledDirPromise) return compiledDirPromise;
+
+	const archiveBytes = getEmbeddedArchive?.();
+	if (!archiveBytes) {
+		throw new Error("Compiled office-pane bundle missing. Rebuild the binary with the embedded office-pane assets.");
+	}
+
+	compiledDirPromise = (async () => {
+		const bundleHash = Bun.hash(archiveBytes).toString(16);
+		const outputDir = path.join(COMPILED_DIR_ROOT, bundleHash);
+		const markerPath = path.join(outputDir, "taskpane.html");
+		try {
+			if ((await fs.stat(markerPath)).isFile()) return outputDir;
+		} catch {}
+
+		await fs.rm(outputDir, { recursive: true, force: true });
+		await fs.mkdir(outputDir, { recursive: true });
+		await extractEmbeddedArchive(archiveBytes, outputDir);
+		return outputDir;
+	})();
+
+	return compiledDirPromise;
+}
+
+/**
+ * Pure request handler: map a URL pathname to a file under `dir` and return it
+ * with the content-type inferred from its extension, or a 404. `/` maps to
+ * `taskpane.html`. Path-traversal is rejected before any filesystem access.
+ */
+export async function handleAssetRequest(pathname: string, dir: string): Promise<Response> {
+	const requested = pathname === "/" ? "taskpane.html" : pathname.replace(/^\/+/, "");
+	const safe = sanitizeArchivePath(requested);
+	if (!safe) return new Response("Not Found", { status: 404 });
+
+	const root = path.resolve(dir);
+	const fullPath = path.resolve(root, safe);
+	if (fullPath !== root && !fullPath.startsWith(root + path.sep)) {
+		return new Response("Not Found", { status: 404 });
+	}
+
+	const file = Bun.file(fullPath);
+	if (await file.exists()) return new Response(file);
+	return new Response("Not Found", { status: 404 });
+}
+
+/** Read the embedded/dev manifest.json as text (for `xcsh office manifest`). */
+export async function readManifest(): Promise<string> {
+	const dir = await getOfficePaneDir();
+	return Bun.file(path.join(dir, "manifest.json")).text();
+}
+
+export interface OfficePaneServer {
+	port: number;
+	url: string;
+	taskpaneUrl: string;
+	/** true when a publicly-trusted `*.local-ip.sh` cert is in use. */
+	trusted: boolean;
+	stop: () => void;
+}
+
+/**
+ * Start the fixed :8444 HTTPS listener serving the embedded/dev assets. Resolves
+ * TLS via {@link resolveBridgeTls} (the shared local-ip.sh cert). Serves only GET
+ * (405 otherwise); unknown paths return 404.
+ */
+export async function startOfficePaneServer(port = OFFICE_PANE_PORT): Promise<OfficePaneServer> {
+	const dir = await getOfficePaneDir();
+	const tls = await resolveBridgeTls();
+
+	const server = Bun.serve({
+		port,
+		hostname: OFFICE_PANE_HOSTNAME,
+		tls,
+		async fetch(req) {
+			if (req.method !== "GET" && req.method !== "HEAD") {
+				return new Response("Method Not Allowed", { status: 405 });
+			}
+			try {
+				const url = new URL(req.url);
+				return await handleAssetRequest(url.pathname, dir);
+			} catch (error) {
+				return new Response(error instanceof Error ? error.message : "Internal Server Error", { status: 500 });
+			}
+		},
+	});
+
+	return {
+		port: server.port ?? port,
+		url: OFFICE_PANE_URL,
+		taskpaneUrl: OFFICE_PANE_TASKPANE_URL,
+		trusted: tls !== undefined,
+		stop: () => server.stop(),
+	};
+}

package/src/cli/office-cli.ts

@@ -0,0 +1,107 @@
+/**
+ * `xcsh office` command handlers.
+ *
+ * Drives the embedded Office task pane: start its fixed :8444 HTTPS listener
+ * (`serve`), emit the unified manifest (`manifest`), or sideload it into a
+ * desktop Office app (`sideload`). The serving/embed logic lives in
+ * `../browser/office-pane-server`; this module is the thin, testable CLI seam
+ * mirroring `stats-cli.ts` / `chrome-cli.ts`.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { 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;
+export type OfficeAction = (typeof OFFICE_ACTIONS)[number];
+
+/** Desktop Office apps a sideload can target. */
+export const OFFICE_APPS = ["excel", "powerpoint", "word"] as const;
+export type OfficeApp = (typeof OFFICE_APPS)[number];
+
+export interface OfficeCommandArgs {
+	action: OfficeAction;
+	/** Target app for `sideload` (defaults to excel). */
+	app?: OfficeApp;
+	/** Optional output path for `manifest`; when omitted, print to stdout. */
+	out?: string;
+}
+
+/**
+ * Resolve the manifest text and optionally write it to `outPath`. Returns the
+ * manifest JSON string. Exposed for unit testing.
+ */
+export async function writeManifest(outPath?: string): Promise<string> {
+	const text = await readManifest();
+	if (outPath) {
+		await Bun.write(outPath, text);
+	}
+	return text;
+}
+
+/** Start the :8444 listener, print the task-pane URL, and block until killed. */
+async function runServe(): Promise<void> {
+	const server = await startOfficePaneServer();
+	console.log(`Serving the xcsh Office task pane at ${server.taskpaneUrl}`);
+	if (!server.trusted) {
+		console.warn(
+			"Warning: a publicly-trusted local-ip.sh cert could not be provisioned; using a self-signed fallback. " +
+				"Office's WebView may refuse to load the page until the cert is trusted.",
+		);
+	}
+	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>(() => {});
+}
+
+/** Emit the manifest to a temp file and run the Office sideload (best-effort). */
+async function runSideload(app: OfficeApp): Promise<void> {
+	const text = await readManifest();
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "xcsh-office-sideload-"));
+	const manifestPath = path.join(dir, "manifest.json");
+	await Bun.write(manifestPath, text);
+	console.log(`Wrote manifest to ${manifestPath}`);
+	console.log(`Sideloading into ${app} (requires the office-addin-debugging / atk tool on PATH)...`);
+
+	const result = spawnSync("office-addin-debugging", ["start", manifestPath, "desktop", "--app", app], {
+		stdio: "inherit",
+	});
+	if (result.error) {
+		const code = (result.error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			console.error(
+				"office-addin-debugging was not found on PATH. Install it (e.g. `npm i -g office-addin-debugging` " +
+					"or `npm i -g @microsoft/m365agentstoolkit-cli` for `atk`), then run:\n" +
+					`  office-addin-debugging start ${manifestPath} desktop --app ${app}`,
+			);
+			return;
+		}
+		throw result.error;
+	}
+	if (typeof result.status === "number" && result.status !== 0) {
+		console.error(`office-addin-debugging exited with status ${result.status}.`);
+	}
+}
+
+/** Dispatch an `xcsh office <action>` invocation. */
+export async function runOfficeCommand(args: OfficeCommandArgs): Promise<void> {
+	switch (args.action) {
+		case "serve":
+			await runServe();
+			return;
+		case "manifest": {
+			const text = await writeManifest(args.out);
+			if (args.out) {
+				console.log(`Wrote manifest to ${args.out}`);
+			} else {
+				console.log(text);
+			}
+			return;
+		}
+		case "sideload":
+			await runSideload(args.app ?? "excel");
+			return;
+	}
+}

package/src/cli.ts

@@ -58,6 +58,7 @@ const commands: CommandEntry[] = [
 	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
 	{ name: "jupyter", load: () => import("./commands/jupyter").then(m => m.default) },
 	{ name: "manager", load: () => import("./commands/manager").then(m => m.default) },
+	{ name: "office", load: () => import("./commands/office").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
 	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },

package/src/commands/office.ts

@@ -0,0 +1,42 @@
+/**
+ * Serve, print, or sideload the embedded xcsh Office task pane.
+ */
+import { Args, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { OFFICE_ACTIONS, OFFICE_APPS, type OfficeAction, type OfficeApp, runOfficeCommand } from "../cli/office-cli";
+
+export default class Office extends Command {
+	static description = "Serve, print, or sideload the embedded xcsh Office task pane";
+
+	static args = {
+		action: Args.string({
+			description: "serve | manifest | sideload",
+			required: false,
+			options: OFFICE_ACTIONS,
+		}),
+		app: Args.string({
+			description: "Office app for sideload (excel | powerpoint | word)",
+			required: false,
+			options: OFFICE_APPS,
+		}),
+	};
+
+	static flags = {
+		out: Flags.string({ char: "o", description: "Write manifest.json to this path (manifest action)" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Office);
+		if (!args.action) {
+			console.log(`Usage: xcsh office <${OFFICE_ACTIONS.join("|")}>`);
+			console.log("  serve     Start the https://127-0-0-1.local-ip.sh:8444 task-pane listener");
+			console.log("  manifest  Print (or -o write) the add-in manifest.json");
+			console.log("  sideload  Sideload the add-in into a desktop Office app");
+			return;
+		}
+		await runOfficeCommand({
+			action: args.action as OfficeAction,
+			app: args.app as OfficeApp | undefined,
+			out: flags.out,
+		});
+	}
+}

package/src/host-tools/guards.ts

@@ -0,0 +1,30 @@
+/**
+ * Transport-neutral host-tool frame guards.
+ *
+ * Kept in a leaf module — depending ONLY on the wire types (`./types`) and
+ * pi-agent-core's `AgentToolResult` *type* — so browser-safe consumers (e.g.
+ * `../browser/chat-protocol`) can import the guards WITHOUT loading the
+ * `RpcHostToolBridge` in `./host-tools`, which pulls the theme + tool-proxy
+ * runtime graph. That graph is fine for the agent runtime but drags node-coupled
+ * modules into a browser (lib.dom) TypeScript program.
+ */
+import type { AgentToolResult } from "@f5-sales-demo/pi-agent-core/types";
+import type { RpcHostToolResult, RpcHostToolUpdate } from "./types";
+
+function isAgentToolResult(value: unknown): value is AgentToolResult<unknown> {
+	if (!value || typeof value !== "object") return false;
+	const content = (value as { content?: unknown }).content;
+	return Array.isArray(content);
+}
+
+export function isRpcHostToolResult(value: unknown): value is RpcHostToolResult {
+	if (!value || typeof value !== "object") return false;
+	const frame = value as { type?: unknown; id?: unknown; result?: unknown };
+	return frame.type === "host_tool_result" && typeof frame.id === "string" && isAgentToolResult(frame.result);
+}
+
+export function isRpcHostToolUpdate(value: unknown): value is RpcHostToolUpdate {
+	if (!value || typeof value !== "object") return false;
+	const frame = value as { type?: unknown; id?: unknown; partialResult?: unknown };
+	return frame.type === "host_tool_update" && typeof frame.id === "string" && isAgentToolResult(frame.partialResult);
+}

package/src/host-tools/host-tools.ts

@@ -19,24 +19,6 @@ type PendingHostToolCall = {
 	onUpdate?: AgentToolUpdateCallback<unknown>;
 };
 
-function isAgentToolResult(value: unknown): value is AgentToolResult<unknown> {
-	if (!value || typeof value !== "object") return false;
-	const content = (value as { content?: unknown }).content;
-	return Array.isArray(content);
-}
-
-export function isRpcHostToolResult(value: unknown): value is RpcHostToolResult {
-	if (!value || typeof value !== "object") return false;
-	const frame = value as { type?: unknown; id?: unknown; result?: unknown };
-	return frame.type === "host_tool_result" && typeof frame.id === "string" && isAgentToolResult(frame.result);
-}
-
-export function isRpcHostToolUpdate(value: unknown): value is RpcHostToolUpdate {
-	if (!value || typeof value !== "object") return false;
-	const frame = value as { type?: unknown; id?: unknown; partialResult?: unknown };
-	return frame.type === "host_tool_update" && typeof frame.id === "string" && isAgentToolResult(frame.partialResult);
-}
-
 /**
  * Validate + normalize incoming host-tool definitions (trim names/labels/descriptions,
  * enforce non-empty name/description and a JSON-Schema `parameters` object). Shared by

package/src/host-tools/index.ts

@@ -7,12 +7,8 @@
  * transport specifics — a driver supplies only an `output: (frame) => void`
  * sink — so every transport reuses them verbatim.
  */
-export {
-	isRpcHostToolResult,
-	isRpcHostToolUpdate,
-	normalizeHostToolDefinitions,
-	RpcHostToolBridge,
-} from "./host-tools";
+export { isRpcHostToolResult, isRpcHostToolUpdate } from "./guards";
+export { normalizeHostToolDefinitions, RpcHostToolBridge } from "./host-tools";
 export type {
 	RpcHostToolCallRequest,
 	RpcHostToolCancelRequest,

package/src/host-tools/types.ts

@@ -6,7 +6,10 @@
  * back. They are shared verbatim across transports (stdio RPC and the WS chat
  * bridge), so they live outside of any single transport driver.
  */
-import type { AgentToolResult } from "@f5-sales-demo/pi-agent-core";
+// Narrow subpath (not the barrel) so browser-safe consumers of these wire types
+// don't transitively pull pi-agent-core's runtime graph (agent → pi-utils), which
+// is not lib.dom-safe. AgentToolResult is a pure type.
+import type { AgentToolResult } from "@f5-sales-demo/pi-agent-core/types";
 
 export interface RpcHostToolDefinition {
 	name: string;

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.64.3",
-	"commit": "3aaab225af4829e6b49252402e164c07bdb3861c",
-	"shortCommit": "3aaab22",
+	"version": "19.66.0",
+	"commit": "a2db5b22aa941b407f9072d154137c57ea932858",
+	"shortCommit": "a2db5b2",
 	"branch": "main",
-	"tag": "v19.64.3",
-	"commitDate": "2026-07-20T16:07:14Z",
-	"buildDate": "2026-07-20T16:33:54.078Z",
+	"tag": "v19.66.0",
+	"commitDate": "2026-07-20T19:28:22Z",
+	"buildDate": "2026-07-20T19:57:53.798Z",
 	"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/3aaab225af4829e6b49252402e164c07bdb3861c",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.64.3"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/a2db5b22aa941b407f9072d154137c57ea932858",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.66.0"
 };