@f5-sales-demo/xcsh 19.52.0 → 19.53.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.52.0",
+	"version": "19.53.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",
@@ -55,13 +55,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.52.0",
-		"@f5-sales-demo/pi-agent-core": "19.52.0",
-		"@f5-sales-demo/pi-ai": "19.52.0",
-		"@f5-sales-demo/pi-natives": "19.52.0",
-		"@f5-sales-demo/pi-resource-management": "19.52.0",
-		"@f5-sales-demo/pi-tui": "19.52.0",
-		"@f5-sales-demo/pi-utils": "19.52.0",
+		"@f5-sales-demo/xcsh-stats": "19.53.0",
+		"@f5-sales-demo/pi-agent-core": "19.53.0",
+		"@f5-sales-demo/pi-ai": "19.53.0",
+		"@f5-sales-demo/pi-natives": "19.53.0",
+		"@f5-sales-demo/pi-resource-management": "19.53.0",
+		"@f5-sales-demo/pi-tui": "19.53.0",
+		"@f5-sales-demo/pi-utils": "19.53.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/capabilities.generated.ts

@@ -25,7 +25,7 @@ export interface ExtensionCapabilities {
 
 export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	"version": "0.1.0",
-	"contractVersion": "1.0.0",
+	"contractVersion": "1.2.0",
 	"protocol": "tool_request/result",
 	"tools": [
 		{
@@ -584,6 +584,18 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 				"readOnly": true
 			}
 		},
+		{
+			"name": "get_page_context",
+			"summary": "Return a snapshot of the active console page (url, AX tree, captured XC API body) for chat grounding.",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {
+				"readOnly": true
+			}
+		},
 		{
 			"name": "javascript_tool",
 			"summary": "Evaluate arbitrary JS in the page (length-capped).",
@@ -706,10 +718,30 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 		"viewport": {
 			"tool": "resize_window",
 			"description": "Control the browser window size."
+		},
+		"chat": {
+			"contextTool": "get_page_context",
+			"transport": "websocket-bridge",
+			"modes": [
+				"educational",
+				"presentation",
+				"configuration",
+				"screenshot",
+				"annotation"
+			],
+			"messages": [
+				"chat_request",
+				"chat_delta",
+				"chat_done",
+				"chat_error",
+				"chat_stop",
+				"chat_tool_notice"
+			],
+			"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."
 		}
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.0.0";
+export const EXTENSION_CONTRACT_VERSION = "1.2.0";
 
-export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","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","find","wait_for","assert_text","screenshot","read_console","read_network","wait_for_api_response","javascript_tool","browser_batch","set_explain_mode","annotate"];
+export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","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","find","wait_for","assert_text","screenshot","read_console","read_network","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.0.0",
+  "contractVersion": "1.2.0",
   "protocol": "tool_request/result",
   "tools": [
     {
@@ -69,9 +69,7 @@
       "category": "navigation",
       "params": {
         "type": "object",
-        "required": [
-          "url"
-        ],
+        "required": ["url"],
         "properties": {
           "url": {
             "type": "string"
@@ -88,11 +86,7 @@
       "category": "navigation",
       "params": {
         "type": "object",
-        "required": [
-          "email",
-          "password",
-          "consoleUrl"
-        ],
+        "required": ["email", "password", "consoleUrl"],
         "properties": {
           "email": {
             "type": "string"
@@ -115,9 +109,7 @@
       "category": "navigation",
       "params": {
         "type": "object",
-        "required": [
-          "ref"
-        ],
+        "required": ["ref"],
         "properties": {
           "ref": {
             "type": "string"
@@ -134,10 +126,7 @@
       "category": "navigation",
       "params": {
         "type": "object",
-        "required": [
-          "width",
-          "height"
-        ],
+        "required": ["width", "height"],
         "properties": {
           "width": {
             "type": "number"
@@ -167,9 +156,7 @@
       "category": "navigation",
       "params": {
         "type": "object",
-        "required": [
-          "url"
-        ],
+        "required": ["url"],
         "properties": {
           "url": {
             "type": "string"
@@ -186,9 +173,7 @@
       "category": "navigation",
       "params": {
         "type": "object",
-        "required": [
-          "tabId"
-        ],
+        "required": ["tabId"],
         "properties": {
           "tabId": {
             "type": "number"
@@ -205,9 +190,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "ref"
-        ],
+        "required": ["ref"],
         "properties": {
           "ref": {
             "type": "string"
@@ -224,9 +207,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "js"
-        ],
+        "required": ["js"],
         "properties": {
           "js": {
             "type": "string"
@@ -246,10 +227,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "x",
-          "y"
-        ],
+        "required": ["x", "y"],
         "properties": {
           "x": {
             "type": "number"
@@ -269,9 +247,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "text"
-        ],
+        "required": ["text"],
         "properties": {
           "text": {
             "type": "string"
@@ -288,10 +264,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "ref",
-          "value"
-        ],
+        "required": ["ref", "value"],
         "properties": {
           "ref": {
             "type": "string"
@@ -311,9 +284,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "key"
-        ],
+        "required": ["key"],
         "properties": {
           "key": {
             "type": "string"
@@ -330,10 +301,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "ref",
-          "value"
-        ],
+        "required": ["ref", "value"],
         "properties": {
           "ref": {
             "type": "string"
@@ -353,10 +321,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "selector",
-          "value"
-        ],
+        "required": ["selector", "value"],
         "properties": {
           "selector": {
             "type": "string"
@@ -382,10 +347,7 @@
       "category": "interaction",
       "params": {
         "type": "object",
-        "required": [
-          "ref",
-          "files"
-        ],
+        "required": ["ref", "files"],
         "properties": {
           "ref": {
             "type": "string"
@@ -432,9 +394,7 @@
       "category": "read",
       "params": {
         "type": "object",
-        "required": [
-          "selector"
-        ],
+        "required": ["selector"],
         "properties": {
           "selector": {
             "type": "string"
@@ -451,9 +411,7 @@
       "category": "read",
       "params": {
         "type": "object",
-        "required": [
-          "selector"
-        ],
+        "required": ["selector"],
         "properties": {
           "selector": {
             "type": "string"
@@ -476,10 +434,7 @@
       "category": "read",
       "params": {
         "type": "object",
-        "required": [
-          "selector",
-          "expected"
-        ],
+        "required": ["selector", "expected"],
         "properties": {
           "selector": {
             "type": "string"
@@ -559,15 +514,25 @@
         "readOnly": true
       }
     },
+    {
+      "name": "get_page_context",
+      "summary": "Return a snapshot of the active console page (url, AX tree, captured XC API body) for chat grounding.",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {
+        "readOnly": true
+      }
+    },
     {
       "name": "javascript_tool",
       "summary": "Evaluate arbitrary JS in the page (length-capped).",
       "category": "script",
       "params": {
         "type": "object",
-        "required": [
-          "code"
-        ],
+        "required": ["code"],
         "properties": {
           "code": {
             "type": "string"
@@ -584,17 +549,13 @@
       "category": "script",
       "params": {
         "type": "object",
-        "required": [
-          "actions"
-        ],
+        "required": ["actions"],
         "properties": {
           "actions": {
             "type": "array",
             "items": {
               "type": "object",
-              "required": [
-                "tool"
-              ],
+              "required": ["tool"],
               "properties": {
                 "tool": {
                   "type": "string"
@@ -629,9 +590,7 @@
       "category": "annotation",
       "params": {
         "type": "object",
-        "required": [
-          "kind"
-        ],
+        "required": ["kind"],
         "properties": {
           "kind": {
             "type": "string"
@@ -668,10 +627,7 @@
       "tool": "annotate",
       "requiresExplainMode": true,
       "autoFingerprintOnClick": true,
-      "kinds": [
-        "fingerprint",
-        "highlight"
-      ],
+      "kinds": ["fingerprint", "highlight"],
       "description": "Transient annotation overlays. In explain mode, clicks auto-draw a fingerprint; `annotate` draws a named overlay by ref or coordinates."
     },
     "capture": {
@@ -681,6 +637,13 @@
     "viewport": {
       "tool": "resize_window",
       "description": "Control the browser window size."
+    },
+    "chat": {
+      "contextTool": "get_page_context",
+      "transport": "websocket-bridge",
+      "modes": ["educational", "presentation", "configuration", "screenshot", "annotation"],
+      "messages": ["chat_request", "chat_delta", "chat_done", "chat_error", "chat_stop", "chat_tool_notice"],
+      "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."
     }
   }
 }

package/src/browser/chat-handler.ts

@@ -0,0 +1,196 @@
+import type { AssistantMessage } from "@f5-sales-demo/pi-ai";
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import {
+	type ChatDelta,
+	type ChatDone,
+	type ChatError,
+	type ChatReference,
+	type ChatRequest,
+	type InteractionMode,
+	isChatRequest,
+	isChatStop,
+	type PageContextSnapshot,
+} from "./chat-protocol";
+import type { BridgeServer } from "./extension-bridge";
+
+interface ActiveChat {
+	id: string;
+	seq: number;
+	terminalSent: boolean;
+	unsubscribe: () => void;
+}
+
+export class ChatHandler {
+	#server: BridgeServer;
+	#session: AgentSession;
+	#activeChats = new Map<string, ActiveChat>();
+
+	constructor(server: BridgeServer, session: AgentSession) {
+		this.#server = server;
+		this.#session = session;
+	}
+
+	attach(): void {
+		this.#server.onMessage(msg => {
+			if (isChatRequest(msg)) this.#handleChatRequest(msg as unknown as ChatRequest);
+			else if (isChatStop(msg)) this.#handleChatStop(msg as unknown as { id: string });
+		});
+
+		this.#server.onDisconnected(() => {
+			for (const chat of this.#activeChats.values()) {
+				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "bridge disconnected" });
+				chat.unsubscribe();
+			}
+			this.#activeChats.clear();
+		});
+	}
+
+	async #handleChatRequest(req: ChatRequest): Promise<void> {
+		const { id } = req;
+
+		if (this.#session.isStreaming || this.#activeChats.size > 0) {
+			this.#server.send({ type: "chat_error", id, error: "session busy" } satisfies ChatError);
+			return;
+		}
+
+		const chat: ActiveChat = { id, seq: 0, terminalSent: false, unsubscribe: () => {} };
+		this.#activeChats.set(id, chat);
+
+		const unsubscribe = this.#session.subscribe((event: AgentSessionEvent) => {
+			this.#handleSessionEvent(chat, event);
+		});
+		chat.unsubscribe = unsubscribe;
+
+		const prompt = composeChatPrompt(req.text, req.context, req.mode);
+
+		try {
+			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false });
+		} catch (err: unknown) {
+			const message = err instanceof Error ? err.message : "unknown error";
+			this.#sendTerminal(chat, { type: "chat_error", id, error: message });
+		} finally {
+			if (!chat.terminalSent) {
+				this.#sendTerminal(chat, { type: "chat_done", id });
+			}
+			chat.unsubscribe();
+			this.#activeChats.delete(id);
+		}
+	}
+
+	#handleSessionEvent(chat: ActiveChat, event: AgentSessionEvent): void {
+		if (chat.terminalSent) return;
+
+		if (event.type === "message_update" && "assistantMessageEvent" in event) {
+			const ame = event.assistantMessageEvent;
+			if (ame.type === "text_delta") {
+				this.#server.send({
+					type: "chat_delta",
+					id: chat.id,
+					seq: chat.seq++,
+					delta: ame.delta,
+				} satisfies ChatDelta);
+			} else if (ame.type === "error") {
+				const errorMsg = ame.error?.errorMessage ?? "LLM error";
+				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: errorMsg });
+			}
+		} else if (event.type === "message_end" && event.message.role === "assistant") {
+			const msg = event.message as AssistantMessage;
+			if (msg.stopReason === "error") {
+				this.#sendTerminal(chat, {
+					type: "chat_error",
+					id: chat.id,
+					error: msg.errorMessage ?? "assistant error",
+				});
+			} else {
+				const references = extractReferences(msg);
+				this.#sendTerminal(chat, {
+					type: "chat_done",
+					id: chat.id,
+					...(references.length > 0 ? { references } : {}),
+				});
+			}
+		}
+	}
+
+	#handleChatStop(stop: { id: string }): void {
+		const chat = this.#activeChats.get(stop.id);
+		if (!chat) return;
+		this.#session.agent.abort();
+	}
+
+	#sendTerminal(chat: ActiveChat, frame: ChatDone | ChatError): void {
+		if (chat.terminalSent) return;
+		chat.terminalSent = true;
+		this.#server.send(frame);
+	}
+
+	dispose(): void {
+		for (const chat of this.#activeChats.values()) {
+			this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "session disposed" });
+			chat.unsubscribe();
+		}
+		this.#activeChats.clear();
+	}
+}
+
+const MODE_INSTRUCTIONS: Record<InteractionMode, string> = {
+	educational: "Explain concepts and settings in depth. Help the user understand what they're looking at and why.",
+	presentation: "Guide a structured walkthrough. Narrate each step clearly for a live audience.",
+	configuration: "Help the user build or modify F5 XC configuration. Be precise and action-oriented.",
+	screenshot: "Focus on capturing annotated screenshots that document the current state.",
+	annotation: "Create on-page teaching annotations that highlight key elements and explain their purpose.",
+};
+
+export function composeChatPrompt(text: string, context: PageContextSnapshot | null, mode: InteractionMode): string {
+	const parts: string[] = [];
+
+	parts.push(`[Chat mode: ${mode}] ${MODE_INSTRUCTIONS[mode]}`);
+
+	if (context) {
+		parts.push("");
+		parts.push(`[Page context — captured at ${new Date(context.capturedAt).toISOString()}]`);
+		parts.push(`URL: ${context.url}`);
+		parts.push(`Title: ${context.title}`);
+
+		if (context.api) {
+			parts.push(`API resource (${context.api.resourceType}, status ${context.api.status}): ${context.api.url}`);
+			if (context.api.body) {
+				const body =
+					typeof context.api.body === "string" ? context.api.body : JSON.stringify(context.api.body, null, 2);
+				parts.push(body);
+			}
+			if (context.api.truncated) {
+				parts.push("[API body was truncated]");
+			}
+		}
+
+		if (context.ax) {
+			const ax = typeof context.ax === "string" ? context.ax : JSON.stringify(context.ax);
+			parts.push(`Accessibility tree: ${ax}`);
+		}
+
+		if (context.truncated) {
+			parts.push("[Page context was truncated]");
+		}
+
+		parts.push("---");
+	}
+
+	parts.push("");
+	parts.push(text);
+	return parts.join("\n");
+}
+
+function extractReferences(msg: AssistantMessage): ChatReference[] {
+	const refs: ChatReference[] = [];
+	for (const block of msg.content) {
+		if (block.type !== "text") continue;
+		const urlRegex = /\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g;
+		for (let match = urlRegex.exec(block.text); match !== null; match = urlRegex.exec(block.text)) {
+			const [, title, url] = match;
+			const kind = url.includes("docs.cloud.f5.com") || url.includes("docs.") ? "doc" : "console";
+			refs.push({ kind, title, url });
+		}
+	}
+	return refs;
+}

package/src/browser/chat-protocol.ts

@@ -0,0 +1,109 @@
+/**
+ * Wire protocol types for the Chrome extension chat side window.
+ * Contract source of truth: capabilities.json v1.2.0.
+ */
+
+// ---------------------------------------------------------------------------
+// Page context snapshot (auto-attached by extension to every chat_request)
+// ---------------------------------------------------------------------------
+
+export interface PageContextApi {
+	url: string;
+	status: number;
+	resourceType: string;
+	body: unknown;
+	truncated: boolean;
+}
+
+export interface PageContextSnapshot {
+	v: 1;
+	capturedAt: number;
+	tabId: number;
+	url: string;
+	path: string;
+	title: string;
+	ax: unknown | null;
+	api: PageContextApi | null;
+	truncated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Interaction modes
+// ---------------------------------------------------------------------------
+
+export type InteractionMode = "educational" | "presentation" | "configuration" | "screenshot" | "annotation";
+
+const VALID_MODES = new Set<string>(["educational", "presentation", "configuration", "screenshot", "annotation"]);
+
+// ---------------------------------------------------------------------------
+// References (attached to chat_done)
+// ---------------------------------------------------------------------------
+
+export interface ChatReference {
+	kind: "doc" | "console";
+	title: string;
+	url: string;
+}
+
+// ---------------------------------------------------------------------------
+// Inbound messages (extension → xcsh)
+// ---------------------------------------------------------------------------
+
+export interface ChatRequest {
+	type: "chat_request";
+	id: string;
+	text: string;
+	context: PageContextSnapshot | null;
+	mode: InteractionMode;
+	history_hint: string;
+}
+
+export interface ChatStop {
+	type: "chat_stop";
+	id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Outbound messages (xcsh → extension)
+// ---------------------------------------------------------------------------
+
+export interface ChatDelta {
+	type: "chat_delta";
+	id: string;
+	seq: number;
+	delta: string;
+}
+
+export interface ChatDone {
+	type: "chat_done";
+	id: string;
+	references?: ChatReference[];
+}
+
+export interface ChatError {
+	type: "chat_error";
+	id: string;
+	error: string;
+}
+
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+
+function hasChatIdPrefix(id: unknown): id is string {
+	return typeof id === "string" && id.startsWith("c-");
+}
+
+export function isChatRequest(msg: Record<string, unknown>): boolean {
+	return (
+		msg.type === "chat_request" &&
+		hasChatIdPrefix(msg.id) &&
+		typeof msg.text === "string" &&
+		typeof msg.mode === "string" &&
+		VALID_MODES.has(msg.mode)
+	);
+}
+
+export function isChatStop(msg: Record<string, unknown>): boolean {
+	return msg.type === "chat_stop" && hasChatIdPrefix(msg.id);
+}

package/src/browser/extension-bridge.ts

@@ -80,6 +80,7 @@ export class BridgeServer {
 	#client: ServerWebSocket<undefined> | null = null;
 	#onConnected: Array<() => void> = [];
 	#onDisconnected: Array<() => void> = [];
+	#onMessage: Array<(msg: Record<string, unknown>) => void> = [];
 
 	/** The port the WebSocket server is listening on (0 = not bound). */
 	get port(): number {
@@ -98,6 +99,16 @@ export class BridgeServer {
 		this.#onDisconnected.push(cb);
 	}
 
+	/** Register a listener for messages not handled by the built-in router (tool_result, ping). */
+	onMessage(cb: (msg: Record<string, unknown>) => void): void {
+		this.#onMessage.push(cb);
+	}
+
+	/** Send a fire-and-forget JSON frame to the connected client. */
+	send(payload: unknown): void {
+		this.#client?.send(JSON.stringify(payload));
+	}
+
 	/** Bind the WebSocket server to a loopback port. Called by {@link startBridgeServer}. */
 	listen(port: number, opts?: { skipOriginCheck?: boolean }): void {
 		this.#server = Bun.serve({
@@ -149,6 +160,8 @@ export class BridgeServer {
 			});
 		} else if (msg.type === "ping") {
 			ws.send(JSON.stringify({ type: "pong" }));
+		} else {
+			for (const cb of this.#onMessage) cb(msg as Record<string, unknown>);
 		}
 	}
 

package/src/browser/extension-provider.ts

@@ -1,5 +1,6 @@
 import { type AxNode, matchNode } from "./ax";
 import { EXTENSION_CONTRACT_VERSION } from "./capabilities.generated";
+import type { PageContextSnapshot } from "./chat-protocol";
 import { type BridgeServer, startBridgeServer, type ToolResult } from "./extension-bridge";
 import { checkContractVersion } from "./extension-contract";
 import { ExtensionPageActions } from "./extension-page-actions";
@@ -75,6 +76,8 @@ export interface ExtensionPage {
 		value: string;
 		optionCount: number;
 	}>;
+	/** Read the current page-context snapshot (URL, title, AX tree, live API body). */
+	getPageContext(): Promise<PageContextSnapshot>;
 	/** Toggle the extension's "explain mode" — the gate for on-page annotation
 	 * overlays (fingerprints/highlights), used during human-paced walkthroughs. */
 	setExplainMode(enabled: boolean): Promise<void>;
@@ -165,6 +168,10 @@ class BridgeExtensionPage implements ExtensionPage {
 		return unwrap(await this.#server.request("screenshot", {}), "screenshot") as string;
 	}
 
+	async getPageContext(): Promise<PageContextSnapshot> {
+		return unwrap(await this.#server.request("get_page_context", {}), "get_page_context") as PageContextSnapshot;
+	}
+
 	async setExplainMode(enabled: boolean): Promise<void> {
 		unwrap(await this.#server.request("set_explain_mode", { enabled }), "set_explain_mode");
 	}

package/src/browser/index.ts

@@ -4,6 +4,8 @@ export * from "./auth";
 export * from "./ax";
 export * from "./cdp-core";
 export * from "./cdp-page-actions";
+export * from "./chat-handler";
+export * from "./chat-protocol";
 export * from "./chrome-locate";
 export * from "./dom-context";
 export * from "./extension-bridge";

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.52.0",
-	"commit": "a54c0128815fd00752c40aba2a1650817ca9874f",
-	"shortCommit": "a54c012",
+	"version": "19.53.0",
+	"commit": "bd260c74c8205835f4934fc2251fc66d5ef95335",
+	"shortCommit": "bd260c7",
 	"branch": "main",
-	"tag": "v19.52.0",
-	"commitDate": "2026-06-29T19:21:11Z",
-	"buildDate": "2026-06-29T19:48:42.397Z",
+	"tag": "v19.53.0",
+	"commitDate": "2026-06-30T11:39:51Z",
+	"buildDate": "2026-06-30T12:06:01.035Z",
 	"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/a54c0128815fd00752c40aba2a1650817ca9874f",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.52.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/bd260c74c8205835f4934fc2251fc66d5ef95335",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.53.0"
 };

package/src/main.ts

@@ -21,6 +21,8 @@ import {
 	VERSION,
 } from "@f5-sales-demo/pi-utils";
 import chalk from "chalk";
+import { ChatHandler } from "./browser/chat-handler";
+import { startBridgeServer } from "./browser/extension-bridge";
 import { invalidate as invalidateFsCache } from "./capability/fs";
 import type { Args } from "./cli/args";
 import { processFileArguments } from "./cli/file-processor";
@@ -883,6 +885,18 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 		return nextSession;
 	};
 
+	// Start the extension bridge chat handler when the extension provider is active.
+	// The bridge server starts eagerly so chat_request messages are accepted immediately.
+	if (process.env.XCSH_BROWSER_PROVIDER?.toLowerCase() === "extension") {
+		const bridgeServer = await startBridgeServer();
+		const chatHandler = new ChatHandler(bridgeServer, session);
+		chatHandler.attach();
+		session.addDisposeHook(() => {
+			chatHandler.dispose();
+			return bridgeServer.close();
+		});
+	}
+
 	if (mode === "rpc") {
 		await runRpcMode(session);
 	} else if (mode === "acp") {

package/src/tools/get-page-context.ts

@@ -0,0 +1,56 @@
+import type { AgentTool, AgentToolResult } from "@f5-sales-demo/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import type { PageContextSnapshot } from "../browser/chat-protocol";
+import type { ToolSession } from ".";
+import { ToolError } from "./tool-errors";
+
+const schema = Type.Object({}, { additionalProperties: false });
+
+export class GetPageContextTool implements AgentTool<typeof schema> {
+	readonly name = "get_page_context";
+	readonly label = "GetPageContext";
+	readonly description =
+		"Read the current page context snapshot from the Chrome extension (URL, title, accessibility tree, live API response). Use this to refresh page state mid-conversation if the user may have navigated.";
+	readonly parameters = schema;
+	readonly strict = true;
+
+	#session: ToolSession;
+
+	constructor(session: ToolSession) {
+		this.#session = session;
+	}
+
+	static createIf(session: ToolSession): GetPageContextTool | null {
+		if (!session.bridgeServer) return null;
+		return new GetPageContextTool(session);
+	}
+
+	async execute(_toolCallId: string, _params: Record<string, never>): Promise<AgentToolResult> {
+		const server = this.#session.bridgeServer;
+		if (!server?.connected) {
+			throw new ToolError("Chrome extension is not connected.");
+		}
+
+		const result = await server.request("get_page_context", {});
+		if (result.is_error) {
+			throw new ToolError(`Failed to get page context: ${JSON.stringify(result.content)}`);
+		}
+
+		const ctx = result.content as PageContextSnapshot;
+		const parts: string[] = [];
+		parts.push(`URL: ${ctx.url}`);
+		parts.push(`Title: ${ctx.title}`);
+		parts.push(`Path: ${ctx.path}`);
+		if (ctx.api) {
+			parts.push(`API (${ctx.api.resourceType}, ${ctx.api.status}): ${ctx.api.url}`);
+			if (ctx.api.body) {
+				parts.push(typeof ctx.api.body === "string" ? ctx.api.body : JSON.stringify(ctx.api.body, null, 2));
+			}
+		}
+		if (ctx.ax) {
+			parts.push(`AX: ${typeof ctx.ax === "string" ? ctx.ax : JSON.stringify(ctx.ax)}`);
+		}
+
+		return { content: [{ type: "text", text: parts.join("\n") }] };
+	}
+}

package/src/tools/index.ts

@@ -31,6 +31,7 @@ import { DebugTool } from "./debug";
 import { DisplayImageTool } from "./display-image";
 import { ExitPlanModeTool } from "./exit-plan-mode";
 import { FindTool } from "./find";
+import { GetPageContextTool } from "./get-page-context";
 import { GrepTool } from "./grep";
 import { InspectImageTool } from "./inspect-image";
 import { NotebookTool } from "./notebook";
@@ -198,6 +199,9 @@ export interface ToolSession {
 
 	/** Queue a hidden message to be injected at the next agent turn. */
 	queueDeferredMessage?(message: CustomMessage): void;
+
+	/** Extension bridge server (available when Chrome extension is connected). */
+	bridgeServer?: import("../browser/extension-bridge").BridgeServer;
 }
 
 type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
@@ -233,6 +237,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	write: s => new WriteTool(s),
 	xcsh_api: s => new XcshApiTool(s),
 	set_presentation_profile: s => new SetPresentationProfileTool(s),
+	get_page_context: GetPageContextTool.createIf,
 };
 
 export const HIDDEN_TOOLS: Record<string, ToolFactory> = {