@f5-sales-demo/xcsh 19.88.0 → 19.89.0

package/package.json

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

package/src/browser/chat-handler.ts

@@ -1,4 +1,7 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AssistantMessage, ImageContent } from "@f5-sales-demo/pi-ai";
+import { settings } from "../config/settings";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
 import {
 	isRpcHostToolResult,
@@ -24,11 +27,13 @@ import {
 	isChatRequest,
 	isChatStop,
 	isConfigure,
+	isListSkills,
 	isSetHostTools,
 	type PageContextSnapshot,
 	type SetHostTools,
 	type SetHostToolsAck,
 	type SetHostToolsError,
+	type SkillsList,
 } from "./chat-protocol";
 import { CONSOLE_ROUTES } from "./console-routes.generated";
 import type { BridgeServer } from "./extension-bridge";
@@ -101,6 +106,9 @@ export class ChatHandler {
 			// 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);
+			// Skills enumeration (#2311): the pane asks for the loaded skills to populate
+			// the composer's Skills submenu.
+			else if (isListSkills(msg)) this.#handleListSkills();
 			else if (isRpcHostToolResult(msg)) this.#hostToolBridge.handleResult(msg as unknown as HostToolResult);
 			else if (isRpcHostToolUpdate(msg)) this.#hostToolBridge.handleUpdate(msg as unknown as HostToolUpdate);
 		});
@@ -164,7 +172,13 @@ export class ChatHandler {
 		});
 		chat.unsubscribe = unsubscribe;
 
-		const prompt = composeChatPrompt(req.text, req.context, req.mode, this.#server.clientHost);
+		// Sanitize the attached paths (absolute, `..`-collapsed, confined to the user's
+		// own space, no control chars) — the engine must not blindly widen its sandbox to
+		// a client-supplied path. Grant the safe set BEFORE composing the prompt so the
+		// 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);
 		// 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 => ({
@@ -172,10 +186,16 @@ export class ChatHandler {
 			data: img.data,
 			mimeType: img.mimeType,
 		}));
+		// "Search the web" toggle → add Anthropic's server-side web-search tool for this
+		// turn only. The gateway executes it and returns cited results; source URLs the
+		// model writes inline flow to the pane's Sources chips via extractReferences.
+		const serverTools = req.web_search
+			? [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }]
+			: undefined;
 
 		try {
 			chat.promptAt = Date.now();
-			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false, images });
+			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) });
@@ -377,6 +397,15 @@ export class ChatHandler {
 		this.#session.agent.abort();
 	}
 
+	/** Reply to `list_skills` with the session's live skills (name + description) so
+	 *  the pane can populate the composer's Skills submenu. Pure read — skills are
+	 *  already loaded on the session; the model actions them via the read tool + the
+	 *  system prompt (Phase 2A enabled `read`), so this is enumeration only. */
+	#handleListSkills(): void {
+		const skills = this.#session.skills.map(s => ({ name: s.name, description: s.description }));
+		this.#server.send({ type: "skills", skills } satisfies SkillsList);
+	}
+
 	#sendTerminal(chat: ActiveChat, frame: ChatDone | ChatError): void {
 		if (chat.terminalSent) return;
 		chat.terminalSent = true;
@@ -455,11 +484,79 @@ const MODE_INSTRUCTIONS: Record<InteractionMode, string> = {
 	annotation: "Create on-page teaching annotations that highlight key elements and explain their purpose.",
 };
 
