@f5-sales-demo/xcsh 19.61.5 → 19.62.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.61.5",
+	"version": "19.62.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.61.5",
-		"@f5-sales-demo/pi-agent-core": "19.61.5",
-		"@f5-sales-demo/pi-ai": "19.61.5",
-		"@f5-sales-demo/pi-natives": "19.61.5",
-		"@f5-sales-demo/pi-resource-management": "19.61.5",
-		"@f5-sales-demo/pi-tui": "19.61.5",
-		"@f5-sales-demo/pi-utils": "19.61.5",
+		"@f5-sales-demo/xcsh-stats": "19.62.0",
+		"@f5-sales-demo/pi-agent-core": "19.62.0",
+		"@f5-sales-demo/pi-ai": "19.62.0",
+		"@f5-sales-demo/pi-natives": "19.62.0",
+		"@f5-sales-demo/pi-resource-management": "19.62.0",
+		"@f5-sales-demo/pi-tui": "19.62.0",
+		"@f5-sales-demo/pi-utils": "19.62.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.5.0",
+	"contractVersion": "1.6.0",
 	"multiPortDiscovery": true,
 	"protocol": "tool_request/result",
 	"tools": [
@@ -625,6 +625,26 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 			},
 			"flags": {}
 		},
+		{
+			"name": "diag_activation",
+			"summary": "Diagnostic: per-gate tab-activation readiness timings (bridge/worker/page), cold/warm.",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {}
+		},
+		{
+			"name": "diag_ttft",
+			"summary": "Diagnostic: init→first-token timeline (per-stage ms, total, dominant, cold/warm).",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {}
+		},
 		{
 			"name": "capture_login_flow",
 			"summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",
@@ -825,6 +845,6 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.5.0";
+export const EXTENSION_CONTRACT_VERSION = "1.6.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","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];
+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.5.0",
+  "contractVersion": "1.6.0",
   "multiPortDiscovery": true,
   "protocol": "tool_request/result",
   "tools": [
@@ -550,6 +550,26 @@
       },
       "flags": {}
     },
+    {
+      "name": "diag_activation",
+      "summary": "Diagnostic: per-gate tab-activation readiness timings (bridge/worker/page), cold/warm.",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {}
+    },
+    {
+      "name": "diag_ttft",
+      "summary": "Diagnostic: init→first-token timeline (per-stage ms, total, dominant, cold/warm).",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {}
+    },
     {
       "name": "capture_login_flow",
       "summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",

package/src/browser/chat-conformance.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.5.0",
+  "contractVersion": "1.6.0",
   "schemas": {
     "chat_request": {
       "type": "object",
@@ -210,6 +210,19 @@
         },
         "error": {
           "type": "string"
+        },
+        "reason": {
+          "anyOf": [
+            { "const": "bridge-disconnected", "type": "string" },
+            { "const": "bridge-unresponsive", "type": "string" },
+            { "const": "no-worker", "type": "string" },
+            { "const": "session-busy", "type": "string" },
+            { "const": "session-disposed", "type": "string" },
+            { "const": "token-expired", "type": "string" },
+            { "const": "token-expiring", "type": "string" },
+            { "const": "provider-4xx", "type": "string" },
+            { "const": "provider-5xx", "type": "string" }
+          ]
         }
       }
     },
@@ -433,7 +446,8 @@
       "chat_error": {
         "type": "chat_error",
         "id": "c-1111",
-        "error": "HTTP 403 forbidden"
+        "error": "HTTP 403 forbidden",
+        "reason": "provider-4xx"
       },
       "chat_tool_notice": {
         "type": "chat_tool_notice",

package/src/browser/chat-handler.ts

@@ -4,6 +4,7 @@ import {
 	type ChatDelta,
 	type ChatDone,
 	type ChatError,
+	type ChatErrorReason,
 	type ChatReference,
 	type ChatRequest,
 	type InteractionMode,
@@ -52,7 +53,12 @@ export class ChatHandler {
 
 		this.#server.onDisconnected(() => {
 			for (const chat of this.#activeChats.values()) {
-				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "bridge disconnected" });
+				this.#sendTerminal(chat, {
+					type: "chat_error",
+					id: chat.id,
+					error: "bridge disconnected",
+					reason: "bridge-disconnected",
+				});
 				chat.unsubscribe();
 			}
 			this.#activeChats.clear();
@@ -63,7 +69,12 @@ export class ChatHandler {
 		const { id } = req;
 
 		if (this.#session.isStreaming || this.#activeChats.size > 0) {
-			this.#server.send({ type: "chat_error", id, error: "session busy" } satisfies ChatError);
+			this.#server.send({
+				type: "chat_error",
+				id,
+				error: "session busy",
+				reason: "session-busy",
+			} satisfies ChatError);
 			return;
 		}
 
@@ -96,7 +107,7 @@ export class ChatHandler {
 			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 });
