@f5xc-salesdemos/xcsh 18.19.2 → 18.20.0

package/package.json

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

package/src/capability/skill.ts

@@ -14,6 +14,7 @@ export interface SkillFrontmatter {
 	description?: string;
 	globs?: string[];
 	alwaysApply?: boolean;
+	contexts?: string[];
 	[key: string]: unknown;
 }
 

package/src/extensibility/skills.ts

@@ -14,6 +14,7 @@ export interface Skill {
 	filePath: string;
 	baseDir: string;
 	source: string;
+	contexts?: string[];
 	/** Source metadata for display */
 	_source?: SourceMeta;
 }
@@ -56,6 +57,9 @@ export async function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Prom
 			filePath: capSkill.path,
 			baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
 			source: options.source,
+			contexts: Array.isArray(capSkill.frontmatter?.contexts)
+				? (capSkill.frontmatter.contexts as string[])
+				: undefined,
 			_source: capSkill._source,
 		})),
 		warnings: (result.warnings ?? []).map(message => ({ skillPath: options.dir, message })),
@@ -170,6 +174,9 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 				filePath: capSkill.path,
 				baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
 				source: `${capSkill._source.provider}:${capSkill.level}`,
+				contexts: Array.isArray(capSkill.frontmatter?.contexts)
+					? (capSkill.frontmatter.contexts as string[])
+					: undefined,
 				_source: capSkill._source,
 			});
 			realPathSet.add(resolvedPath);
@@ -206,6 +213,9 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 					filePath: capSkill.path,
 					baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
 					source: "custom:user",
+					contexts: Array.isArray(capSkill.frontmatter?.contexts)
+						? (capSkill.frontmatter.contexts as string[])
+						: undefined,
 					_source: { ...capSkill._source, providerName: "Custom" },
 				},
 				path: capSkill.path,
@@ -250,3 +260,9 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		warnings: [...(result.warnings ?? []).map(w => ({ skillPath: "", message: w })), ...collisionWarnings],
 	};
 }
+
+export function isApplicableToContext(skill: Skill, contextName?: string): boolean {
+	if (!skill.contexts || skill.contexts.length === 0) return true;
+	if (!contextName) return true;
+	return skill.contexts.includes(contextName);
+}

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.19.2",
-	"commit": "aadf3b16536d2269c1e1ff2ee1aefa406c1f4ecc",
-	"shortCommit": "aadf3b1",
+	"version": "18.20.0",
+	"commit": "6feb4da2091180b8eb6488f3991608b55ce3e6a8",
+	"shortCommit": "6feb4da",
 	"branch": "main",
-	"tag": "v18.19.2",
-	"commitDate": "2026-04-27T21:44:40Z",
-	"buildDate": "2026-04-27T22:06:55.819Z",
+	"tag": "v18.20.0",
+	"commitDate": "2026-04-28T04:58:55Z",
+	"buildDate": "2026-04-28T05:21:14.340Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/aadf3b16536d2269c1e1ff2ee1aefa406c1f4ecc",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.19.2"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/6feb4da2091180b8eb6488f3991608b55ce3e6a8",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.20.0"
 };

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

@@ -39,6 +39,9 @@ Credential source: {{context.credentialSource}}.
 Auth status: {{context.authStatus}}.
 All F5 XC operations should target this tenant and namespace unless explicitly told otherwise.
 {{/if}}
