@f5-sales-demo/xcsh 20.1.2 → 20.2.2

package/src/browser/chat-conformance.json

@@ -1,9 +1,9 @@
 {
-  "contractVersion": "1.12.0",
+  "contractVersion": "2.0.0",
   "schemas": {
     "chat_request": {
       "type": "object",
-      "required": ["type", "id", "text", "context", "mode"],
+      "required": ["type", "id", "text", "context", "mode", "tabId", "sessionKey"],
       "properties": {
         "type": {
           "const": "chat_request",
@@ -125,6 +125,13 @@
             }
           ]
         },
+        "tabId": {
+          "type": "number"
+        },
+        "sessionKey": {
+          "minLength": 1,
+          "type": "string"
+        },
         "history_hint": {
           "type": "string"
         }
@@ -198,7 +205,7 @@
     },
     "chat_error": {
       "type": "object",
-      "required": ["type", "id", "error"],
+      "required": ["type", "id", "reason"],
       "properties": {
         "type": {
           "const": "chat_error",
@@ -208,9 +215,6 @@
           "pattern": "^c-",
           "type": "string"
         },
-        "error": {
-          "type": "string"
-        },
         "reason": {
           "anyOf": [
             {
@@ -356,52 +360,6 @@
         }
       }
     },
-    "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"],
@@ -599,68 +557,6 @@
           "type": "boolean"
         }
       }
-    },
-    "list_skills": {
-      "type": "object",
-      "required": ["type"],
-      "properties": {
-        "type": {
-          "const": "list_skills",
-          "type": "string"
-        }
-      }
-    },
-    "skills": {
-      "type": "object",
-      "required": ["type", "skills"],
-      "properties": {
-        "type": {
-          "const": "skills",
-          "type": "string"
-        },
-        "skills": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["name", "description"],
-            "properties": {
-              "name": { "type": "string", "minLength": 1 },
-              "description": { "type": "string" }
-            }
-          }
-        }
-      }
-    },
-    "list_commands": {
-      "type": "object",
-      "required": ["type"],
-      "properties": {
-        "type": {
-          "const": "list_commands",
-          "type": "string"
-        }
-      }
-    },
-    "commands": {
-      "type": "object",
-      "required": ["type", "commands"],
-      "properties": {
-        "type": {
-          "const": "commands",
-          "type": "string"
-        },
-        "commands": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["name", "description"],
-            "properties": {
-              "name": { "type": "string", "minLength": 1 },
-              "description": { "type": "string" }
-            }
-          }
-        }
-      }
     }
   },
   "examples": {
@@ -738,6 +634,8 @@
           "truncated": false
         },
         "mode": "educational",
+        "tabId": 7,
+        "sessionKey": "example-corp|production",
         "history_hint": "conv-1"
       },
       "chat_request_no_context": {
@@ -745,7 +643,9 @@
         "id": "c-2222",
         "text": "help me build a WAF policy",
         "context": null,
-        "mode": "configuration"
+        "mode": "configuration",
+        "tabId": 7,
+        "sessionKey": "example-corp|production"
       },
       "chat_stop": {
         "type": "chat_stop",
@@ -781,7 +681,6 @@
       "chat_error": {
         "type": "chat_error",
         "id": "c-1111",
-        "error": "HTTP 403 forbidden",
         "reason": "provider-4xx"
       },
       "chat_tool_notice": {
@@ -821,24 +720,6 @@
         "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",
@@ -876,38 +757,6 @@
         "type": "host_tool_cancel",
         "id": "7295551234567891",
         "targetId": "7295551234567890"
-      },
-      "list_skills": {
-        "type": "list_skills"
-      },
-      "skills": {
-        "type": "skills",
-        "skills": [
-          {
-            "name": "meddpicc:deal-review",
-            "description": "Facilitate a structured weekly MEDDPICC deal review"
-          }
-        ]
-      },
-      "skills_empty": {
-        "type": "skills",
-        "skills": []
-      },
-      "list_commands": {
-        "type": "list_commands"
-      },
-      "commands": {
-        "type": "commands",
-        "commands": [
-          {
-            "name": "meddpicc:qualify-deal",
-            "description": "Score and qualify a deal using the MEDDPICC framework"
-          }
-        ]
-      },
-      "commands_empty": {
-        "type": "commands",
-        "commands": []
       }
     },
     "invalid": [
@@ -953,6 +802,8 @@
             "truncated": false
           },
           "mode": "educational",
+          "tabId": 7,
+          "sessionKey": "example-corp|production",
           "history_hint": "conv-1"
         }
       },
@@ -998,6 +849,8 @@
             "truncated": false
           },
           "mode": "wizard",
+          "tabId": 7,
+          "sessionKey": "example-corp|production",
           "history_hint": "conv-1"
         }
       },
@@ -1008,7 +861,107 @@
           "type": "chat_request",
           "id": "c-1",
           "context": null,
-          "mode": "educational"
+          "mode": "educational",
+          "tabId": 7,
+          "sessionKey": "example-corp|production"
+        }
+      },
+      {
+        "schema": "chat_request",
+        "why": "missing tabId",
+        "value": {
+          "type": "chat_request",
+          "id": "c-1111",
+          "text": "What does this load balancer do?",
+          "context": {
+            "v": 1,
+            "capturedAt": 1719000000000,
+            "tabId": 7,
+            "url": "https://example-corp.console.ves.volterra.io/web/namespaces/default/http_loadbalancers/lb1",
+            "path": "/web/namespaces/default/http_loadbalancers/lb1",
+            "title": "lb1 — Distributed Cloud",
+            "ax": {
+              "role": "WebArea",
+              "name": "lb1",
+              "children": [
+                {
+                  "role": "button",
+                  "name": "Edit",
+                  "ref": "e12"
+                }
+              ]
+            },
+            "api": {
+              "url": "/api/config/namespaces/default/http_loadbalancers/lb1",
+              "status": 200,
+              "resourceType": "http_loadbalancers",
+              "body": {
+                "metadata": {
+                  "name": "lb1"
+                },
+                "spec": {
+                  "domains": ["lb1.example.com"]
+                }
+              },
+              "truncated": false
+            },
+            "truncated": false
+          },
+          "mode": "educational",
+          "sessionKey": "example-corp|production"
+        }
+      },
+      {
+        "schema": "chat_request",
+        "why": "missing sessionKey",
+        "value": {
+          "type": "chat_request",
+          "id": "c-1111",
+          "text": "What does this load balancer do?",
+          "context": {
+            "v": 1,
+            "capturedAt": 1719000000000,
+            "tabId": 7,
+            "url": "https://example-corp.console.ves.volterra.io/web/namespaces/default/http_loadbalancers/lb1",
+            "path": "/web/namespaces/default/http_loadbalancers/lb1",
+            "title": "lb1 — Distributed Cloud",
+            "ax": {
+              "role": "WebArea",
+              "name": "lb1",
+              "children": [
+                {
+                  "role": "button",
+                  "name": "Edit",
+                  "ref": "e12"
+                }
+              ]
+            },
+            "api": {
+              "url": "/api/config/namespaces/default/http_loadbalancers/lb1",
+              "status": 200,
+              "resourceType": "http_loadbalancers",
+              "body": {
+                "metadata": {
+                  "name": "lb1"
+                },
+                "spec": {
+                  "domains": ["lb1.example.com"]
+                }
+              },
+              "truncated": false
+            },
+            "truncated": false
+          },
+          "mode": "educational",
+          "tabId": 7
+        }
+      },
+      {
+        "schema": "chat_error",
+        "why": "missing reason",
+        "value": {
+          "type": "chat_error",
+          "id": "c-1"
         }
       },
       {
@@ -1091,68 +1044,6 @@
             "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": ""
-        }
-      },
-      {
-        "schema": "commands",
-        "why": "commands must be an array, not a name-keyed map",
-        "value": {
-          "type": "commands",
-          "commands": {
-            "meddpicc:qualify-deal": "Score and qualify a deal"
-          }
-        }
-      },
-      {
-        "schema": "commands",
-        "why": "an entry with no description has nothing to render in the menu",
-        "value": {
-          "type": "commands",
-          "commands": [
-            {
-              "name": "meddpicc:qualify-deal"
-            }
-          ]
-        }
-      },
-      {
-        "schema": "commands",
-        "why": "an entry with an empty name cannot be sent back as a prompt",
-        "value": {
-          "type": "commands",
-          "commands": [
-            {
-              "name": "",
-              "description": "Score and qualify a deal"
-            }
-          ]
-        }
-      },
-      {
-        "schema": "skills",
-        "why": "skills must be an array, not a name-keyed map",
-        "value": {
-          "type": "skills",
-          "skills": {
-            "meddpicc:coach": "MEDDPICC coaching"
-          }
-        }
       }
     ]
   }