+/** Bases a user-attached context path must fall under. Confines grants to the user's
+ *  own space (home, the project cwd, temp, external volumes, /opt) and thereby blocks
+ *  a client from widening the sandbox to system/credential dirs (`/etc`, `/var`,
+ *  `/usr`, `/System`, other users' homes, `/`). */
+function contextPathAllowedBases(): string[] {
+	const bases = [process.cwd(), "/tmp", "/private/tmp", "/Volumes", "/opt"];
+	const home = process.env.HOME ?? process.env.USERPROFILE;
+	if (home) bases.push(home);
+	// Canonicalize with realpath so BOTH sides of the containment check are symlink-free
+	// (a symlink base like /tmp→/private/tmp must compare against the real target).
+	return bases.map(b => {
+		try {
+			return fs.realpathSync(b);
+		} catch {
+			return path.resolve(b);
+		}
+	});
+}
+
+/**
+ * Canonicalize + validate the user-attached context paths BEFORE they widen the
+ * sandbox or are named in the prompt. Rejects anything that isn't an absolute path
+ * confined to {@link contextPathAllowedBases} (after collapsing `..`), and anything
+ * carrying control characters (a prompt-injection vector). Deduped. This is the trust
+ * boundary: the engine must not blindly grant a client-supplied path to its own
+ * filesystem sandbox.
+ */
+export function sanitizeContextPaths(paths: string[]): string[] {
+	const bases = contextPathAllowedBases();
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const p of paths) {
+		if (typeof p !== "string" || p.length === 0 || /[\n\r\0]/.test(p) || !path.isAbsolute(p)) continue;
+		// realpathSync resolves symlinks — a link INSIDE an allowed base that points out to
+		// /etc canonicalizes to /etc and fails the containment check — AND requires the
+		// path to exist, so a non-existent (typo'd/spoofed) attachment is skipped.
+		let real: string;
+		try {
+			real = fs.realpathSync(p);
+		} catch {
+			continue;
+		}
+		const within = bases.some(base => real === base || real.startsWith(base + path.sep));
+		if (!within || seen.has(real)) continue;
+		seen.add(real);
+		out.push(real);
+	}
+	return out;
+}
+
+/**
+ * Append absolute context paths to the session's sandbox read-allowlist. In-memory
+ * (`override`, never persisted) and deduped, so re-attaching a path is a no-op. The
+ * sandbox-guard keys its policy cache on the allow-list, so the grant takes effect on
+ * the model's next file tool call. Best-effort: a pre-init settings proxy is tolerated.
+ * Callers MUST pass paths through {@link sanitizeContextPaths} first.
+ */
+export function grantSandboxPaths(paths: string[]): void {
+	try {
+		const current = (settings.get("sandbox.allowRead") as string[] | undefined) ?? [];
+		const merged = Array.from(new Set([...current, ...paths]));
+		if (merged.length !== current.length) settings.override("sandbox.allowRead", merged);
+	} catch {
+		/* settings not initialized (some SDK/test contexts) — the grant is best-effort */
+	}
+}
+
 export function composeChatPrompt(
 	text: string,
 	context: PageContextSnapshot | null,
 	mode: InteractionMode,
 	host: ClientHost | null,
+	contextPaths?: string[],
 ): string {
 	const parts: string[] = [];
 
@@ -477,6 +574,17 @@ export function composeChatPrompt(
 		if (context) composeBrowserPageContext(parts, context);
 	}
 
+	// User-attached local context paths (files/folders). They're granted to the
+	// sandbox alongside this, so the model may read them on demand — tell it they exist.
+	if (contextPaths && contextPaths.length > 0) {
+		parts.push("");
+		// JSON.stringify each path: an unambiguous, escaped boundary so a path can't
+		// blur into surrounding prompt text (belt-and-suspenders — they're pre-sanitized).
+		parts.push(
+			`The user attached these local paths as context; read them with your tools (read/grep/bash) as needed:\n${contextPaths.map(p => `- ${JSON.stringify(p)}`).join("\n")}`,
+		);
+	}
+
 	parts.push("");
 	parts.push(text);
 	return parts.join("\n");

package/src/browser/chat-protocol.ts

@@ -85,6 +85,48 @@ export interface ChatRequest {
 	history_hint?: 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
+	 *  grants them to the filesystem sandbox for the session and tells the model they
+	 *  are available to read on demand. */
+	contextPaths?: string[];
+	/** When true, the engine adds Anthropic's server-side web-search tool to this
+	 *  turn's request (the "Search the web" composer toggle). */
+	web_search?: boolean;
+}
+
+/** Client → engine: open a native OS file/folder picker on the machine running the
+ *  bridge and return the chosen absolute path. */
+export interface PickPath {
+	type: "pick_path";
+	mode: "file" | "folder";
+}
+
+/** Engine → client: the picker result. `path` is set on success; `canceled` when the
+ *  user dismissed the dialog; `unsupported` when the platform has no native picker
+ *  (the pane then falls back to manual path entry). */
+export interface PathPicked {
+	type: "path_picked";
+	path?: string;
+	canceled?: boolean;
+	unsupported?: boolean;
+}
+
+/** Client → engine: enumerate the session's loaded skills for the composer's
+ *  Skills submenu. Sent once after the pane connects. */
+export interface ListSkills {
+	type: "list_skills";
+}
+
+/** One skill surfaced to the pane's Skills submenu (name + human description). */
+export interface SkillInfo {
+	name: string;
+	description: string;
+}
+
+/** Engine → client: the session's live skills, in load order. */
+export interface SkillsList {
+	type: "skills";
+	skills: SkillInfo[];
 }
 
 export interface ChatStop {
@@ -266,6 +308,14 @@ export function isChatStop(msg: Record<string, unknown>): boolean {
 	return msg.type === "chat_stop" && hasChatIdPrefix(msg.id);
 }
 
+export function isListSkills(msg: Record<string, unknown>): boolean {
+	return msg.type === "list_skills";
+}
+
+export function isPickPath(msg: Record<string, unknown>): boolean {
+	return msg.type === "pick_path" && (msg.mode === "file" || msg.mode === "folder");
+}
+
 export function isSetHostTools(msg: Record<string, unknown>): boolean {
 	return msg.type === "set_host_tools" && Array.isArray(msg.tools);
 }

package/src/browser/headless-bridge.ts

@@ -20,8 +20,10 @@ import { ContextService } from "../services/xcsh-context";
 import { deriveTenantEnv } from "../services/xcsh-env";
 import { resolveBridgeTls } from "./bridge-cert";
 import { ChatHandler } from "./chat-handler";
+import { isPickPath, type PathPicked } from "./chat-protocol";
 import { type BridgeServer, OFFICE_PORT_RANGE, startBridgeServer } from "./extension-bridge";
 import { OFFICE_TOOL_NAMES } from "./extension-bridge-tools";
+import { pickPathNative } from "./native-picker";
 import { setSharedBridgeServer } from "./provider";
 
 /** A running headless bridge + a teardown that disposes the chat handler and
@@ -69,6 +71,9 @@ export interface HeadlessBridgeDeps {
 	setSharedBridgeServer: typeof setSharedBridgeServer;
 	createAgentSession: typeof createAgentSession;
 	ChatHandlerCtor: typeof ChatHandler;
+	/** Native OS file/folder picker (macOS osascript by default). Injectable so tests
+	 *  don't open a real dialog. */
+	pickPath: typeof pickPathNative;
 }
 
 const defaultDeps: HeadlessBridgeDeps = {
@@ -96,6 +101,7 @@ const defaultDeps: HeadlessBridgeDeps = {
 	setSharedBridgeServer,
 	createAgentSession,
 	ChatHandlerCtor: ChatHandler,
+	pickPath: pickPathNative,
 };
 
 /**
@@ -157,9 +163,23 @@ export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = default
 		const chatHandler = new deps.ChatHandlerCtor(bridge, session);
 		chatHandler.attach();
 
+		// Second bridge subscriber (the bridge fans out to all): serve `pick_path` by
+		// opening a native OS picker and replying `path_picked`. Pure — it only returns
+		// the chosen path; the sandbox grant + prompt note happen in ChatHandler when the
+		// path rides the next `chat_request.contextPaths` (kept atomic there). `disposed`
+		// guards against a superseded serve firing the picker on a closed bridge.
+		let disposed = false;
+		bridge.onMessage(async msg => {
+			if (disposed || !isPickPath(msg)) return;
+			const { path, canceled, unsupported } = await deps.pickPath((msg as { mode: "file" | "folder" }).mode);
+			if (disposed) return;
+			bridge.send({ type: "path_picked", path, canceled, unsupported } satisfies PathPicked);
+		});
+
 		return {
 			bridge,
 			dispose: async () => {
+				disposed = true;
 				chatHandler.dispose();
 				deps.setSharedBridgeServer(null);
 				await bridge.close();

package/src/browser/host-profiles.ts

@@ -94,6 +94,8 @@ 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.
 
+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.
+
 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.`;

package/src/browser/native-picker.ts

@@ -0,0 +1,47 @@
+/**
+ * Native OS file/folder picker for the local Office bridge.
+ *
+ * An Office task-pane WebView cannot open a local file dialog, but the bridge runs
+ * in-process on the user's machine, so it can. macOS uses `osascript`'s `choose
+ * file`/`choose folder`; other platforms have no one-liner equivalent, so the pane
+ * falls back to manual path entry there.
+ *
+ * ASYNC on purpose: the dialog blocks until the user responds, so a synchronous
+ * spawn would stall the bridge's event loop (heartbeats, in-flight turns) for the
+ * whole time it's open. `Bun.spawn` + `await proc.exited` keeps the bridge live.
+ */
+
+export interface PickResult {
+	ok: boolean;
+	/** Absolute path chosen (no trailing slash), when `ok`. */
+	path?: string;
+	/** The user dismissed the dialog. */
+	canceled?: boolean;
+	/** This platform has no native picker; the pane should prompt for a path instead. */
+	unsupported?: boolean;
+}
+
+/**
+ * Open a native picker and resolve the chosen absolute path. Never throws — every
+ * failure maps to a `PickResult` flag so the caller can respond gracefully.
+ */
+export async function pickPathNative(mode: "file" | "folder"): Promise<PickResult> {
+	// macOS only for now — osascript is not present on win32/linux.
+	if (process.platform !== "darwin") return { ok: false, unsupported: true };
+	const script = mode === "folder" ? "POSIX path of (choose folder)" : "POSIX path of (choose file)";
+	try {
+		const proc = Bun.spawn(["osascript", "-e", script], { stdout: "pipe", stderr: "ignore" });
+		const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+		// Cancel raises AppleScript error -128 → non-zero exit, empty stdout.
+		if (code !== 0) return { ok: false, canceled: true };
+		let path = out.trim();
+		if (!path) return { ok: false, canceled: true };
+		// `choose folder` yields a trailing slash; normalize to a bare dir path so it
+		// matches the sandbox allow-rule root exactly.
+		if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+		return { ok: true, path };
+	} catch {
+		// osascript missing/blocked — treat as unsupported so the pane offers manual entry.
+		return { ok: false, unsupported: true };
+	}
+}

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.88.0",
-	"commit": "4e87c996191e7c88ae503cedded3afee98177587",
-	"shortCommit": "4e87c99",
+	"version": "19.89.0",
+	"commit": "e3c72edcac3935dc928e0599909ce1fc9bdc4832",
+	"shortCommit": "e3c72ed",
 	"branch": "main",
-	"tag": "v19.88.0",
-	"commitDate": "2026-07-24T18:57:08Z",
-	"buildDate": "2026-07-24T19:23:46.325Z",
+	"tag": "v19.89.0",
+	"commitDate": "2026-07-24T23:47:33Z",
+	"buildDate": "2026-07-25T00:13:14.668Z",
 	"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/4e87c996191e7c88ae503cedded3afee98177587",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.88.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/e3c72edcac3935dc928e0599909ce1fc9bdc4832",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.89.0"
 };

package/src/internal-urls/terraform-index.generated.ts

@@ -167,7 +167,7 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			name: "Uncategorized",
 			slug: "uncategorized",
 			description: "Resources pending categorization",
-			resource_count: 6,
+			resource_count: 7,
 			resources: [
 				"application_profiles",
 				"authorization_server",
@@ -175,6 +175,7 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 				"mitigated_domain",
 				"protected_application",
 				"protected_domain",
+				"registration_approval",
 			],
 		},
 		{
@@ -1427,6 +1428,17 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			},
 			import_syntax: "terraform import xcsh_registration.example namespace/name",
 		},
