@f5-sales-demo/xcsh 19.95.4 → 19.97.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.95.4",
+	"version": "19.97.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",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.95.4",
-		"@f5-sales-demo/pi-agent-core": "19.95.4",
-		"@f5-sales-demo/pi-ai": "19.95.4",
-		"@f5-sales-demo/pi-natives": "19.95.4",
-		"@f5-sales-demo/pi-resource-management": "19.95.4",
-		"@f5-sales-demo/pi-tui": "19.95.4",
-		"@f5-sales-demo/pi-utils": "19.95.4",
+		"@f5-sales-demo/xcsh-stats": "19.97.0",
+		"@f5-sales-demo/pi-agent-core": "19.97.0",
+		"@f5-sales-demo/pi-ai": "19.97.0",
+		"@f5-sales-demo/pi-natives": "19.97.0",
+		"@f5-sales-demo/pi-resource-management": "19.97.0",
+		"@f5-sales-demo/pi-tui": "19.97.0",
+		"@f5-sales-demo/pi-utils": "19.97.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.11.0",
+	"contractVersion": "1.12.0",
 	"multiPortDiscovery": true,
 	"protocol": "tool_request/result",
 	"tools": [
@@ -858,7 +858,11 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 				"host_tool_cancel",
 				"configure",
 				"configure_ack",
-				"configure_error"
+				"configure_error",
+				"list_skills",
+				"skills",
+				"list_commands",
+				"commands"
 			],
 			"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": {
@@ -878,6 +882,6 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.11.0";
+export const EXTENSION_CONTRACT_VERSION = "1.12.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.11.0",
+  "contractVersion": "1.12.0",
   "multiPortDiscovery": true,
   "protocol": "tool_request/result",
   "tools": [
@@ -751,7 +751,11 @@
         "host_tool_cancel",
         "configure",
         "configure_ack",
-        "configure_error"
+        "configure_error",
+        "list_skills",
+        "skills",
+        "list_commands",
+        "commands"
       ],
       "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.11.0",
+  "contractVersion": "1.12.0",
   "schemas": {
     "chat_request": {
       "type": "object",
@@ -599,6 +599,68 @@
           "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": {
@@ -814,6 +876,38 @@
         "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": [
@@ -1014,6 +1108,51 @@
           "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

@@ -4,6 +4,7 @@ import type { AssistantMessage, ImageContent } from "@f5-sales-demo/pi-ai";
 import { settings } from "../config/settings";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
 import { toSkillSummaries } from "../extensibility/skills";
+import { expandSlashCommand, toSlashCommandSummaries } from "../extensibility/slash-commands";
 import {
 	isRpcHostToolResult,
 	isRpcHostToolUpdate,
@@ -28,6 +29,7 @@ import {
 	isChatRequest,
 	isChatStop,
 	isConfigure,
+	isListCommands,
 	isListSkills,
 	isSetHostTools,
 	type PageContextSnapshot,
@@ -35,6 +37,7 @@ import {
 	type SetHostToolsAck,
 	type SetHostToolsError,
 	type SkillsList,
+	type SlashCommandsList,
 } from "./chat-protocol";
 import { CONSOLE_ROUTES } from "./console-routes.generated";
 import type { BridgeServer } from "./extension-bridge";
@@ -110,6 +113,9 @@ export class ChatHandler {
 			// Skills enumeration (#2311): the pane asks for the loaded skills to populate
 			// the composer's Skills submenu.
 			else if (isListSkills(msg)) this.#handleListSkills();
+			// Slash-command enumeration: the pane asks for the session's file-based
+			// commands to populate the composer's `/` menu.
+			else if (isListCommands(msg)) this.#handleListCommands();
 			else if (isRpcHostToolResult(msg)) this.#hostToolBridge.handleResult(msg as unknown as HostToolResult);
 			else if (isRpcHostToolUpdate(msg)) this.#hostToolBridge.handleUpdate(msg as unknown as HostToolUpdate);
 		});
@@ -179,7 +185,14 @@ export class ChatHandler {
 		// model's read/grep/bash calls pass the gate. Session-scoped, in-memory, deduped.
 		const contextPaths = Array.isArray(req.contextPaths) ? sanitizeContextPaths(req.contextPaths) : [];
 		if (contextPaths.length > 0) grantSandboxPaths(contextPaths);
-		const prompt = composeChatPrompt(req.text, req.context, req.mode, this.#server.clientHost, contextPaths);
+		// Expand a file-based slash command HERE, on the user's raw text, before it is
+		// composed. Two reasons it cannot live in `AgentSession.prompt` for this surface:
+		// we call `prompt` with `expandPromptTemplates: false`, and `composeChatPrompt`
+		// appends the user's text last, so by then the string no longer starts with `/`.
+		// A `/name` that matches nothing is returned unchanged, which is what keeps the
+		// skill convention (same spelling, handled by the system prompt) working.
+		const text = expandSlashCommand(req.text, [...this.#session.slashCommands]);
+		const prompt = composeChatPrompt(text, req.context, req.mode, this.#server.clientHost, contextPaths);
 		// Photo/image attachments ride as base64 vision blocks (the model is
 		// vision-capable); text attachments are already folded into req.text upstream.
 		const images: ImageContent[] | undefined = req.images?.map(img => ({
@@ -433,6 +446,16 @@ export class ChatHandler {
 		this.#server.send({ type: "skills", skills: toSkillSummaries(this.#session.skills) } satisfies SkillsList);
 	}
 
+	/** Reply to `list_commands` with the session's file-based slash commands (name +
+	 *  description) so the pane can populate the composer's `/` menu. Pure read — the
+	 *  commands are already discovered; the template bodies never cross the wire. */
+	#handleListCommands(): void {
+		this.#server.send({
+			type: "commands",
+			commands: toSlashCommandSummaries(this.#session.slashCommands),
+		} satisfies SlashCommandsList);
+	}
+
 	#sendTerminal(chat: ActiveChat, frame: ChatDone | ChatError): void {
 		if (chat.terminalSent) return;
 		chat.terminalSent = true;

package/src/browser/chat-protocol.ts

@@ -129,6 +129,30 @@ export interface SkillsList {
 	skills: SkillInfo[];
 }
 
+/** Client → engine: enumerate the session's file-based slash commands for the
+ *  composer's `/` menu. Sent once after the pane connects, beside `list_skills`. */
+export interface ListCommands {
+	type: "list_commands";
+}
+
+/**
+ * One slash command surfaced to the pane's `/` menu.
+ *
+ * Deliberately NOT the command's `content`: that body is a prompt template which can run
+ * to hundreds of lines, and the menu needs a label. It also keeps the plugin author's
+ * instructions off the wire, where nothing reads them.
+ */
+export interface SlashCommandInfo {
+	name: string;
+	description: string;
+}
+
+/** Engine → client: the session's live slash commands, in load order. */
+export interface SlashCommandsList {
+	type: "commands";
+	commands: SlashCommandInfo[];
+}
+
 export interface ChatStop {
 	type: "chat_stop";
 	id: string;
@@ -312,6 +336,10 @@ export function isListSkills(msg: Record<string, unknown>): boolean {
 	return msg.type === "list_skills";
 }
 
+export function isListCommands(msg: Record<string, unknown>): boolean {
+	return msg.type === "list_commands";
+}
+
 export function isPickPath(msg: Record<string, unknown>): boolean {
 	return msg.type === "pick_path" && (msg.mode === "file" || msg.mode === "folder");
 }

package/src/browser/host-profiles.ts

@@ -94,9 +94,11 @@ SAFETY — NEVER DO THESE:
 const OFFICE_NATIVE_TOOLS_NOTE = `
 NATIVE TOOLS: Beyond the document host tools, you have xcsh's full local toolset — \`bash\` (run shell commands, including CLIs like \`az\`, \`gh\`, \`terraform\`, \`git\` when installed and authenticated), file tools (\`read\`/\`write\`/\`edit\`), and \`grep\` — plus any skills available in this workspace. Reach for them when the task genuinely needs them (pull live data with a CLI, read a local file the user points you at). Prefer the document host tools for document work. Your file tools and shell are confined to the folder xcsh was launched from.
 
-This pane runs NO MCP servers and NO plugin-provided tools — the tools listed above (plus the document host tools) are everything you have. Do not look for, read, or report on plugin/MCP manifests: to use a cloud or SCM CLI, invoke it directly with \`bash\` (e.g. \`az account show\`, \`gh repo view\`). The user sees your narration, so don't describe missing plugins as failures — just use the CLI.
+This pane runs NO MCP servers and exposes NO plugin-provided TOOLS — the tools listed above (plus the document host tools) are everything you can call. To use a cloud or SCM CLI, invoke it directly with \`bash\` (e.g. \`az account show\`, \`gh repo view\`) rather than hunting for an MCP server that would provide it. The user sees your narration, so don't describe a missing MCP tool as a failure — just use the CLI.
 
-SKILLS: When a message begins with \`/<skill-name>\` naming one of your available skills, treat it as a request to USE that skill — read its instructions (open \`skill://<skill-name>\`, or its SKILL.md via \`read\`) and follow them, applying any text after the name as the skill's input.
+Plugin RESOURCES are a different thing and they ARE available to you: an installed plugin's skills, slash commands, schemas, templates and engines. Read them through \`xcsh://plugin/<name>\` (summary), \`xcsh://plugin/<name>/<key>\` (a declared resource such as \`schema\`), or \`xcsh://plugin/<name>/file/<path>\` (any file in the plugin), and run a plugin's engine with \`bash\` (e.g. \`bun xcsh://plugin/<name>/file/engine/cli.ts <command>\`). When a plugin declares a deterministic engine, use it — never recompute by hand what the engine computes.
+
+SKILLS AND SLASH COMMANDS: A message beginning \`/<name>\` names either a slash command (already expanded for you before it arrived — just follow the instructions you were given) or one of your available skills. For a skill, treat it as a request to USE it — read its instructions (open \`skill://<skill-name>\`, or its SKILL.md via \`read\`) and follow them, applying any text after the name as the skill's input. Names from a plugin are prefixed with the plugin, e.g. \`/meddpicc:deal-review\`.
 
 SAFETY:
 - NEVER kill, stop, inspect, or manage the xcsh \`office serve\` process, its bridge ports, or any xcsh process — that bridge IS you; ending it ends the session.
@@ -122,6 +124,7 @@ TOOLS: Discover the workbook before you answer, then reach for the tool that mat
 - Use \`read_table\` for structured Excel Tables (it tracks the real extent), \`get_formulas\` to see the formulas behind cells, \`get_cell_metadata\` for cell types/number formats, and \`read_named_range\` to read a defined name.
 - Use \`sort_filter_table\` to sort or filter a Table by column.
 - Use \`read_range\`/\`write_range\` for arbitrary cell ranges (bare or sheet-qualified like Sheet2!A1:B10), and \`list_sheets\` when you only need the tab names.
+- Use \`add_sheet\` to build a report on its own tab instead of overwriting the user's data. It is idempotent — an existing tab of that name is reused — so add first, then \`write_range\` block by block, and do not read the sheet back to confirm.
 ${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR: