@f5xc-salesdemos/xcsh 18.30.1 → 18.30.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.30.1",
+	"version": "18.30.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -48,12 +48,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.30.1",
-		"@f5xc-salesdemos/pi-agent-core": "18.30.1",
-		"@f5xc-salesdemos/pi-ai": "18.30.1",
-		"@f5xc-salesdemos/pi-natives": "18.30.1",
-		"@f5xc-salesdemos/pi-tui": "18.30.1",
-		"@f5xc-salesdemos/pi-utils": "18.30.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.30.2",
+		"@f5xc-salesdemos/pi-agent-core": "18.30.2",
+		"@f5xc-salesdemos/pi-ai": "18.30.2",
+		"@f5xc-salesdemos/pi-natives": "18.30.2",
+		"@f5xc-salesdemos/pi-tui": "18.30.2",
+		"@f5xc-salesdemos/pi-utils": "18.30.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/scripts/generate-api-spec-index.ts

@@ -1,10 +1,42 @@
 #!/usr/bin/env bun
 
-import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { gzipSync } from "node:zlib";
+import { $ } from "bun";
+
+interface SpecPathOperation {
+	operationId?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * Finds the operationId schema components (e.g., 'dns_zone', 'views.forward_proxy_policy')
+ * that correspond to a given resource name by matching path segments.
+ */
+function findResourceSchemaComponents(
+	resourceName: string,
+	paths: Record<string, Record<string, SpecPathOperation>>,
+): string[] {
+	const name = resourceName.replace(/-/g, "_");
+	const plural = name.endsWith("s") ? name : `${name}s`;
+	const found = new Set<string>();
+
+	for (const [pathKey, methods] of Object.entries(paths)) {
+		const segments = pathKey.split("/");
+		if (!segments.some(s => s === name || s === plural)) continue;
+
+		for (const op of Object.values(methods)) {
+			const opId = op?.operationId;
+			if (!opId) continue;
+			const match = opId.match(/^ves\.io\.schema\.(.+?)\.(?:API|CustomAPI)\./);
+			if (match) found.add(match[1]);
+		}
+	}
+
+	return [...found];
+}
 
 interface IndexEntry {
 	domain: string;
@@ -33,6 +65,7 @@ const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/api-spec-
 
 async function downloadFromRelease(): Promise<string> {
 	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "api-specs-"));
+	downloadedTmpDir = tmpDir;
 	const tag = process.env.API_SPECS_TAG ?? PINNED_TAG;
 	const zipName = `f5xc-api-specs-${tag}.zip`;
 	const downloadUrl = `https://github.com/${REPO}/releases/download/${tag}/${zipName}`;
@@ -49,7 +82,13 @@ async function downloadFromRelease(): Promise<string> {
 
 	const extractDir = path.join(tmpDir, "extracted");
 	fs.mkdirSync(extractDir, { recursive: true });
-	execFileSync("unzip", ["-q", zipPath, "-d", extractDir], { stdio: "inherit" });
+	const result = await $`unzip -q ${zipPath} -d ${extractDir}`.nothrow();
+	if (result.exitCode !== 0) {
+		throw new Error(
+			`Failed to extract ${zipPath}: unzip exited with code ${result.exitCode}.\n` +
+				"Ensure 'unzip' is installed: apt install unzip / brew install unzip",
+		);
+	}
 
 	const domainsDir = path.join(extractDir, "domains");
 	if (fs.existsSync(domainsDir) && fs.existsSync(path.join(extractDir, "index.json"))) {
@@ -75,6 +114,8 @@ async function findSpecsDir(): Promise<string> {
 	return downloadFromRelease();
 }
 
+let downloadedTmpDir: string | null = null;
+
 const specsDir = await findSpecsDir();
 console.log(`Reading specs from: ${specsDir}`);
 
@@ -100,12 +141,18 @@ for (const entry of rawIndex.specifications) {
 	}
 
 	const specContent = fs.readFileSync(specFile, "utf-8");
+	const specJson = JSON.parse(specContent) as {
+		paths?: Record<string, Record<string, SpecPathOperation>>;
+		[k: string]: unknown;
+	};
 	const compressed = gzipSync(Buffer.from(specContent));
 	const b64 = compressed.toString("base64");
 
-	const resources = (entry["x-f5xc-primary-resources"] ?? []).map(
-		r => `\t\t\t{ name: ${JSON.stringify(r.name)}, description: ${JSON.stringify(r.description)} },`,
-	);
+	const resources = (entry["x-f5xc-primary-resources"] ?? []).map(r => {
+		const schemaComponents = findResourceSchemaComponents(r.name, specJson.paths ?? {});
+		const scStr = schemaComponents.length > 0 ? `, schemaComponents: ${JSON.stringify(schemaComponents)}` : "";
+		return `\t\t\t{ name: ${JSON.stringify(r.name)}, description: ${JSON.stringify(r.description)}${scStr} },`;
+	});
 
 	const useCases = entry["x-f5xc-use-cases"];
 	const relatedDomains = entry["x-f5xc-related-domains"];
@@ -163,3 +210,7 @@ const outputSize = (Buffer.byteLength(output) / 1024 / 1024).toFixed(1);
 console.log(
 	`Generated ${path.relative(process.cwd(), outputPath)} (${processedCount} domains, ${skippedCount} skipped, ${outputSize} MB)`,
 );
+
+if (downloadedTmpDir) {
+	fs.rmSync(downloadedTmpDir, { recursive: true, force: true });
+}

package/src/internal-urls/api-spec-resolve.ts

@@ -1,11 +1,23 @@
 import { gunzipSync } from "node:zlib";
 import { LRUCache } from "lru-cache";
-import type { ApiSpecDomainEntry, ApiSpecIndex, OpenAPISpec } from "./api-spec-types";
+import type { ApiSpecDomainEntry, ApiSpecIndex, OpenAPIPathOperation, OpenAPISpec } from "./api-spec-types";
 import type { InternalResource, InternalUrl } from "./types";
 
 const LRU_CAPACITY = 5;
 const SCHEMA_RENDER_MAX_DEPTH = 3;
 
+// Module-level cache for groupPathsBySchema results, keyed by spec identity.
+// Different resolver instances create distinct OpenAPISpec objects so there is no cross-resolver leakage.
+const groupsCache = new WeakMap<OpenAPISpec, Map<string, Record<string, Record<string, OpenAPIPathOperation>>>>();
+
+function getCachedGroups(spec: OpenAPISpec): Map<string, Record<string, Record<string, OpenAPIPathOperation>>> {
+	const cached = groupsCache.get(spec);
+	if (cached) return cached;
+	const groups = groupPathsBySchema(spec);
+	groupsCache.set(spec, groups);
+	return groups;
+}
+
 export interface ApiSpecResolver {
 	resolve(url: InternalUrl): Promise<InternalResource>;
 }
@@ -22,11 +34,16 @@ export function createApiSpecResolver(index: ApiSpecIndex, blobs: Record<string,
 			throw new Error(`No spec blob for domain: ${domain}`);
 		}
 
-		const buffer = Buffer.from(blob, "base64");
-		const decompressed = gunzipSync(buffer);
-		const spec = JSON.parse(decompressed.toString("utf-8")) as OpenAPISpec;
-		cache.set(domain, spec);
-		return spec;
+		try {
+			const buffer = Buffer.from(blob, "base64");
+			const decompressed = gunzipSync(buffer);
+			const spec = JSON.parse(decompressed.toString("utf-8")) as OpenAPISpec;
+			cache.set(domain, spec);
+			return spec;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new Error(`Failed to decompress spec for domain '${domain}': ${message}`);
+		}
 	}
 
 	return {
@@ -43,25 +60,30 @@ export function createApiSpecResolver(index: ApiSpecIndex, blobs: Record<string,
 				return makeResource(url, renderUnknownDomain(domain, index));
 			}
 
-			const resource = url.searchParams.get("resource");
-			const pathFilter = url.searchParams.get("path");
+			try {
+				const resource = url.searchParams.get("resource");
+				const pathFilter = url.searchParams.get("path");
 
-			if (resource) {
-				const spec = decompress(domain);
-				const matchingPaths = filterPathsByResource(spec, resource);
-				if (Object.keys(matchingPaths).length === 0) {
-					return makeResource(url, renderUnknownResource(resource, entry, spec));
+				if (resource) {
+					const spec = decompress(domain);
+					const matchingPaths = filterPathsByResource(spec, resource, entry);
+					if (Object.keys(matchingPaths).length === 0) {
+						return makeResource(url, renderUnknownResource(resource, entry, spec));
+					}
+					return makeResource(url, renderResourceSpec(domain, resource, spec, entry));
+				}
+
+				if (pathFilter) {
+					const spec = decompress(domain);
+					return makeResource(url, renderPathSpec(domain, pathFilter, spec));
 				}
-				return makeResource(url, renderResourceSpec(domain, resource, spec));
-			}
 
-			if (pathFilter) {
 				const spec = decompress(domain);
-				return makeResource(url, renderPathSpec(domain, pathFilter, spec));
+				return makeResource(url, renderDomainDetail(domain, entry, spec));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return makeResource(url, `# Error loading ${domain}\n\n${message}\n`);
 			}
-
-			const spec = decompress(domain);
-			return makeResource(url, renderDomainDetail(domain, entry, spec));
 		},
 	};
 }
@@ -94,20 +116,13 @@ function renderDomainIndex(index: ApiSpecIndex): string {
 }
 
 function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: OpenAPISpec): string {
-	const groups = groupPathsBySchema(spec);
-	const schemaNames = [...groups.keys()].sort();
-
-	const resourceRows = schemaNames.map(s => {
-		const paths = groups.get(s)!;
-		const opCount = Object.values(paths).reduce((n, m) => n + Object.keys(m).length, 0);
-		return `| ${s} | ${opCount} operations |`;
-	});
+	const resourceRows = entry.resources.map(r => `| ${r.name} | ${r.description} |`);
 
 	const operationRows: string[] = [];
 	for (const [pathKey, methods] of Object.entries(spec.paths)) {
 		for (const [method, op] of Object.entries(methods)) {
 			if (typeof op !== "object" || !op) continue;
-			const summary = (op as Record<string, unknown>).summary ?? "";
+			const summary = op.summary ?? "";
 			operationRows.push(`| ${method.toUpperCase()} | ${pathKey} | ${summary} |`);
 		}
 	}
@@ -119,8 +134,8 @@ function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: Ope
 		"",
 		"## Resources",
 		"",
-		"| Resource | Info |",
-		"|----------|------|",
+		"| Resource | Description |",
+		"|----------|-------------|",
 		...resourceRows,
 		"",
 		"## Operations",
@@ -148,13 +163,13 @@ function extractSchemaComponent(operationId: string): string | null {
 	return match ? match[1] : null;
 }
 
-function groupPathsBySchema(spec: OpenAPISpec): Map<string, Record<string, Record<string, unknown>>> {
-	const groups = new Map<string, Record<string, Record<string, unknown>>>();
+function groupPathsBySchema(spec: OpenAPISpec): Map<string, Record<string, Record<string, OpenAPIPathOperation>>> {
+	const groups = new Map<string, Record<string, Record<string, OpenAPIPathOperation>>>();
 
 	for (const [pathKey, methods] of Object.entries(spec.paths)) {
 		for (const [method, op] of Object.entries(methods)) {
 			if (typeof op !== "object" || !op) continue;
-			const opId = (op as Record<string, unknown>).operationId as string | undefined;
+			const opId = op.operationId;
 			if (!opId) continue;
 			const schema = extractSchemaComponent(opId);
 			if (!schema) continue;
@@ -163,22 +178,45 @@ function groupPathsBySchema(spec: OpenAPISpec): Map<string, Record<string, Recor
 			}
 			const group = groups.get(schema)!;
 			if (!group[pathKey]) group[pathKey] = {};
-			group[pathKey][method] = op as Record<string, unknown>;
+			group[pathKey][method] = op;
 		}
 	}
 
 	return groups;
 }
 
-function filterPathsByResource(spec: OpenAPISpec, resource: string): Record<string, Record<string, unknown>> {
-	const groups = groupPathsBySchema(spec);
+function filterPathsByResource(
+	spec: OpenAPISpec,
+	resource: string,
+	entry?: ApiSpecDomainEntry,
+): Record<string, Record<string, OpenAPIPathOperation>> {
+	// Index-guided lookup: use pre-computed schemaComponents from the enriched index
+	if (entry) {
+		const indexedResource = entry.resources.find(r => r.name === resource);
+		if (indexedResource?.schemaComponents?.length) {
+			const groups = getCachedGroups(spec);
+			const result: Record<string, Record<string, OpenAPIPathOperation>> = {};
+			for (const comp of indexedResource.schemaComponents) {
+				const paths = groups.get(comp);
+				if (paths) {
+					for (const [pathKey, methods] of Object.entries(paths)) {
+						if (!result[pathKey]) result[pathKey] = {};
+						Object.assign(result[pathKey], methods);
+					}
+				}
+			}
+			if (Object.keys(result).length > 0) return result;
+		}
+	}
+
+	const groups = getCachedGroups(spec);
 
 	const exactKey = resource.replace(/-/g, "_");
 	if (groups.has(exactKey)) {
 		return groups.get(exactKey)!;
 	}
 
-	const partial = new Map<string, Record<string, Record<string, unknown>>>();
+	const partial = new Map<string, Record<string, Record<string, OpenAPIPathOperation>>>();
 	for (const [schema, paths] of groups) {
 		const schemaEnd = schema.split(".").at(-1) ?? schema;
 		if (
@@ -201,7 +239,7 @@ function filterPathsByResource(spec: OpenAPISpec, resource: string): Record<stri
 	}
 
 	const pluralized = exactKey.endsWith("s") ? exactKey : `${exactKey}s`;
-	const result: Record<string, Record<string, unknown>> = {};
+	const result: Record<string, Record<string, OpenAPIPathOperation>> = {};
 	for (const [pathKey, methods] of Object.entries(spec.paths)) {
 		const segments = pathKey.split("/");
 		if (segments.some(s => s === pluralized || s === exactKey)) {
@@ -211,18 +249,18 @@ function filterPathsByResource(spec: OpenAPISpec, resource: string): Record<stri
 	return result;
 }
 
-function renderResourceSpec(_domain: string, resource: string, spec: OpenAPISpec): string {
-	const matchingPaths = filterPathsByResource(spec, resource);
+function renderResourceSpec(_domain: string, resource: string, spec: OpenAPISpec, entry?: ApiSpecDomainEntry): string {
+	const matchingPaths = filterPathsByResource(spec, resource, entry);
 	const sections = [`# ${resource} — Full API Specification`, ""];
 
 	for (const [pathKey, methods] of Object.entries(matchingPaths)) {
 		for (const [method, op] of Object.entries(methods)) {
 			if (typeof op !== "object" || !op) continue;
-			const operation = op as Record<string, unknown>;
+			const operation = op;
 			sections.push(`## ${method.toUpperCase()} ${pathKey}`, "");
 			if (operation.summary) sections.push(String(operation.summary), "");
 
-			const params = operation.parameters as Array<Record<string, unknown>> | undefined;
+			const params = operation.parameters;
 			if (params?.length) {
 				sections.push("### Parameters", "");
 				sections.push("| Name | In | Required | Type | Description |");
@@ -236,7 +274,7 @@ function renderResourceSpec(_domain: string, resource: string, spec: OpenAPISpec
 				sections.push("");
 			}
 
-			const reqBody = operation.requestBody as Record<string, unknown> | undefined;
+			const reqBody = operation.requestBody;
 			if (reqBody) {
 				sections.push("### Request Body", "");
 				const content = reqBody.content as Record<string, Record<string, unknown>> | undefined;
@@ -247,7 +285,7 @@ function renderResourceSpec(_domain: string, resource: string, spec: OpenAPISpec
 				}
 			}
 
-			const responses = operation.responses as Record<string, Record<string, unknown>> | undefined;
+			const responses = operation.responses;
 			if (responses) {
 				for (const [status, resp] of Object.entries(responses)) {
 					if (typeof resp !== "object" || !resp) continue;
@@ -283,7 +321,7 @@ function renderPathSpec(_domain: string, pathKey: string, spec: OpenAPISpec): st
 
 	for (const [method, op] of Object.entries(methods)) {
 		if (typeof op !== "object" || !op) continue;
-		const operation = op as Record<string, unknown>;
+		const operation = op;
 		sections.push(`## ${method.toUpperCase()}`, "");
 		if (operation.summary) sections.push(String(operation.summary), "");
 	}
@@ -358,7 +396,7 @@ function renderUnknownDomain(requested: string, index: ApiSpecIndex): string {
 }
 
 function renderUnknownResource(requested: string, entry: ApiSpecDomainEntry, spec: OpenAPISpec): string {
-	const groups = groupPathsBySchema(spec);
+	const groups = getCachedGroups(spec);
 	const schemaNames = [...groups.keys()].sort();
 
 	return [

package/src/internal-urls/api-spec-types.ts

@@ -8,6 +8,7 @@
 export interface ApiSpecDomainResource {
 	readonly name: string;
 	readonly description: string;
+	readonly schemaComponents?: readonly string[];
 }
 
 export interface ApiSpecDomainEntry {

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.30.1",
-	"commit": "44f3e8eb67ae0eaa93412d10edd0c3af366f2bd3",
-	"shortCommit": "44f3e8e",
+	"version": "18.30.2",
+	"commit": "25941ca15e065dd3be59c1814a5ff8871b7af373",
+	"shortCommit": "25941ca",
 	"branch": "main",
-	"tag": "v18.30.1",
-	"commitDate": "2026-05-01T05:16:08Z",
-	"buildDate": "2026-05-01T05:42:04.697Z",
+	"tag": "v18.30.2",
+	"commitDate": "2026-05-01T06:03:28Z",
+	"buildDate": "2026-05-01T06:27:47.424Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/44f3e8eb67ae0eaa93412d10edd0c3af366f2bd3",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.30.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/25941ca15e065dd3be59c1814a5ff8871b7af373",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.30.2"
 };

package/src/internal-urls/xcsh-protocol.ts

@@ -28,6 +28,12 @@ const EMPTY_INDEX: ApiSpecIndex = { version: "unknown", timestamp: "", domains:
 
 let _apiSpecCache: { index: ApiSpecIndex; blobs: Record<string, string>; version: string } | null = null;
 
+/**
+ * Lazily loads the generated API spec index. Uses require() instead of
+ * top-level import because the generated file may not exist in all
+ * contexts (tarball install, type-check without build). The try-catch
+ * falls back to an empty index so the handler degrades gracefully.
+ */
 function loadApiSpecs(): { index: ApiSpecIndex; blobs: Record<string, string>; version: string } {
 	if (_apiSpecCache) return _apiSpecCache;
 	try {

package/src/prompts/system/system-prompt.md

@@ -189,12 +189,12 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 - `mcp://<resource-uri>` — MCP resource from a connected server; matched against exact resource URIs first, then RFC 6570 URI templates advertised by connected servers
 - `xcsh://..` — Internal xcsh documentation. **MUST NOT** read unless the user asks about xcsh itself.
   - `xcsh://about` — Identity, version, build fingerprint, architecture, self-improvement. **MUST** read for any question about xcsh before exploring `~/.xcsh/`.
-- `xcsh://api-spec/` — F5 Distributed Cloud API specifications ({{apiSpecDomainCount}} domains, v{{apiSpecVersion}}).
+- `xcsh://api-spec/` — F5 XC API specifications.
   **MUST NOT** read proactively. When the user needs to interact with the F5 XC API:
   1. Read `xcsh://api-spec/` to identify the correct domain
   2. Read `xcsh://api-spec/{domain}` to find the resource and operations
   3. Read `xcsh://api-spec/{domain}?resource={name}` for full endpoint specification
-  Never guess API paths or request schemas — always consult the spec first.
+  Never guess API paths or request schemas.
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
 

package/src/system-prompt.ts

@@ -16,23 +16,6 @@ import { isApplicableToContext, loadSkills, type Skill } from "./extensibility/s
 import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md" with { type: "text" };
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
 
-let _apiSpecMeta: { domainCount: number; version: string } | null = null;
-
-function getApiSpecMeta(): { domainCount: number; version: string } {
-	if (_apiSpecMeta) return _apiSpecMeta;
-	try {
-		// eslint-disable-next-line @typescript-eslint/no-require-imports
-		const mod = require("./internal-urls/api-spec-index.generated");
-		_apiSpecMeta = {
-			domainCount: mod.API_SPEC_INDEX?.domains?.length ?? 0,
-			version: mod.API_SPEC_VERSION ?? "unknown",
-		};
-	} catch {
-		_apiSpecMeta = { domainCount: 0, version: "unknown" };
-	}
-	return _apiSpecMeta;
-}
-
 let _buildMeta: { version: string; repoSlug: string } | null = null;
 
 function getBuildMeta(): { version: string; repoSlug: string } {
@@ -49,15 +32,6 @@ function getBuildMeta(): { version: string; repoSlug: string } {
 	}
 	return _buildMeta;
 }
-
-function apiSpecDomainCount(): number {
-	return getApiSpecMeta().domainCount;
-}
-
-function apiSpecVersion(): string {
-	return getApiSpecMeta().version;
-}
-
 interface AlwaysApplyRule {
 	name: string;
 	content: string;
@@ -677,8 +651,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		secretsEnabled,
 		context,
 		knowledgeTopics: options.knowledgeTopics,
-		apiSpecDomainCount: apiSpecDomainCount(),
-		apiSpecVersion: apiSpecVersion(),
 	};
 	let rendered = prompt.render(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);