@f5-sales-demo/xcsh 21.0.0 → 21.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.0.0",
+	"version": "21.2.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",
@@ -61,13 +61,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
-		"@f5-sales-demo/pi-agent-core": "21.0.0",
-		"@f5-sales-demo/pi-ai": "21.0.0",
-		"@f5-sales-demo/pi-natives": "21.0.0",
-		"@f5-sales-demo/pi-resource-management": "21.0.0",
-		"@f5-sales-demo/pi-tui": "21.0.0",
-		"@f5-sales-demo/pi-utils": "21.0.0",
-		"@f5-sales-demo/xcsh-stats": "21.0.0",
+		"@f5-sales-demo/pi-agent-core": "21.2.0",
+		"@f5-sales-demo/pi-ai": "21.2.0",
+		"@f5-sales-demo/pi-natives": "21.2.0",
+		"@f5-sales-demo/pi-resource-management": "21.2.0",
+		"@f5-sales-demo/pi-tui": "21.2.0",
+		"@f5-sales-demo/pi-utils": "21.2.0",
+		"@f5-sales-demo/xcsh-stats": "21.2.0",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",

package/src/browser/capabilities.generated.ts

@@ -15,13 +15,33 @@ export interface ExtensionToolDef {
 	readonly flags?: ExtensionToolFlags;
 }
 