+		registration_approval: {
+			category: "uncategorized",
+			description: "Request for admission approval. configuration",
+			required: ["name", "namespace"],
+			minimal_config:
+				'resource "xcsh_registration_approval" "example" {\n  name      = "example-registration-approval"\n  namespace = "staging"\n}',
+			dependencies: {
+				requires: [],
+			},
+			import_syntax: "terraform import xcsh_registration_approval.example namespace/name",
+		},
 		route: {
 			category: "load-balancing",
 			description:

package/src/session/agent-session.ts

@@ -277,6 +277,12 @@ export interface PromptOptions {
 	attribution?: MessageAttribution;
 	/** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
 	skipCompactionCheck?: boolean;
+	/**
+	 * Raw provider "server tool" specs to inject into THIS turn's request tools, e.g.
+	 * Anthropic's `{type:"web_search_20250305", name:"web_search", max_uses:N}`. Rides
+	 * the provider `onPayload` seam (per-turn, no client-side tool registration).
+	 */
+	serverTools?: Record<string, unknown>[];
 }
 
 /** Result from cycleModel() */
@@ -2632,7 +2638,7 @@ export class AgentSession {
 	async #promptWithMessage(
 		message: AgentMessage,
 		expandedText: string,
-		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck"> & {
+		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck" | "serverTools"> & {
 			prependMessages?: AgentMessage[];
 			skipPostPromptRecoveryWait?: boolean;
 		},
@@ -2753,7 +2759,10 @@ export class AgentSession {
 				return;
 			}
 
-			const agentPromptOptions = options?.toolChoice ? { toolChoice: options.toolChoice } : undefined;
+			const agentPromptOptions =
+				options?.toolChoice || options?.serverTools
+					? { toolChoice: options?.toolChoice, serverTools: options?.serverTools }
+					: undefined;
 			await logger.ttftAttr("ttft.agent-loop-total", () =>
 				this.#promptAgentWithIdleRetry(messages, agentPromptOptions),
 			);
@@ -5601,7 +5610,10 @@ export class AgentSession {
 		this.#resolveRetry();
 	}
 
-	async #promptAgentWithIdleRetry(messages: AgentMessage[], options?: { toolChoice?: ToolChoice }): Promise<void> {
+	async #promptAgentWithIdleRetry(
+		messages: AgentMessage[],
+		options?: { toolChoice?: ToolChoice; serverTools?: Record<string, unknown>[] },
+	): Promise<void> {
 		const deadline = Date.now() + 30_000;
 		for (;;) {
 			try {