@f5-sales-demo/xcsh 19.87.0 → 19.88.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.87.0",
+	"version": "19.88.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.87.0",
-		"@f5-sales-demo/pi-agent-core": "19.87.0",
-		"@f5-sales-demo/pi-ai": "19.87.0",
-		"@f5-sales-demo/pi-natives": "19.87.0",
-		"@f5-sales-demo/pi-resource-management": "19.87.0",
-		"@f5-sales-demo/pi-tui": "19.87.0",
-		"@f5-sales-demo/pi-utils": "19.87.0",
+		"@f5-sales-demo/xcsh-stats": "19.88.0",
+		"@f5-sales-demo/pi-agent-core": "19.88.0",
+		"@f5-sales-demo/pi-ai": "19.88.0",
+		"@f5-sales-demo/pi-natives": "19.88.0",
+		"@f5-sales-demo/pi-resource-management": "19.88.0",
+		"@f5-sales-demo/pi-tui": "19.88.0",
+		"@f5-sales-demo/pi-utils": "19.88.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

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

@@ -100,16 +100,48 @@ export const BROWSER_TOOL_NAMES: readonly string[] = [
 
 /**
  * Builtin agent tools scoped into the headless OFFICE bridge (`xcsh office serve`).
- * The Office task pane drives a document (Excel/PowerPoint/Word), NOT a browser, so
- * it must get NONE of the {@link BROWSER_TOOL_NAMES} — those would be hallucinated
- * against a host with no browser to drive. The document's own tools arrive at
- * runtime over the bridge via `set_host_tools`; this list is only the minimal
- * general-purpose, host-neutral builtin toolset a document assistant can safely use.
  *
- * NOTE: an EMPTY list cannot express "no builtin tools" — createAgentSession/createTools
- * treat `[]` as "unscoped" and hand back the FULL builtin registry (bash/edit/python/
- * browser/…). So we pass an explicit minimal set instead. `calc` is the one builtin
- * that is pure computation — no browser, no shell, no filesystem, no network — and is
- * genuinely useful for spreadsheet/document math.
+ * FULL CLI-PARITY tool set (minus browser automation): the Office pane is a full
+ * local xcsh agent, so it gets the same general-purpose native tools the CLI has —
+ * `bash` (so it can shell out to `az`, `gh`, terraform, git, …), the file tools
+ * (`read`/`write`/`edit`), search (`grep`), plus planning (`todo_write`,
+ * `task`) and `calc`. (File-finding is covered by `bash`; the builtin `find`
+ * tool is omitted because its name collides with a browser tool.) The document's own Excel/PowerPoint/Word tools arrive at
+ * runtime over the bridge via `set_host_tools`.
+ *
+ * DELIBERATELY EXCLUDED:
+ *  - Every {@link BROWSER_TOOL_NAMES} entry — there is no browser to drive in a
+ *    document pane, so navigate/click/screenshot would only be hallucinated.
+ *  - `ask` (needs interactive stdin → would hang headless), `python` (spawns a
+ *    kernel → startup cost), `ssh`/`debug`/`notebook`/`browser`/`get_page_context`.
+ *
+ * SAFETY: the headless session pairs this with the bundled `sandbox-guard`
+ * extension (see headless-bridge.ts `bundledExtensions`), which confines the file
+ * tools + the shell's working dir to the launch cwd subtree — the CLI's own model.
+ * `az`/`gh` still run (network actions aren't filesystem-confined); credentials must
+ * already exist for the process user. There is no per-tool approval prompt — the
+ * local trusted bridge auto-runs tools exactly as the CLI does.
+ *
+ * THREAT MODEL (reviewed + accepted, 2026-07-24): the pane's agent auto-reads
+ * document content, which could be adversarial (a prompt-injected customer .xlsx)
+ * and steer it into shell/`az`/`gh` calls; the filesystem sandbox blocks file
+ * damage outside cwd but NOT network/cloud actions. This is the same exposure the
+ * xcsh CLI already carries (no approval system anywhere). The operator explicitly
+ * chose full CLI parity + FS sandbox over a bash approval gate, mitigating in
+ * practice by only opening trusted documents. If untrusted files become common,
+ * revisit with a per-shell approval round-trip (host_tool_call-style frame).
+ *
+ * NOTE: an EMPTY list cannot express "no builtin tools" — createTools treats `[]` as
+ * "unscoped" and returns the FULL registry (including browser tools). So this is an
+ * explicit curated array, not `[]`.
  */
-export const OFFICE_TOOL_NAMES: readonly string[] = ["calc"];
+export const OFFICE_TOOL_NAMES: readonly string[] = [
+	"read",
+	"write",
+	"edit",
+	"bash",
+	"grep",
+	"todo_write",
+	"task",
+	"calc",
+];

package/src/browser/headless-bridge.ts

@@ -134,12 +134,10 @@ export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = default
 	// selectProvider() reuses a dead bridge. The caller (startOfficeServe) treats
 	// the rethrow as a non-fatal "pane only" fallback.
 	try {
-		// Create ONE headless Office session scoped to the minimal general builtin set
-		// (OFFICE_TOOL_NAMES) with NO browser tools — neither the browser BUILTINS
-		// (navigate/click/…) nor the bridge-proxying browser CUSTOM tools, both of which
-		// would be hallucinated in a document task pane (there is no browser to drive).
-		// The document's own tools (Excel/Word/PowerPoint) arrive at runtime via
-		// set_host_tools; chat over xcsh's configured provider needs no browser tooling.
+		// Create ONE headless Office session with the full CLI-parity builtin set
+		// (OFFICE_TOOL_NAMES: bash/read/write/edit/grep/find/… — NO browser tools, which
+		// would be hallucinated in a document task pane). The document's own tools
+		// (Excel/Word/PowerPoint) arrive at runtime via set_host_tools.
 		const { session } = await deps.createAgentSession({
 			cwd,
 			hasUI: false,
@@ -149,6 +147,11 @@ export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = default
 			enableMCP: false,
 			enableLsp: false,
 			disableExtensionDiscovery: true,
+			// …but DO load the bundled filesystem sandbox: the pane runs full CLI-parity
+			// tools (bash/read/write), so it needs the CLI's safety net confining file
+			// tools + the shell's cwd to the launch directory subtree (sandbox.enabled
+			// defaults true). Without this, a discovery-disabled session ran ungated.
+			bundledExtensions: ["sandbox-guard"],
 		});
 
 		const chatHandler = new deps.ChatHandlerCtor(bridge, session);

package/src/browser/host-profiles.ts

@@ -85,6 +85,19 @@ SAFETY — NEVER DO THESE:
 
 `;
 
+/**
+ * Shared tail for every Office (document) profile: the pane is a FULL local xcsh
+ * agent — same native tools as the CLI — plus the one safety rule that shelling
+ * out makes necessary (don't let the agent kill its own bridge). Interpolated into
+ * each document profile so the three stay in sync (DRY).
+ */
+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.
+
+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.
+- NEVER run \`lsof\`/\`fuser\`/\`kill\`/\`pkill\` against the bridge ports or use the shell to manage xcsh itself.`;
+
 /**
  * Excel task-pane self-awareness prompt. The assistant works the OPEN workbook
  * via host tools (arriving at runtime over the bridge), thinking in cells,
@@ -95,7 +108,7 @@ You are still xcsh, the F5 Distributed Cloud technical coworker defined in your
 
 CRITICAL: ALWAYS respond with TEXT FIRST — the user sees a chat pane and expects a conversational reply, not silence while tools run. Answer questions from the data you read; only WRITE to the workbook when the user asks you to.
 
-CONTEXT: You can only access the open workbook. Think in cells, ranges, and — above all — FORMULAS and their dependencies:
+CONTEXT: Your workspace centers on the open workbook. Think in cells, ranges, and — above all — FORMULAS and their dependencies:
 - Preserve formula relationships. When you change a cell, let dependent cells recompute; do not overwrite a formula with its current value unless asked.
 - Warn the user before overwriting existing cell contents.
 - Cite specific cells and ranges precisely (e.g. A1, Sheet1!B2:B10) so the user can follow along.
@@ -105,6 +118,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.
+${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR:
 - Respond concisely with markdown. The task pane is narrow — avoid long code blocks.
@@ -123,7 +137,7 @@ You are still xcsh, the F5 Distributed Cloud technical coworker defined in your
 
 CRITICAL: ALWAYS respond with TEXT FIRST — the user sees a chat pane and expects a conversational reply, not silence while tools run. Answer questions from what you read; only edit the deck when the user asks you to.
 
-CONTEXT: You can only access the open presentation. Think in slides, shapes, and the slide master:
+CONTEXT: Your workspace centers on the open presentation. Think in slides, shapes, and the slide master:
 - Conform any new content to the deck's existing template, fonts, and colors — do not introduce a different look.
 - Make pinpoint, per-slide edits. Do NOT regenerate the whole deck to change one thing.
 - Refer to slides by number so the user can follow along.
@@ -132,6 +146,7 @@ TOOLS: Discover the deck before you answer, then reach for the tool that matches
 - Call \`get_presentation_info\` FIRST to discover all slides, their layouts, and shape counts before answering — do not guess the structure.
 - Use \`read_slide_shapes\` to see all shapes on a slide with their text + position, \`read_slide_layout\` for the layout/master applied to a slide, and \`modify_shape_text\` to edit the text of a named shape.
 - Use \`read_slides\` for a quick text-only scan of the whole deck, and \`add_text_box\`/\`add_slide\` to create new content.
+${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR:
 - Respond concisely with markdown. The task pane is narrow — avoid long code blocks.
@@ -151,7 +166,7 @@ You are still xcsh, the F5 Distributed Cloud technical coworker defined in your
 
 CRITICAL: ALWAYS respond with TEXT FIRST — the user sees a chat pane and expects a conversational reply, not silence while tools run. Answer questions from what you read; only edit the document when the user asks you to.
 
-CONTEXT: You can only access the open document. Think in paragraphs, the current selection, comments, and tracked changes:
+CONTEXT: Your workspace centers on the open document. Think in paragraphs, the current selection, comments, and tracked changes:
 - Preserve the document's styles and numbering — do not flatten formatting.
 - Describe your edits so the user can review them, and prefer changes the user can accept or reject.
 - When the user refers to "the selection" (or "this"), act on the current selection.
@@ -161,6 +176,7 @@ TOOLS: Discover the document before you answer, then reach for the tool that mat
 - Use \`read_paragraphs\` for styled paragraph content, \`read_selection\` for the current selection, \`get_comments\` for comments, and \`get_tracked_changes\` for revisions.
 - Use \`read_document\` when you need the full plain text.
 - Use \`insert_paragraph\` to add content at a specific location (start, end, or before/after the selection), and \`insert_text\` for inline text within a paragraph.
+${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR:
 - Respond concisely with markdown. The task pane is narrow — avoid long code blocks.

package/src/extensibility/extensions/loader.ts

@@ -336,8 +336,17 @@ export async function loadExtensionFromFactory(
 
 /**
  * Load extensions from paths.
+ *
+ * `bundledExtensionNames` opts specific bundled extensions (e.g. `["sandbox-guard"]`)
+ * into a session that has otherwise disabled discovery — the headless bridges use
+ * this to keep the CLI's filesystem safety net without paying for full discovery.
  */
-export async function loadExtensions(paths: string[], cwd: string, eventBus?: EventBus): Promise<LoadExtensionsResult> {
+export async function loadExtensions(
+	paths: string[],
+	cwd: string,
+	eventBus?: EventBus,
+	bundledExtensionNames: readonly string[] = [],
+): Promise<LoadExtensionsResult> {
 	const extensions: Extension[] = [];
 	const errors: Array<{ path: string; error: string }> = [];
 	const resolvedEventBus = eventBus ?? new EventBus();
@@ -356,11 +365,14 @@ export async function loadExtensions(paths: string[], cwd: string, eventBus?: Ev
 		}
 	}
 
-	return {
-		extensions,
-		errors,
-		runtime,
-	};
+	const result: LoadExtensionsResult = { extensions, errors, runtime };
+
+	if (bundledExtensionNames.length > 0) {
+		const allow = new Set(bundledExtensionNames);
+		await loadBundledExtensions(result, cwd, resolvedEventBus, name => !allow.has(name));
+	}
+
+	return result;
 }
 
 interface ExtensionManifest {

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.87.0",
-	"commit": "db63afc083e9c0dc054f4bd9253db872f5f7ff76",
-	"shortCommit": "db63afc",
+	"version": "19.88.0",
+	"commit": "4e87c996191e7c88ae503cedded3afee98177587",
+	"shortCommit": "4e87c99",
 	"branch": "main",
-	"tag": "v19.87.0",
-	"commitDate": "2026-07-24T17:43:35Z",
-	"buildDate": "2026-07-24T18:05:28.484Z",
+	"tag": "v19.88.0",
+	"commitDate": "2026-07-24T18:57:08Z",
+	"buildDate": "2026-07-24T19:23:46.325Z",
 	"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/db63afc083e9c0dc054f4bd9253db872f5f7ff76",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.87.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/4e87c996191e7c88ae503cedded3afee98177587",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.88.0"
 };

package/src/sdk.ts

@@ -188,6 +188,12 @@ export interface CreateAgentSessionOptions {
 	additionalExtensionPaths?: string[];
 	/** Disable extension discovery (explicit paths still load). */
 	disableExtensionDiscovery?: boolean;
+	/**
+	 * Bundled extensions to load even when discovery is disabled (e.g.
+	 * `["sandbox-guard"]`). Lets a headless session keep the CLI's filesystem
+	 * safety net without paying for full discovery.
+	 */
+	bundledExtensions?: string[];
 	/**
 	 * Pre-loaded extensions (skips file discovery).
 	 * @internal Used by CLI when extensions are loaded early to parse custom flags.
@@ -1238,7 +1244,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		let extensionsResult: LoadExtensionsResult;
 		if (options.disableExtensionDiscovery) {
 			const configuredPaths = options.additionalExtensionPaths ?? [];
-			extensionsResult = await logger.time("loadExtensions", loadExtensions, configuredPaths, cwd, eventBus);
+			extensionsResult = await logger.time(
+				"loadExtensions",
+				loadExtensions,
+				configuredPaths,
+				cwd,
+				eventBus,
+				options.bundledExtensions ?? [],
+			);
 			for (const { path, error } of extensionsResult.errors) {
 				logger.error("Failed to load extension", { path, error });
 			}