package/src/browser/chat-handler.ts

@@ -102,14 +102,18 @@ export class ChatHandler {
 
 	attach(): void {
 		this.#server.onMessage(msg => {
-			if (isChatRequest(msg)) this.#handleChatRequest(msg as unknown as ChatRequest);
+			if (isChatRequest(msg, this.#server.serveKind === "browser" ? "browser" : "transport"))
+				this.#handleChatRequest(msg as unknown as ChatRequest);
 			else if (isChatStop(msg)) this.#handleChatStop(msg as unknown as { id: string });
 			// 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);
+			// Office-only provider configuration channel (#2095): swap the LLM
+			// provider/model in session memory at runtime (never persisted), then ack
+			// or nack. Contract-2 Chrome clients cannot configure credentials.
+			else if (this.#server.serveKind === "office" && isConfigure(msg)) {
+				this.#handleConfigure(msg as unknown as Configure);
+			}
 			// Skills enumeration (#2311): the pane asks for the loaded skills to populate
 			// the composer's Skills submenu.
 			else if (isListSkills(msg)) this.#handleListSkills();
@@ -128,7 +132,6 @@ export class ChatHandler {
 				this.#sendTerminal(chat, {
 					type: "chat_error",
 					id: chat.id,
-					error: "bridge disconnected",
 					reason: "bridge-disconnected",
 				});
 				chat.unsubscribe();
@@ -212,7 +215,7 @@ export class ChatHandler {
 			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false, images, serverTools });
 		} catch (err: unknown) {
 			const message = err instanceof Error ? err.message : "unknown error";
-			this.#sendTerminal(chat, { type: "chat_error", id, error: message, reason: classifyChatErrorReason(message) });
+			this.#sendTerminal(chat, { type: "chat_error", id, reason: classifyChatErrorReason(message) });
 		} finally {
 			if (!chat.terminalSent) {
 				this.#sendTerminal(chat, { type: "chat_done", id });
@@ -323,7 +326,6 @@ export class ChatHandler {
 				this.#sendTerminal(chat, {
 					type: "chat_error",
 					id: chat.id,
-					error: errorMsg,
 					reason: classifyChatErrorReason(errorMsg),
 				});
 			} else if (msg.stopReason === "toolUse" || msg.content.some(part => part.type === "toolCall")) {
@@ -421,12 +423,15 @@ export class ChatHandler {
 			await this.#session.setModel(model);
 
 			this.#server.send({ type: "configure_ack", model: model.id } satisfies ConfigureAck);
-		} catch (err) {
+		} catch {
+			// Collapse provider and validation details at the runtime boundary. The
+			// Office pane needs only a stable recovery signal and must never receive
+			// identity-bearing upstream error text.
 			// 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),
+				reason: "configuration-rejected",
 			} satisfies ConfigureError);
 		}
 	}
@@ -476,7 +481,6 @@ export class ChatHandler {
 			this.#sendTerminal(chat, {
 				type: "chat_error",
 				id: chat.id,
-				error: "session disposed",
 				reason: "session-disposed",
 			});
 			chat.unsubscribe();
@@ -503,12 +507,10 @@ export function requireHttpsUrl(raw: string): string {
 	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).
- * 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 {
+/** Classify an upstream/provider error into the closed public reason vocabulary.
+ * Token checks run before the generic 4xx check; unknown failures fail closed to
+ * provider-5xx instead of crossing the runtime boundary as raw text. */
+export function classifyChatErrorReason(message: string): ChatErrorReason {
 	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";
@@ -523,7 +525,7 @@ export function classifyChatErrorReason(message: string): ChatErrorReason | unde
 	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;
+	return "provider-5xx";
 }
 
 const MODE_INSTRUCTIONS: Record<InteractionMode, string> = {
@@ -661,7 +663,7 @@ function composeBrowserPageContext(parts: string[], context: PageContextSnapshot
 	if (pageState.operation === "login") {
 		parts.push("Page: LOGIN — session expired or first login. The user is on the Keycloak authentication page.");
 		parts.push(
-			"Use the login tool with their email and password to log in. The login tool handles both production and staging Keycloak (including login-staging.volterra.us). Do NOT bypass it or claim it doesn't support staging.",
+			"Ask the user to authenticate directly in the browser. Never request, accept, or enter their username, password, token, or other authentication secret.",
 		);
 	} else if (pageState.resource) {
 		const opLabel = pageState.operation.toUpperCase();

package/src/browser/chat-protocol.ts

@@ -83,6 +83,10 @@ export interface ChatRequest {
 	context: PageContextSnapshot | null;
 	mode: InteractionMode;
 	history_hint?: string;
+	/** Required for the Chrome host, whose side panel routes each turn to an
+	 * explicitly bound tab and tenant session. Office routing is transport-bound. */
+	tabId?: number;
+	sessionKey?: string;
 	/** Optional photo/image attachments, sent to the model as vision blocks. */
 	images?: ChatImage[];
 	/** Absolute local paths (files/folders) the user attached as context. The engine
@@ -175,11 +179,8 @@ 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). */
+/** Machine-readable cause of a terminal chat_error. Raw provider error text is
+ * deliberately absent because it can carry identity-bearing response content. */
 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
@@ -197,8 +198,7 @@ export type ChatErrorReason = (typeof CHAT_ERROR_REASONS)[number];
 export interface ChatError {
 	type: "chat_error";
 	id: string;
-	error: string;
-	reason?: ChatErrorReason;
+	reason: ChatErrorReason;
 }
 
 /** Liveness signal (contract 1.7.0): the worker is actively working the turn — e.g.
@@ -217,7 +217,7 @@ export interface ChatKeepalive {
 // to whatever host is driving the WS bridge (the chrome extension, an Office
 // add-in, etc.). The frames are FIELD-IDENTICAL to the transport-neutral
 // `RpcHostTool*` vocabulary (`src/host-tools/`), so they are re-exported here
-// rather than re-declared — one vocabulary across every transport, no drift.
+// rather than redeclared — one vocabulary across every transport, no drift.
 //
 // CRITICAL: `host_tool_result.result` and `host_tool_update.partialResult` are
 // `AgentToolResult` values — a `content[]` array — NOT a `{ data }` object. The
@@ -262,14 +262,13 @@ export interface SetHostToolsError {
 }
 
 // ---------------------------------------------------------------------------
-// Provider configuration channel (contract 1.9.0)
+// Office provider configuration channel
 //
-// 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.
+// Lets the office-xcsh add-in configure xcsh's LLM provider at runtime after the
+// socket is connected, without restarting the worker or persisting the token.
+// Contract-2 Chrome clients have no credential-configuration interface. 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
@@ -292,10 +291,10 @@ export interface ConfigureAck {
 }
 
 /** 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. */
+ * API key). The fixed reason prevents provider text from crossing the bridge. */
 export interface ConfigureError {
 	type: "configure_error";
-	error: string;
+	reason: "configuration-rejected";
 }
 
 // ---------------------------------------------------------------------------
@@ -317,14 +316,19 @@ function isValidChatImages(v: unknown): boolean {
 	});
 }
 
-export function isChatRequest(msg: Record<string, unknown>): boolean {
+export function isChatRequest(msg: Record<string, unknown>, routing: "browser" | "transport"): boolean {
 	return (
 		msg.type === "chat_request" &&
 		hasChatIdPrefix(msg.id) &&
 		typeof msg.text === "string" &&
 		typeof msg.mode === "string" &&
 		VALID_MODES.has(msg.mode) &&
-		isValidChatImages(msg.images)
+		isValidChatImages(msg.images) &&
+		(routing === "transport" ||
+			(typeof msg.tabId === "number" &&
+				Number.isFinite(msg.tabId) &&
+				typeof msg.sessionKey === "string" &&
+				msg.sessionKey.length > 0))
 	);
 }
 

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

@@ -84,7 +84,6 @@ export const BROWSER_TOOL_NAMES: readonly string[] = [
 	"fill",
 	"type_text",
 	"screenshot",
-	"login",
 	"read_ax",
 	"get_page_context",
 	"query_dom",