+			this.#sendTerminal(chat, { type: "chat_error", id, error: message, reason: classifyChatErrorReason(message) });
 		} finally {
 			if (!chat.terminalSent) {
 				this.#sendTerminal(chat, { type: "chat_done", id });
@@ -153,15 +164,22 @@ export class ChatHandler {
 				}
 			} else if (ame.type === "error") {
 				const errorMsg = ame.error?.errorMessage ?? "LLM error";
-				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: errorMsg });
+				this.#sendTerminal(chat, {
+					type: "chat_error",
+					id: chat.id,
+					error: errorMsg,
+					reason: classifyChatErrorReason(errorMsg),
+				});
 			}
 		} else if (event.type === "message_end" && event.message.role === "assistant") {
 			const msg = event.message as AssistantMessage;
 			if (msg.stopReason === "error") {
+				const errorMsg = msg.errorMessage ?? "assistant error";
 				this.#sendTerminal(chat, {
 					type: "chat_error",
 					id: chat.id,
-					error: msg.errorMessage ?? "assistant error",
+					error: errorMsg,
+					reason: classifyChatErrorReason(errorMsg),
 				});
 			} else {
 				const references = extractReferences(msg);
@@ -194,13 +212,41 @@ export class ChatHandler {
 
 	dispose(): void {
 		for (const chat of this.#activeChats.values()) {
-			this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "session disposed" });
+			this.#sendTerminal(chat, {
+				type: "chat_error",
+				id: chat.id,
+				error: "session disposed",
+				reason: "session-disposed",
+			});
 			chat.unsubscribe();
 		}
 		this.#activeChats.clear();
 	}
 }
 
+/** 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).
+ * Token checks run before the generic 4xx check (a 401 is more useful as an
+ * expired-token hint than a bare client error). */
+export function classifyChatErrorReason(message: string): ChatErrorReason | undefined {
+	const m = message.toLowerCase();
+	if (/\btoken\b[^.]*\b(expir|invalid)|\b(expir|invalid)[^.]*\btoken\b|aws sso|\/context (create|validate)/.test(m)) {
+		return "token-expired";
+	}
+	if (
+		/\b5\d\d\b|internal server error|bad gateway|service unavailable|gateway timeout|econnreset|etimedout|socket hang up|network error/.test(
+			m,
+		)
+	) {
+		return "provider-5xx";
+	}
+	if (/\b4\d\d\b|forbidden|unauthorized|invalid model|bad request|not found|too many requests|rate limit/.test(m)) {
+		return "provider-4xx";
+	}
+	return undefined;
+}
+
 /**
  * Chrome-extension self-awareness prompt. Injected when xcsh is serving a browser
  * chat (not the CLI TUI). Tells the LLM it's in a Chrome side panel alongside the

package/src/browser/chat-protocol.ts

@@ -80,10 +80,30 @@ export interface ChatDone {
 	references?: ChatReference[];
 }
 
+/** Machine-readable cause of a terminal chat_error, so the panel can render a
+ * distinct, actionable message (and decide whether to auto-recover) instead of a
+ * generic failure. Additive/optional on the wire (contract 1.6.0); an omitted
+ * reason means an unclassified error (legacy behavior — show the error text).
+ * Shared vocabulary with the extension (keep both lists identical). */
+export const CHAT_ERROR_REASONS = [
+	"bridge-disconnected", // the worker's bridge closed mid-turn
+	"bridge-unresponsive", // the socket looked open but the worker never answered
+	"no-worker", // no worker is running for this tab
+	"session-busy", // a turn is already in flight for this session
+	"session-disposed", // the worker session was torn down
+	"token-expired", // F5 XC API token expired
+	"token-expiring", // F5 XC API token is about to expire
+	"provider-4xx", // upstream provider rejected the request (client error)
+	"provider-5xx", // upstream provider failed (server error) — retryable
+] as const;
+
+export type ChatErrorReason = (typeof CHAT_ERROR_REASONS)[number];
+
 export interface ChatError {
 	type: "chat_error";
 	id: string;
 	error: string;
+	reason?: ChatErrorReason;
 }
 
 // ---------------------------------------------------------------------------

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.61.5",
-	"commit": "e9f45bc1c87e84c1d99060a016ae1e20907e2210",
-	"shortCommit": "e9f45bc",
+	"version": "19.62.0",
+	"commit": "002bc2b7d7e14a95e282f940730cbdc347197635",
+	"shortCommit": "002bc2b",
 	"branch": "main",
-	"tag": "v19.61.5",
-	"commitDate": "2026-07-08T01:47:55Z",
-	"buildDate": "2026-07-08T02:09:52.692Z",
+	"tag": "v19.62.0",
+	"commitDate": "2026-07-08T02:22:10Z",
+	"buildDate": "2026-07-08T02:45:44.169Z",
 	"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/e9f45bc1c87e84c1d99060a016ae1e20907e2210",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.5"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/002bc2b7d7e14a95e282f940730cbdc347197635",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.62.0"
 };