+export type ExtensionInteractionMode =
+	| "educational"
+	| "presentation"
+	| "configuration"
+	| "screenshot"
+	| "annotation";
+
+export interface ExtensionChatPromptHints {
+	readonly role: string;
+	readonly grounding: string;
+	readonly referenceLinks: string;
+	readonly toolUse: string;
+	readonly modes: Readonly<Record<ExtensionInteractionMode, string>>;
+}
+
+export interface ExtensionFeatures {
+	readonly chat: { readonly promptHints: ExtensionChatPromptHints; readonly [key: string]: unknown };
+	readonly [key: string]: unknown;
+}
+
 export interface ExtensionCapabilities {
 	readonly version: string;
 	readonly contractVersion: string;
 	readonly multiPortDiscovery?: boolean;
 	readonly protocol: string;
 	readonly tools: readonly ExtensionToolDef[];
-	readonly features: Record<string, unknown>;
+	readonly features: ExtensionFeatures;
 }
 
 export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {

package/src/browser/chat-handler.ts

@@ -21,6 +21,7 @@ import {
 import { LITELLM_LOGIN_MODEL_CHOICES } from "../modes/controllers/login-model";
 import { extractReferences } from "../references";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import { EXTENSION_CAPABILITIES } from "./capabilities.generated";
 import {
 	type ChatDelta,
 	type ChatDone,
@@ -689,14 +690,6 @@ export function classifyChatErrorReason(message: string): ChatErrorReason {
 	return "provider-5xx";
 }
 
-const MODE_INSTRUCTIONS: Record<InteractionMode, string> = {
-	educational: "Explain concepts and settings in depth. Help the user understand what they're looking at and why.",
-	presentation: "Guide a structured walkthrough. Narrate each step clearly for a live audience.",
-	configuration: "Help the user build or modify F5 XC configuration. Be precise and action-oriented.",
-	screenshot: "Focus on capturing annotated screenshots that document the current state.",
-	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`,
@@ -779,11 +772,22 @@ export function composeChatPrompt(
 	const profile = hostProfile(host);
 	parts.push(profile.systemPrompt);
 
+	const promptHints = EXTENSION_CAPABILITIES.features.chat.promptHints;
+
 	// Browser hosts ALSO get an interaction mode + the page-context block. Document
 	// hosts get NEITHER: Office sends no page context and has no browser modes; its
 	// tools + document state arrive at runtime via set_host_tools.
 	if (profile.kind === "browser") {
-		parts.push(`[Chat mode: ${mode}] ${MODE_INSTRUCTIONS[mode]}`);
+		parts.push(
+			[
+				"[Published extension chat contract]",
+				promptHints.role,
+				promptHints.grounding,
+				promptHints.referenceLinks,
+				promptHints.toolUse,
+			].join("\n"),
+		);
+		parts.push(`[Chat mode: ${mode}] ${promptHints.modes[mode]}`);
 		if (context) composeBrowserPageContext(parts, context);
 	}
 

package/src/browser/extension-contract.ts

@@ -46,3 +46,65 @@ export function extractRequestedTools(source: string): string[] {
 	while ((m = re.exec(source)) !== null) out.add(m[1]);
 	return [...out];
 }
+
+interface ToolReferenceManifest {
+	readonly contractVersion: string;
+	readonly tools: readonly {
+		readonly name: string;
+		readonly summary: string;
+		readonly category: string;
+		readonly params: Readonly<Record<string, unknown>>;
+		readonly flags?: {
+			readonly readOnly?: boolean;
+			readonly mutates?: boolean;
+			readonly requiresExplainMode?: boolean;
+		};
+	}[];
+}
+
+function compareText(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** Stable JSON with object keys sorted recursively and array order preserved. */
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>).sort(([left], [right]) =>
+			compareText(left, right),
+		);
+		return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+/** Render the complete extension tool surface as deterministic Markdown. */
+export function renderToolReference(manifest: ToolReferenceManifest): string {
+	const categories = new Map<string, ToolReferenceManifest["tools"][number][]>();
+	for (const tool of manifest.tools) {
+		const tools = categories.get(tool.category) ?? [];
+		tools.push(tool);
+		categories.set(tool.category, tools);
+	}
+
+	const lines = [
+		"# Chrome Extension Tool Signatures",
+		"",
+		`Generated from extension capability contract \`${manifest.contractVersion}\`.`,
+	];
+	for (const category of [...categories.keys()].sort(compareText)) {
+		lines.push("", `## ${category}`);
+		for (const tool of (categories.get(category) ?? []).sort((left, right) => compareText(left.name, right.name))) {
+			lines.push(
+				"",
+				`### \`${tool.name}\``,
+				"",
+				tool.summary,
+				"",
+				`- Parameters: \`${canonicalJson(tool.params)}\``,
+				`- Semantic flags: \`${canonicalJson(tool.flags ?? {})}\``,
+			);
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}

package/src/cli/args.ts

@@ -17,6 +17,8 @@ import {
 
 export type Mode = "text" | "json" | "rpc" | "acp";
 
+export type ExtensionFlagRegistry = ReadonlyMap<string, { type: "boolean" | "string" }>;
+
 export interface Args {
 	cwd?: string;
 	allowHome?: boolean;
@@ -224,7 +226,97 @@ function isValueToken(token: string | undefined): token is string {
 	return token !== undefined && !token.startsWith("-") && !token.startsWith("@");
 }
 
-export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+export interface LaunchBootstrapArgs {
+	allowHome?: boolean;
+	cwd?: string;
+	noSandbox?: boolean;
+	allowPath: string[];
+	noMemories?: boolean;
+	hooks: string[];
+	extensions: string[];
+	noExtensions?: boolean;
+	pluginDirs: string[];
+	preExtensionExit: boolean;
+}
+
+const BOOTSTRAP_VALUE_FLAGS = new Set(["allow-path", "hook", "extension", "plugin-dir"]);
+const PRE_EXTENSION_EXITS = new Set(["version", "list-models", "export"]);
+
+/**
+ * Read only the built-in controls needed to load extensions.
+ *
+ * This is deliberately not an argument parse: it never classifies positional input, files, or
+ * extension flags. It only follows the known built-in grammar far enough to avoid mistaking a
+ * built-in value for a discovery control. The authoritative parse happens after this scan.
+ */
+export function scanLaunchBootstrapArgs(args: readonly string[]): LaunchBootstrapArgs {
+	const result: LaunchBootstrapArgs = {
+		allowPath: [],
+		hooks: [],
+		extensions: [],
+		pluginDirs: [],
+		preExtensionExit: false,
+	};
+	const tokens = normalizeFlagTokens(args);
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--") break;
+		if (!token.startsWith("-") || token === "-") continue;
+
+		const name = token.startsWith("--") ? token.slice(2) : flagNameForChar(token.slice(1));
+		if (name === undefined) continue;
+		const spec = flagSpec(name);
+		if (!spec) continue;
+
+		let value: string | true = true;
+		if (spec.arity === "optional-value") {
+			if (isValueToken(tokens[i + 1])) value = tokens[++i];
+		} else if (takesValue(spec)) {
+			if (tokens[i + 1] === undefined) continue;
+			value = tokens[++i];
+		}
+
+		if (PRE_EXTENSION_EXITS.has(name)) result.preExtensionExit = true;
+		if (name === "allow-home") result.allowHome = true;
+		if (name === "no-sandbox") result.noSandbox = true;
+		if (name === "no-memories") result.noMemories = true;
+		if (name === "no-extensions") result.noExtensions = true;
+		if (BOOTSTRAP_VALUE_FLAGS.has(name) && value !== true) {
+			if (name === "allow-path") result.allowPath.push(value);
+			if (name === "hook") result.hooks.push(value);
+			if (name === "extension") result.extensions.push(value);
+			if (name === "plugin-dir") result.pluginDirs.push(value);
+		}
+	}
+
+	return result;
+}
+
+export interface ResolvedLaunchArgs {
+	bootstrap: LaunchBootstrapArgs;
+	parsed: Args;
+	extensionFlags?: ExtensionFlagRegistry;
+}
+
+/**
+ * Resolve extension registrations before the one parse whose result drives launch behavior.
+ * Version/model-list/export retain their pre-extension fast path.
+ */
+export async function resolveLaunchArgs(
+	args: readonly string[],
+	loadExtensionFlags: (bootstrap: LaunchBootstrapArgs) => Promise<ExtensionFlagRegistry>,
+): Promise<ResolvedLaunchArgs> {
+	const bootstrap = scanLaunchBootstrapArgs(args);
+	const extensionFlags = bootstrap.preExtensionExit ? undefined : await loadExtensionFlags(bootstrap);
+	return {
+		bootstrap,
+		parsed: parseArgs([...args], extensionFlags),
+		...(extensionFlags ? { extensionFlags } : {}),
+	};
+}
+
+export function parseArgs(args: string[], extensionFlags?: ExtensionFlagRegistry): Args {
 	const result: Args = {
 		messages: [],
 		fileArgs: [],
@@ -282,23 +374,20 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			continue;
 		}
 
-		// Extension flags are only known on the second parse, once extensions have loaded.
+		// Extension registrations are loaded before this authoritative parse.
 		const extFlag = name === undefined ? undefined : extensionFlags?.get(name);
 		if (extFlag && name !== undefined) {
 			if (extFlag.type === "boolean") {
-				result.unknownFlags.set(name, true);
+				const inlineValue = token.startsWith("--") ? token.split("=", 2)[1] : undefined;
+				result.unknownFlags.set(name, inlineValue === undefined ? true : inlineValue === "true");
 			} else if (i + 1 < tokens.length) {
 				result.unknownFlags.set(name, tokens[++i]);
 			}
 			continue;
 		}
 
-		// Record the flag, but do NOT consume the token after it. The bootstrap parse runs before
-		// extensions load, so it cannot know whether an unrecognized flag takes a value: swallowing
-		// the next token silently discards the user's prompt whenever the flag turns out to be
-		// boolean (`xcsh -p --verbose "do work"`). Leaving it means a string extension flag's value
-		// still reaches `messages`, which is the pre-existing behaviour and the lesser harm — the
-		// real fix is to load extensions before the first parse, which is out of scope here.
+		// Do not consume a following token for a genuine unknown flag: it may be prompt content.
+		// Registered extension flags never reach this path because launch discovers them first.
 		result.unrecognizedFlags.push({ token, name: name ?? token.replace(/^-+/, "") });
 	}
 

package/src/cli/flag-spec.ts

@@ -175,20 +175,23 @@ export function validateInlineFlagSyntax(args: readonly string[], extensionFlags
 		if (!inline) continue;
 
 		const spec = flagSpec(inline.name);
-		const isBoolean = spec?.arity === "boolean" || extensionFlags?.get(inline.name)?.type === "boolean";
-		if (isBoolean) {
+		if (spec?.arity === "boolean") {
 			throw new CliUsageError(`--${inline.name} is a boolean flag and does not take a value`);
 		}
+		if (extensionFlags?.get(inline.name)?.type === "boolean" && inline.value !== "true" && inline.value !== "false") {
+			throw new CliUsageError(`--${inline.name} is a boolean flag and expects true or false`);
+		}
 	}
 }
 
 /**
  * Rewrite `--name=value` into `["--name", "value"]` for every flag that takes a value.
  *
- * A boolean flag with `=` is an error rather than a guess: accepting `--no-sandbox=true` invites
+ * A built-in boolean flag with `=` is an error rather than a guess: accepting `--no-sandbox=true` invites
  * `--no-sandbox=false`, which the parser has no way to express, and quietly reading it as "on" would
  * be exactly the class of bug #2469 reports. Unknown names are left intact so the unknown-flag path
  * can report the token as the user wrote it.
+ * Extension boolean flags accept explicit true or false values through their runtime map.
  *
  * Short forms are untouched: no shell convention makes `-p=x` mean `-p x`.
  */
@@ -223,7 +226,11 @@ export function normalizeFlagTokens(args: readonly string[], extensionFlags?: Ex
 
 		const extension = extensionFlags?.get(name);
 		if (extension) {
-			normalized.push(`--${name}`, value);
+			if (extension.type === "boolean") {
+				normalized.push(arg);
+			} else {
+				normalized.push(`--${name}`, value);
+			}
 			continue;
 		}
 

package/src/cli/plugin-cli.ts

@@ -425,6 +425,17 @@ async function handleInstall(
 		}
 
 		if (target.type === "marketplace") {
+			if (flags.dryRun) {
+				const preview = {
+					action: "install",
+					target: `${target.name}@${target.marketplace}`,
+					scope: flags.scope ?? "user",
+					dryRun: true,
+				};
+				if (flags.json) console.log(JSON.stringify(preview, null, 2));
+				else console.log(chalk.dim(`[dry-run] Would install ${preview.target} (${preview.scope})`));
+				continue;
+			}
 			try {
 				const entry = await mktMgr.installPlugin(target.name, target.marketplace, {
 					force: flags.force,

package/src/cli/sandbox-check.ts

@@ -6,10 +6,17 @@ import { executeShell, fencePermits } from "@f5-sales-demo/pi-natives";
 import { isEnoent } from "@f5-sales-demo/pi-utils";
 import { Settings } from "../config/settings";
 import { fenceForNative } from "../exec/bash-executor";
-import { buildContainmentFence, type ContainmentFence, containmentStatus, fenceVerdict } from "../sandbox/containment";
+import {
+	buildContainmentFence,
+	type ContainmentFence,
+	containmentStatus,
+	fenceVerdict,
+	seatbeltFenceVerdict,
+} from "../sandbox/containment";
 import { evaluateToolCall } from "../sandbox/enforce";
 import {
 	SANDBOX_CHECK_NAMED_SIBLING_ENV,
+	SANDBOX_CHECK_NAMED_SIBLING_EXPECTATION_ENV,
 	SANDBOX_OPERATOR_HOME_ENV,
 	SANDBOX_SESSION_ROOT_ENV,
 	sandboxCheckSiblingRoot,
@@ -74,6 +81,13 @@ function sanitizeDetail(value: string, redactions: readonly Redaction[]): string
 	return sanitized.length > 500 ? `${sanitized.slice(0, 497)}...` : sanitized;
 }
 
+function inheritedNamedSiblingDenied(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	if (value === "denied") return true;
+	if (value === "allowed") return false;
+	throw new Error(`invalid ${SANDBOX_CHECK_NAMED_SIBLING_EXPECTATION_ENV}: expected "allowed" or "denied"`);
+}
+
 function errnoFromOutput(output: string): string {
 	if (/operation not permitted/iu.test(output)) return "EPERM";
 	if (/permission denied/iu.test(output)) return "EACCES";
@@ -210,6 +224,10 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 		const inheritedHome = process.env[SANDBOX_OPERATOR_HOME_ENV];
 		const inheritedSibling = process.env[SANDBOX_CHECK_NAMED_SIBLING_ENV];
 		const inheritedProfile = inheritedWorkspace !== undefined;
+		const inheritedSiblingDenied =
+			inheritedProfile && inheritedSibling !== undefined
+				? inheritedNamedSiblingDenied(process.env[SANDBOX_CHECK_NAMED_SIBLING_EXPECTATION_ENV])
+				: undefined;
 		const workspaceInput = inheritedWorkspace ?? process.cwd();
 		const homeInput = inheritedHome ?? os.homedir();
 		redactions.push([workspaceInput, "<workspace>"], [homeInput, "<operator-home>"]);
@@ -462,7 +480,7 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 			);
 		});
 
-		await check("named sibling remains reachable", async () => {
+		await check("named sibling follows the active boundary", async () => {
 			const displayPath = "<session-parent>/<synthetic-sibling>";
 			let liveSibling = inheritedSibling;
 			if (liveSibling === undefined) {
@@ -480,13 +498,24 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 					return exceptionOutcome("create named sibling fixture", displayPath, error, redactions);
 				}
 			}
+			const seatbeltDeniesSibling =
+				inheritedSiblingDenied ??
+				(backend.backend === "seatbelt" && seatbeltFenceVerdict(liveFence, liveSibling, "read") === "deny");
 			const result = await shellProbe(
-				'test "$(cat named.txt)" = sibling',
-				liveSibling,
-				undefined,
+				`cd ${quote(liveSibling)} && test "$(cat named.txt)" = sibling`,
+				liveWorkspace,
+				inheritedProfile ? undefined : liveFence,
 				abortController.signal,
 			);
-			return shellOutcome(result, true, "live profile must allow a named sibling read", displayPath, redactions);
+			return shellOutcome(
+				result,
+				!seatbeltDeniesSibling,
+				seatbeltDeniesSibling
+					? "Seatbelt must deny a named sibling outside the workspace"
+					: "live profile must allow a named sibling read",
+				displayPath,
+				redactions,
+			);
 		});
 
 		if (backend.osEnforced) {

package/src/commands/launch.ts

@@ -4,7 +4,6 @@
 
 import { APP_NAME } from "@f5-sales-demo/pi-utils";
 import { Args, Command } from "@f5-sales-demo/pi-utils/cli";
-import { parseArgs } from "../cli/args";
 import { buildCliFlags } from "../cli/flag-spec";
 import { runRootCommand } from "../main";
 
@@ -36,7 +35,6 @@ export default class Index extends Command {
 	static strict = false;
 
 	async run(): Promise<void> {
-		const parsed = parseArgs(this.argv);
-		await runRootCommand(parsed, this.argv);
+		await runRootCommand(this.argv);
 	}
 }

package/src/config/model-registry.ts

@@ -187,6 +187,8 @@ const ThinkingControlModeSchema = Type.Union([
 const ModelThinkingSchema = Type.Object({
 	minLevel: EffortSchema,
 	maxLevel: EffortSchema,
+	defaultLevel: Type.Optional(EffortSchema),
+	canDisable: Type.Optional(Type.Boolean()),
 	mode: ThinkingControlModeSchema,
 });
 

package/src/discovery/helpers.ts

@@ -843,12 +843,13 @@ export async function listXcshPluginRoots(
 		roots.push(...projectRoots, ...deduped);
 	}
 
-	// Merge --plugin-dir roots (highest precedence) on every fresh load
+	// Merge --plugin-dir roots (highest precedence) on every fresh load. Local roots use
+	// an artificial marketplace ID, so identity must be matched by manifest plugin name;
+	// comparing full IDs would leave the installed copy active beside the candidate.
 	if (injectedPluginDirRoots.length > 0) {
-		const injectedIds = new Set(injectedPluginDirRoots.map(r => r.id));
-		const filtered = roots.filter(r => !injectedIds.has(r.id));
+		const merged = prioritizeInjectedPluginRoots(roots, injectedPluginDirRoots);
 		roots.length = 0;
-		roots.push(...injectedPluginDirRoots, ...filtered);
+		roots.push(...merged);
 	}
 
 	const result = { roots, warnings };
@@ -856,6 +857,19 @@ export async function listXcshPluginRoots(
 	return result;
 }
 
+export function prioritizeInjectedPluginRoots(
+	installed: XcshPluginRoot[],
+	injected: XcshPluginRoot[],
+): XcshPluginRoot[] {
+	const seen = new Set<string>();
+	const winners = injected.filter(root => {
+		if (seen.has(root.plugin)) return false;
+		seen.add(root.plugin);
+		return true;
+	});
+	return [...winners, ...installed.filter(root => !seen.has(root.plugin))];
+}
+
 export interface XcshPluginSummary {
 	/** Registry id (root.plugin) — the key the `xcsh://plugin/<id>` resolver matches on. */
 	id: string;

package/src/exec/bash-executor.ts

@@ -24,6 +24,7 @@ export function fenceForNative(fence: ContainmentFence | undefined) {
 		allowReadOnly: [...fence.allowReadOnly],
 		allowWriteOnly: [...fence.allowWriteOnly],
 		deny: [...fence.deny],
+		denyOnSeatbelt: [...fence.denyOnSeatbelt],
 		denyEnumerate: [...fence.denyEnumerate],
 	};
 }

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

@@ -171,7 +171,7 @@ function renderContainment(containment: ContainmentStatus | null): string {
 	if (!containment) return "";
 	// `landlock` is derived rather than another field on the status, because the template needs a
 	// boolean and Handlebars cannot compare strings. It gates the Linux-only costs — unlistable split
-	// directories, no setuid, no interactive terminal — which are true of that backend and no other.
+	// directories and no setuid — which are true of that backend and no other.
 	return prompt.render(containmentTemplate, {
 		containment: { ...containment, landlock: containment.backend === "landlock" },
 	});

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "21.0.0",
-	"commit": "7402d0fe1d43a25000908463ed254d54c71d0b6b",
-	"shortCommit": "7402d0f",
+	"version": "21.2.0",
+	"commit": "d217f62f68fae54fe18d88c7d90a8f7dc4703c0d",
+	"shortCommit": "d217f62",
 	"branch": "main",
-	"tag": "v21.0.0",
-	"commitDate": "2026-08-28T10:34:07+00:00",
-	"buildDate": "2026-08-28T11:01:38.586Z",
+	"tag": "v21.2.0",
+	"commitDate": "2026-08-30T03:18:04+00:00",
+	"buildDate": "2026-08-30T03:46:25.618Z",
 	"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/7402d0fe1d43a25000908463ed254d54c71d0b6b",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.0.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/d217f62f68fae54fe18d88c7d90a8f7dc4703c0d",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.2.0"
 };

package/src/internal-urls/console-resolve.ts

@@ -121,10 +121,10 @@ function renderResource(resource: string, catalog: ConsoleCatalogData, fieldMeta
 	const doc = (parseYaml(raw) ?? {}) as Record<string, unknown>;
 	const console_ = (doc.console ?? {}) as Record<string, unknown>;
 	const lines = [`# ${(doc.label as string | undefined) ?? key}`, ""];
-	if (console_.route_pattern) {
-		const fullRoute = console_.route_prefix
-			? `${console_.route_prefix}${console_.route_pattern}`
-			: console_.route_pattern;
+	const routePattern = typeof console_.route_pattern === "string" ? console_.route_pattern : undefined;
+	if (routePattern) {
+		const routePrefix = typeof console_.route_prefix === "string" ? console_.route_prefix : undefined;
+		const fullRoute = routePrefix ? `${routePrefix}${routePattern}` : routePattern;
 		lines.push(`**Route:** \`${fullRoute}\``, "");
 	}
 	if (Array.isArray(console_.menu_path)) lines.push(`**Menu:** ${(console_.menu_path as string[]).join(" › ")}`, "");
@@ -155,8 +155,9 @@ function renderWorkflow(resource: string, operation: string, catalog: ConsoleCat
 	for (const s of steps) {
 		const sel = s.selector ? ` \`${s.selector}\`` : "";
 		const val = s.value != null ? ` = ${JSON.stringify(s.value)}` : "";
+		const action = typeof s.action === "string" ? s.action : "unknown";
 		lines.push(
-			`1. **${s.action}**${sel}${val} — ${(s.description as string | undefined) ?? (s.id as string | undefined) ?? ""}`,
+			`1. **${action}**${sel}${val} — ${(s.description as string | undefined) ?? (s.id as string | undefined) ?? ""}`,
 		);
 	}
 	return `${lines.join("\n")}\n`;

package/src/internal-urls/extension-tools.generated.ts

@@ -0,0 +1,4 @@
+// Auto-generated by scripts/generate-extension-capabilities.ts - DO NOT EDIT
+// Source: src/browser/capabilities.json (the Chrome extension's published contract).
+
+export const EXTENSION_TOOL_REFERENCE = "# Chrome Extension Tool Signatures\n\nGenerated from extension capability contract `2.1.0`.\n\n## annotation\n\n### `annotate`\n\nDraw an overlay annotation (fingerprint/highlight). No-op unless explain mode is on.\n\n- Parameters: `{\"properties\":{\"h\":{\"type\":\"number\"},\"kind\":{\"type\":\"string\"},\"ref\":{\"type\":\"string\"},\"w\":{\"type\":\"number\"},\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"}},\"required\":[\"kind\"],\"type\":\"object\"}`\n- Semantic flags: `{\"requiresExplainMode\":true}`\n\n### `set_explain_mode`\n\nEnter/leave explain mode — the gate for all on-page annotation overlays.\n\n- Parameters: `{\"properties\":{\"enabled\":{\"type\":\"boolean\"}},\"type\":\"object\"}`\n- Semantic flags: `{}`\n\n## interaction\n\n### `click`\n\nDeterministic click of an AX-ref element (layout-engine coords + hit-test).\n\n- Parameters: `{\"properties\":{\"ref\":{\"type\":\"string\"}},\"required\":[\"ref\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `click_element`\n\nClick the element returned by a JS expression (polls; occlusion-safe).\n\n- Parameters: `{\"properties\":{\"js\":{\"type\":\"string\"},\"wait_ms\":{\"type\":\"number\"}},\"required\":[\"js\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `click_xy`\n\nTrusted click at explicit viewport coordinates.\n\n- Parameters: `{\"properties\":{\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"}},\"required\":[\"x\",\"y\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `file_upload`\n\nUpload files (base64 data URIs) to a file input by AX ref.\n\n- Parameters: `{\"properties\":{\"files\":{\"items\":{\"type\":\"string\"},\"type\":\"array\"},\"ref\":{\"type\":\"string\"}},\"required\":[\"ref\",\"files\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `form_input`\n\nSet a form field value by AX ref.\n\n- Parameters: `{\"properties\":{\"ref\":{\"type\":\"string\"},\"value\":{\"type\":\"string\"}},\"required\":[\"ref\",\"value\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `key_press`\n\nDispatch a key press.\n\n- Parameters: `{\"properties\":{\"key\":{\"type\":\"string\"}},\"required\":[\"key\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `label_select`\n\nType into a CDK-portal typeahead and click the matching option.\n\n- Parameters: `{\"properties\":{\"label_value\":{\"type\":\"string\"},\"selector\":{\"type\":\"string\"},\"value\":{\"type\":\"string\"},\"wait_ms\":{\"type\":\"number\"}},\"required\":[\"selector\",\"value\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `select_option`\n\nSelect an option in a native <select> by AX ref.\n\n- Parameters: `{\"properties\":{\"ref\":{\"type\":\"string\"},\"value\":{\"type\":\"string\"}},\"required\":[\"ref\",\"value\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `type_text`\n\nType text into the focused element (trusted input).\n\n- Parameters: `{\"properties\":{\"text\":{\"type\":\"string\"}},\"required\":[\"text\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n## meta\n\n### `capabilities`\n\nReturn this self-describing capability manifest (tools + features + versions).\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `debug_exec`\n\nDiagnostic: probe in-page bridge availability.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `detach`\n\nDetach the debugger from the target tab.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `ping`\n\nLiveness check; returns { ok, version }.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `reload`\n\nReload the extension (re-reads dist/ from disk).\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `set_bridge_port`\n\nSet the WebSocket bridge port (persists across reload; enables multi-session on different ports).\n\n- Parameters: `{\"properties\":{\"port\":{\"type\":\"number\"}},\"required\":[\"port\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n## navigation\n\n### `navigate`\n\nNavigate the console tab to a scoped https URL.\n\n- Parameters: `{\"properties\":{\"url\":{\"type\":\"string\"}},\"required\":[\"url\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `resize_window`\n\nResize the browser window.\n\n- Parameters: `{\"properties\":{\"height\":{\"type\":\"number\"},\"width\":{\"type\":\"number\"}},\"required\":[\"width\",\"height\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `scroll_to`\n\nScroll an AX-ref element into view.\n\n- Parameters: `{\"properties\":{\"ref\":{\"type\":\"string\"}},\"required\":[\"ref\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `tabs_close`\n\nClose a tab by id.\n\n- Parameters: `{\"properties\":{\"tabId\":{\"type\":\"number\"}},\"required\":[\"tabId\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `tabs_create`\n\nOpen a new tab at a scoped URL.\n\n- Parameters: `{\"properties\":{\"url\":{\"type\":\"string\"}},\"required\":[\"url\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `tabs_list`\n\nList scoped console tabs.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{}`\n\n## read\n\n### `assert_text`\n\nAssert an element contains expected text.\n\n- Parameters: `{\"properties\":{\"context\":{\"type\":\"string\"},\"expected\":{\"type\":\"string\"},\"selector\":{\"type\":\"string\"}},\"required\":[\"selector\",\"expected\"],\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `diag_activation`\n\nDiagnostic: per-gate tab-activation readiness timings (bridge/worker/page), cold/warm.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{}`\n\n### `diag_bridges`\n\nList discovered xcsh bridge health without tenant, environment, or session identifiers.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{}`\n\n### `diag_suspension`\n\nDiagnostic: SW-lifecycle event buffer + suspension summary (Phase 0a).\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{}`\n\n### `diag_ttft`\n\nDiagnostic: init→first-token timeline (per-stage ms, total, dominant, cold/warm).\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{}`\n\n### `find`\n\nFind AX nodes matching a locator.\n\n- Parameters: `{\"properties\":{\"selector\":{\"type\":\"string\"}},\"required\":[\"selector\"],\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `get_page_context`\n\nReturn a snapshot of the active console page (url, AX tree, captured XC API body) for chat grounding.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `get_page_text`\n\nReturn the page text.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `query_dom`\n\nDirect DOM.querySelector at wire speed — bypasses Runtime.evaluate for simple CSS selectors.\n\n- Parameters: `{\"properties\":{\"selector\":{\"type\":\"string\"}},\"required\":[\"selector\"],\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `read_ax`\n\nRead the accessibility tree of the page.\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `read_console`\n\nRead buffered console messages, optionally filtered by pattern.\n\n- Parameters: `{\"properties\":{\"pattern\":{\"type\":\"string\"}},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `read_network`\n\nRead buffered network events, optionally filtered by pattern.\n\n- Parameters: `{\"properties\":{\"pattern\":{\"type\":\"string\"}},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `screenshot`\n\nCapture a screenshot (base64 PNG).\n\n- Parameters: `{\"properties\":{},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `wait_for`\n\nWait for an AX node matching a locator to appear.\n\n- Parameters: `{\"properties\":{\"context\":{\"type\":\"string\"},\"selector\":{\"type\":\"string\"},\"timeoutMs\":{\"type\":\"number\"}},\"required\":[\"selector\"],\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n### `wait_for_api_response`\n\nWait for a network response whose URL matches a pattern.\n\n- Parameters: `{\"properties\":{\"pattern\":{\"type\":\"string\"},\"timeout_ms\":{\"type\":\"number\"}},\"type\":\"object\"}`\n- Semantic flags: `{\"readOnly\":true}`\n\n## script\n\n### `browser_batch`\n\nRun a batch of { tool, params } actions in sequence.\n\n- Parameters: `{\"properties\":{\"actions\":{\"items\":{\"properties\":{\"params\":{},\"tool\":{\"type\":\"string\"}},\"required\":[\"tool\"],\"type\":\"object\"},\"type\":\"array\"}},\"required\":[\"actions\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n\n### `javascript_tool`\n\nEvaluate arbitrary JS in the page (length-capped).\n\n- Parameters: `{\"properties\":{\"code\":{\"type\":\"string\"}},\"required\":[\"code\"],\"type\":\"object\"}`\n- Semantic flags: `{\"mutates\":true}`\n";