@f5-sales-demo/xcsh 19.64.2 → 19.65.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.64.2",
+	"version": "19.65.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.64.2",
-		"@f5-sales-demo/pi-agent-core": "19.64.2",
-		"@f5-sales-demo/pi-ai": "19.64.2",
-		"@f5-sales-demo/pi-natives": "19.64.2",
-		"@f5-sales-demo/pi-resource-management": "19.64.2",
-		"@f5-sales-demo/pi-tui": "19.64.2",
-		"@f5-sales-demo/pi-utils": "19.64.2",
+		"@f5-sales-demo/xcsh-stats": "19.65.0",
+		"@f5-sales-demo/pi-agent-core": "19.65.0",
+		"@f5-sales-demo/pi-ai": "19.65.0",
+		"@f5-sales-demo/pi-natives": "19.65.0",
+		"@f5-sales-demo/pi-resource-management": "19.65.0",
+		"@f5-sales-demo/pi-tui": "19.65.0",
+		"@f5-sales-demo/pi-utils": "19.65.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/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.2",
-	"commit": "2f997ccc03d56bf0345a7cb56fefb94414ff3d8b",
-	"shortCommit": "2f997cc",
+	"version": "19.65.0",
+	"commit": "342e21815d71783c1c2b1ffe233bc0078fbcc44a",
+	"shortCommit": "342e218",
 	"branch": "main",
-	"tag": "v19.64.2",
-	"commitDate": "2026-07-20T14:05:44Z",
-	"buildDate": "2026-07-20T14:31:59.136Z",
+	"tag": "v19.65.0",
+	"commitDate": "2026-07-20T18:44:32Z",
+	"buildDate": "2026-07-20T19:07:31.313Z",
 	"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/2f997ccc03d56bf0345a7cb56fefb94414ff3d8b",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.64.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/342e21815d71783c1c2b1ffe233bc0078fbcc44a",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.65.0"
 };