+{{#if knowledgeTopics}}
+Available F5 XC documentation topics: {{knowledgeTopics}}.
+{{/if}}
 {{#if skills.length}}
 Skills are specialized knowledge.
 You **MUST** scan descriptions for your task domain.

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

@@ -143,6 +143,10 @@ Auth status: {{context.authStatus}}.
 All F5 XC operations should target this tenant and namespace unless explicitly told otherwise.
 {{/if}}
 
+{{#if knowledgeTopics}}
+Available F5 XC documentation topics: {{knowledgeTopics}}.
+{{/if}}
+
 {{#if contextFiles.length}}
 <context>
 Context files below **MUST** be followed for all tasks:

package/src/sdk.ts

@@ -738,6 +738,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	// Capture ContextService reference for sync consumers (e.g., InternalDocsProtocolHandler's
 	// getContextStatus getter below). Null when ContextService isn't available (SDK consumers, tests).
 	let contextServiceRef: typeof import("./services/f5xc-context").ContextService | null = null;
+	let knowledgeServiceRef: typeof import("./services/f5xc-knowledge").KnowledgeService | null = null;
 
 	// Capture ContextService reference for sync consumers (rebuildSystemPrompt context resolution,
 	// InternalDocsProtocolHandler getContextStatus). The context-change listener itself is
@@ -749,6 +750,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	} catch {
 		// ContextService not available (SDK consumers, tests). Skip.
 	}
+	try {
+		const { KnowledgeService } = await import("./services/f5xc-knowledge");
+		const { getF5XCConfigDir } = await import("@f5xc-salesdemos/pi-utils");
+		knowledgeServiceRef = KnowledgeService;
+		if (!KnowledgeService._hasInstance()) {
+			KnowledgeService.init(getF5XCConfigDir());
+			KnowledgeService.instance.loadCache();
+		}
+	} catch {
+		// KnowledgeService not available — skip.
+	}
 
 	// Check if session has existing data to restore
 	const existingSession = logger.time("loadSessionContext", () =>
@@ -1370,6 +1382,24 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				// ContextService not available or not initialized — leave contextForPrompt undefined.
 			}
 
+			let knowledgeTopics: string | undefined;
+			try {
+				if (knowledgeServiceRef) {
+					const svc = knowledgeServiceRef.instance;
+					const cached = svc.getIndex();
+					if (cached && cached.products.length > 0) {
+						knowledgeTopics = cached.products
+							.map(p => p.name)
+							.sort()
+							.join(", ");
+					}
+					// Fire-and-forget background refresh when TTL is expired — never blocks the prompt.
+					void svc.getOrRefreshIndex();
+				}
+			} catch {
+				// KnowledgeService not available — leave undefined.
+			}
+
 			// Build combined append prompt: memory instructions + MCP server instructions
 			const serverInstructions = mcpManager?.getServerInstructions();
 			let appendPrompt: string | undefined = memoryInstructions ?? undefined;
@@ -1406,6 +1436,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				eagerTasks,
 				secretsEnabled,
 				context: contextForPrompt,
+				knowledgeTopics,
 			});
 
 			if (options.systemPrompt === undefined) {
@@ -1430,6 +1461,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					eagerTasks,
 					secretsEnabled,
 					context: contextForPrompt,
+					knowledgeTopics,
 				});
 			}
 			return options.systemPrompt(defaultPrompt);

package/src/services/f5xc-knowledge.ts

@@ -0,0 +1,177 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { logger } from "@f5xc-salesdemos/pi-utils";
+
+export interface LlmsProduct {
+	name: string;
+	description: string;
+	url: string;
+}
+
+export interface LlmsIndex {
+	title: string;
+	description: string;
+	products: LlmsProduct[];
+	fetchedAt: string;
+}
+
+const INFRASTRUCTURE_SLUGS = new Set([
+	"docs-builder",
+	"docs-theme",
+	"docs-icons",
+	"devcontainer",
+	"xcsh",
+	"docs",
+	"cdn-simulator",
+	"origin-server",
+]);
+
+const ENTRY_PATTERN = /^- \[([^\]]+)\]\(([^)]+)\):\s*(.+)$/;
+
+function extractSlug(url: string): string | null {
+	try {
+		const pathname = new URL(url).pathname;
+		const segments = pathname.split("/").filter(Boolean);
+		return segments[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+
+export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
+	const lines = content.split("\n");
+	let title = "";
+	let description = "";
+	const products: LlmsProduct[] = [];
+	let inFederatedSites = false;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+
+		if (!title && trimmed.startsWith("# ")) {
+			title = trimmed.slice(2).trim();
+			continue;
+		}
+
+		if (!description && trimmed.startsWith("> ")) {
+			description = trimmed.slice(2).trim();
+			continue;
+		}
+
+		if (trimmed.startsWith("## ")) {
+			inFederatedSites = trimmed === "## Federated Sites";
+			continue;
+		}
+
+		if (!inFederatedSites) continue;
+
+		const match = ENTRY_PATTERN.exec(trimmed);
+		if (!match) continue;
+
+		const [, name, url, desc] = match;
+		const slug = extractSlug(url);
+		if (slug && INFRASTRUCTURE_SLUGS.has(slug)) continue;
+
+		products.push({ name, description: desc, url });
+	}
+
+	return {
+		title,
+		description,
+		products,
+		fetchedAt: (now ?? new Date()).toISOString(),
+	};
+}
+
+const ROOT_LLMS_URL = "https://f5xc-salesdemos.github.io/docs/llms.txt";
+const DEFAULT_TTL_MS = 3_600_000;
+
+export class KnowledgeService {
+	static #instance: KnowledgeService | null = null;
+
+	#configDir: string;
+	#index: LlmsIndex | null = null;
+
+	private constructor(configDir: string) {
+		this.#configDir = configDir;
+	}
+
+	static init(configDir: string): KnowledgeService {
+		KnowledgeService.#instance = new KnowledgeService(configDir);
+		return KnowledgeService.#instance;
+	}
+
+	static get instance(): KnowledgeService {
+		if (!KnowledgeService.#instance) {
+			throw new Error("KnowledgeService not initialized. Call KnowledgeService.init() first.");
+		}
+		return KnowledgeService.#instance;
+	}
+
+	static _resetForTest(): void {
+		KnowledgeService.#instance = null;
+	}
+
+	static _hasInstance(): boolean {
+		return KnowledgeService.#instance !== null;
+	}
+
+	get cachePath(): string {
+		return path.join(this.#configDir, "knowledge-cache.json");
+	}
+
+	loadCache(): void {
+		try {
+			if (!fs.existsSync(this.cachePath)) return;
+			const raw = fs.readFileSync(this.cachePath, "utf-8");
+			this.#index = JSON.parse(raw) as LlmsIndex;
+		} catch {
+			this.#index = null;
+		}
+	}
+
+	saveCache(index: LlmsIndex): void {
+		try {
+			fs.mkdirSync(this.#configDir, { recursive: true });
+			fs.writeFileSync(this.cachePath, JSON.stringify(index, null, 2));
+		} catch (err) {
+			logger.debug("F5XC knowledge cache write failed", { error: String(err) });
+		}
+	}
+
+	getIndex(): LlmsIndex | null {
+		return this.#index;
+	}
+
+	async refreshIndex(): Promise<LlmsIndex> {
+		const response = await fetch(ROOT_LLMS_URL, {
+			signal: AbortSignal.timeout(10_000),
+		});
+		if (!response.ok) {
+			throw new Error(`Failed to fetch llms.txt: HTTP ${response.status}`);
+		}
+		const content = await response.text();
+		const index = parseLlmsTxt(content);
+		this.#index = index;
+		this.saveCache(index);
+		return index;
+	}
+
+	async getOrRefreshIndex(ttlMs = DEFAULT_TTL_MS): Promise<LlmsIndex | null> {
+		if (this.#index) {
+			const age = Date.now() - new Date(this.#index.fetchedAt).getTime();
+			if (age < ttlMs) return this.#index;
+		}
+		try {
+			return await this.refreshIndex();
+		} catch (err) {
+			logger.debug("F5XC knowledge index refresh failed, using stale cache", { error: String(err) });
+			return this.#index;
+		}
+	}
+
+	getProductNames(): string[] {
+		if (!this.#index) return [];
+		return this.#index.products.map(p => p.name).sort();
+	}
+}

package/src/system-prompt.ts

@@ -12,7 +12,7 @@ import { contextFileCapability } from "./capability/context-file";
 import { systemPromptCapability } from "./capability/system-prompt";
 import type { SkillsSettings } from "./config/settings";
 import { type ContextFile, loadCapability, type SystemPrompt as SystemPromptFile } from "./discovery";
-import { loadSkills, type Skill } from "./extensibility/skills";
+import { isApplicableToContext, loadSkills, type Skill } from "./extensibility/skills";
 import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md" with { type: "text" };
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
 
@@ -441,6 +441,7 @@ export interface BuildSystemPromptOptions {
 		credentialSource: string;
 		authStatus: string;
 	};
+	knowledgeTopics?: string;
 }
 
 /** Build the system prompt with tools, guidelines, and context */
@@ -584,6 +585,11 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	const hasRead = tools?.has("read");
 	const filteredSkills = hasRead ? skills : [];
 
+	// contexts values match the tenant label derived from the API URL hostname (first DNS label).
+	// Example: https://acme.console.ves.volterra.io → tenant "acme" → contexts: ["acme"]
+	const contextName = context?.tenant;
+	const contextFilteredSkills = filteredSkills.filter(s => isApplicableToContext(s, contextName));
+
 	const effectiveSystemPromptCustomization = dedupePromptSource(systemPromptCustomization, [
 		resolvedCustomPrompt,
 		resolvedAppendPrompt,
@@ -602,7 +608,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		environment,
 		contextFiles,
 		agentsMdSearch,
-		skills: filteredSkills,
+		skills: contextFilteredSkills,
 		rules: rules ?? [],
 		alwaysApplyRules: injectedAlwaysApplyRules,
 		date,
@@ -616,6 +622,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		eagerTasks,
 		secretsEnabled,
 		context,
+		knowledgeTopics: options.knowledgeTopics,
 	};
 	let rendered = prompt.render(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);