@f5-sales-demo/xcsh 19.75.0 → 19.76.0

package/package.json

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

package/src/discovery/helpers.ts

@@ -856,6 +856,67 @@ export async function listXcshPluginRoots(
 	return result;
 }
 
+export interface XcshPluginSummary {
+	/** Registry id (root.plugin) — the key the `xcsh://plugin/<id>` resolver matches on. */
+	id: string;
+	/** Display name from the plugin's own manifest (falls back to the registry id). */
+	name: string;
+	description: string;
+}
+
+/**
+ * Sanitize a manifest/package description for single-line rendering in the system prompt.
+ * Collapses whitespace runs to single spaces, trims, and caps length (appending "…" if truncated).
+ * Defense-in-depth: the value is rendered with `noEscape:true`, so a newline would break the
+ * single-line bullet and an oversized description would bloat the prompt.
+ */
+function sanitizePluginDescription(description: unknown): string {
+	if (typeof description !== "string") return "";
+	const collapsed = description.replace(/\s+/g, " ").trim();
+	return collapsed.length > 300 ? `${collapsed.slice(0, 300)}…` : collapsed;
+}
+
+/** Read a plugin's human name+description from its own manifest. Fail-safe: never throws. */
+export async function readPluginSummary(root: { plugin: string; path: string }): Promise<XcshPluginSummary> {
+	// Precedence mirrors MarketplaceManager#resolvePluginVersion.
+	const candidates: Array<{ rel: string; pick: (m: any) => { name?: string; description?: string } }> = [
+		{ rel: ".xcsh-plugin/plugin.json", pick: m => ({ name: m?.name, description: m?.description }) },
+		{
+			rel: "package.json",
+			pick: m => ({ name: m?.xcsh?.name ?? m?.pi?.name, description: m?.xcsh?.description ?? m?.pi?.description }),
+		},
+	];
+	for (const c of candidates) {
+		try {
+			const m = await Bun.file(path.join(root.path, c.rel)).json();
+			const { name, description } = c.pick(m);
+			if (name || description) {
+				return { id: root.plugin, name: name ?? root.plugin, description: sanitizePluginDescription(description) };
+			}
+		} catch {
+			// try next candidate
+		}
+	}
+	return { id: root.plugin, name: root.plugin, description: "" };
+}
+
+/** All installed plugins as {name, description}, sorted by name, deduped by plugin id. */
+export async function listXcshPluginSummaries(home: string, cwd?: string): Promise<XcshPluginSummary[]> {
+	try {
+		const { roots } = await listXcshPluginRoots(home, cwd);
+		const seen = new Set<string>();
+		const out: XcshPluginSummary[] = [];
+		for (const r of roots) {
+			if (seen.has(r.plugin)) continue;
+			seen.add(r.plugin);
+			out.push(await readPluginSummary(r));
+		}
+		return out.sort((a, b) => a.name.localeCompare(b.name));
+	} catch {
+		return [];
+	}
+}
+
 /**
  * Clear the plugin roots cache (useful for testing or when plugins change).
  */

package/src/discovery/plugin-summaries.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readPluginSummary } from "./helpers";
+
+async function mkRoot(files: Record<string, unknown>): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), "xps-"));
+	for (const [rel, content] of Object.entries(files)) {
+		const p = join(dir, rel);
+		await mkdir(join(p, ".."), { recursive: true });
+		await writeFile(p, JSON.stringify(content));
+	}
+	return dir;
+}
+
+describe("readPluginSummary", () => {
+	test("reads name+description from .xcsh-plugin/plugin.json", async () => {
+		const path = await mkRoot({
+			".xcsh-plugin/plugin.json": { name: "meddpicc", description: "MEDDPICC framework" },
+		});
+		expect(await readPluginSummary({ plugin: "meddpicc", path })).toEqual({
+			id: "meddpicc",
+			name: "meddpicc",
+			description: "MEDDPICC framework",
+		});
+	});
+	test("falls back to package.json xcsh field", async () => {
+		const path = await mkRoot({ "package.json": { xcsh: { name: "foo", description: "Foo tool" } } });
+		expect(await readPluginSummary({ plugin: "foo", path })).toEqual({
+			id: "foo",
+			name: "foo",
+			description: "Foo tool",
+		});
+	});
+	test("falls back to package.json pi field", async () => {
+		const path = await mkRoot({ "package.json": { pi: { name: "legacy", description: "Legacy tool" } } });
+		expect(await readPluginSummary({ plugin: "legacy", path })).toEqual({
+			id: "legacy",
+			name: "legacy",
+			description: "Legacy tool",
+		});
+	});
+	test("no manifest → name from root.plugin, empty description", async () => {
+		const path = await mkRoot({});
+		expect(await readPluginSummary({ plugin: "bare", path })).toEqual({
+			id: "bare",
+			name: "bare",
+			description: "",
+		});
+	});
+	test("manifest without name → falls back to root.plugin", async () => {
+		const path = await mkRoot({ ".xcsh-plugin/plugin.json": { description: "desc only" } });
+		expect(await readPluginSummary({ plugin: "baz", path })).toEqual({
+			id: "baz",
+			name: "baz",
+			description: "desc only",
+		});
+	});
+	test("id is the registry id even when the manifest name differs", async () => {
+		const path = await mkRoot({
+			".xcsh-plugin/plugin.json": { name: "Display Name", description: "mismatched name" },
+		});
+		expect(await readPluginSummary({ plugin: "registry-id", path })).toEqual({
+			id: "registry-id",
+			name: "Display Name",
+			description: "mismatched name",
+		});
+	});
+	test("multi-line / oversized description is collapsed to one line and capped with …", async () => {
+		const longDescription = `line one\nline two\t${"x".repeat(400)}`;
+		const path = await mkRoot({
+			".xcsh-plugin/plugin.json": { name: "big", description: longDescription },
+		});
+		const summary = await readPluginSummary({ plugin: "big", path });
+		expect(summary.id).toBe("big");
+		expect(summary.description).not.toContain("\n");
+		expect(summary.description).not.toContain("\t");
+		expect(summary.description.startsWith("line one line two ")).toBe(true);
+		expect(summary.description.length).toBe(301); // 300 chars + the "…" ellipsis
+		expect(summary.description.endsWith("…")).toBe(true);
+	});
+});

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.75.0",
-	"commit": "ac9635391c489c70d35c68a0e1cacdbae9f7e631",
-	"shortCommit": "ac96353",
+	"version": "19.76.0",
+	"commit": "2e4e3b0d461f6dc353419167c54b0da3c7310765",
+	"shortCommit": "2e4e3b0",
 	"branch": "main",
-	"tag": "v19.75.0",
-	"commitDate": "2026-07-22T13:46:55Z",
-	"buildDate": "2026-07-22T14:09:19.426Z",
+	"tag": "v19.76.0",
+	"commitDate": "2026-07-22T16:43:35Z",
+	"buildDate": "2026-07-22T17:06:30.694Z",
 	"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/ac9635391c489c70d35c68a0e1cacdbae9f7e631",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.75.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/2e4e3b0d461f6dc353419167c54b0da3c7310765",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.76.0"
 };

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

@@ -307,7 +307,10 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
   - `xcsh://console/<resource>/<operation>` — the exact ordered UI steps (selectors) for that operation.
 - `xcsh://extension` — Chrome extension bridge tool API reference: which tool to use (click, typeahead, input, navigation) for each automation task.
 {{#if hasPlugins}}
-Installed plugins expose capabilities, schemas, and executable helpers on demand. Read `xcsh://plugin` to list installed plugins and `xcsh://plugin/<name>` for a plugin's summary and how to go deeper — pull this in only when a task matches a plugin's domain.
+**Installed plugins** expose domain capabilities, schemas, and executable helpers on demand. When a task falls within a plugin's domain, consult that plugin: read `xcsh://plugin/<name>` for its summary, then **run its engine/helpers to produce any computed, scored, ranked, or "what to do next" result** rather than deriving it yourself or reading it from a data file — a plugin's engine is the source of truth, and values already written into an artifact may be stale or wrong:
+{{#each plugins}}
+- **{{name}}** — {{description}} → `xcsh://plugin/{{id}}`
+{{/each}}
 {{/if}}
 
 ### Presentation profile

package/src/system-prompt.plugin-pointer.test.ts

@@ -3,36 +3,54 @@ import * as path from "node:path";
 import { prompt } from "@f5-sales-demo/pi-utils";
 import { registerCodingAgentPromptHelpers } from "./config/prompt-templates";
 
-// L0 of the MEDDPICC progressive-hints ladder: a single framework-agnostic line
-// telling the agent that installed plugins expose capabilities/schemas via
-// `xcsh://plugin/<name>`. It is gated on the `hasPlugins` render variable that
-// `buildSystemPrompt` computes from discovered plugin roots.
+// Technique A of the MEDDPICC progressive-hints ladder: a generic, framework-agnostic
+// "Installed Plugins" capability index. When ≥1 plugin is present, the template enumerates
+// each installed plugin by name + own-manifest description + `xcsh://plugin/<name>` pointer,
+// so the agent reliably consults the plugin instead of answering from memory. It is gated on
+// the `hasPlugins` render variable and iterates the `plugins` array that `buildSystemPrompt`
+// computes from discovered plugin summaries.
 //
-// Seam: the Handlebars-compile path (`prompt.render(template, data)`) — the same
-// seam every other conditional-rendering assertion in this package uses. It is
-// deterministic (no dependency on what is installed under the real home dir) and
-// exercises the exact template conditional this task adds. `buildSystemPrompt`
-// resolves plugins from `os.homedir()` and takes no `home` override, so a
-// true-case fixture through it would be non-deterministic.
+// Seam: the Handlebars-compile path (`prompt.render(template, data)`) — the same seam every
+// other conditional-rendering assertion in this package uses. It is deterministic (no
+// dependency on what is installed under the real home dir) and exercises the exact template
+// block this task renders. `buildSystemPrompt` resolves plugins from `os.homedir()` and takes
+// no `home` override, so a true-case fixture through it would be non-deterministic.
 
 const systemPromptPath = path.resolve(import.meta.dir, "prompts/system/system-prompt.md");
 
-describe("L0 plugin-capability pointer", () => {
+describe("Installed Plugins index (technique A)", () => {
 	beforeAll(() => {
 		registerCodingAgentPromptHelpers();
 	});
 
-	test("renders the generic pointer when a plugin is present, naming no plugin", async () => {
+	test("enumerates installed plugins with pointer, names no plugin in the core template", async () => {
 		const template = await Bun.file(systemPromptPath).text();
-		const rendered = prompt.render(template, { hasPlugins: true });
-		expect(rendered).toContain("xcsh://plugin");
-		// Generic/reusable: it must not name any specific plugin.
-		expect(rendered).not.toContain("meddpicc");
+		const rendered = prompt.render(template, {
+			hasPlugins: true,
+			plugins: [{ id: "meddpicc", name: "meddpicc", description: "MEDDPICC qualification helper" }],
+		});
+		expect(rendered).toContain("Installed plugins");
+		expect(rendered).toContain("xcsh://plugin/meddpicc");
+		expect(rendered).toContain("MEDDPICC qualification helper");
 	});
 
-	test("omits the pointer entirely when no plugins are present", async () => {
+	test("pointer uses the registry id while the label uses the manifest name", async () => {
 		const template = await Bun.file(systemPromptPath).text();
-		const rendered = prompt.render(template, { hasPlugins: false });
+		const rendered = prompt.render(template, {
+			hasPlugins: true,
+			plugins: [{ id: "registry-id", name: "Display Name", description: "mismatched name and id" }],
+		});
+		// POINTER must resolve against the registry id, not the display name.
+		expect(rendered).toContain("xcsh://plugin/registry-id");
+		expect(rendered).not.toContain("xcsh://plugin/Display Name");
+		// DISPLAY label keeps the manifest name.
+		expect(rendered).toContain("**Display Name**");
+	});
+
+	test("omits the block entirely when no plugins are present", async () => {
+		const template = await Bun.file(systemPromptPath).text();
+		const rendered = prompt.render(template, { hasPlugins: false, plugins: [] });
+		expect(rendered).not.toContain("Installed plugins");
 		expect(rendered).not.toContain("xcsh://plugin");
 	});
 });

package/src/system-prompt.ts

@@ -13,7 +13,7 @@ import { systemPromptCapability } from "./capability/system-prompt";
 import type { SkillsSettings } from "./config/settings";
 import { renderDeprecationGuardrails } from "./deprecations";
 import { type ContextFile, loadCapability, type SystemPrompt as SystemPromptFile } from "./discovery";
-import { listXcshPluginRoots } from "./discovery/helpers";
+import { listXcshPluginSummaries, type XcshPluginSummary } from "./discovery/helpers";
 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" };
@@ -556,12 +556,13 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 					? loadSkills({ ...mergedSkillsSettings, cwd: resolvedCwd }).then(result => result.skills)
 					: Promise.resolve([]);
 
-		// L0 plugin-capability pointer: gate a generic `xcsh://plugin` hint on ≥1
-		// discoverable plugin. Discovery is cached and reads one small registry file,
-		// so this is effectively free; it fails safe to `false` (no hint) on error.
-		const hasPluginsPromise: Promise<boolean> = listXcshPluginRoots(os.homedir(), resolvedCwd)
-			.then(result => result.roots.length > 0)
-			.catch(() => false);
+		// Installed-plugins capability index: enumerate installed plugins (name + own-manifest
+		// description + xcsh://plugin/<name> pointer) so the agent reliably consults them. Discovery
+		// is cached; fails safe to [] (no block) on error.
+		const pluginSummariesPromise: Promise<XcshPluginSummary[]> = listXcshPluginSummaries(
+			os.homedir(),
+			resolvedCwd,
+		).catch(() => []);
 
 		return Promise.all([
 			resolvePromptInput(customPrompt, "system prompt"),
@@ -570,7 +571,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 			contextFilesPromise,
 			agentsMdSearchPromise,
 			skillsPromise,
-			hasPluginsPromise,
+			pluginSummariesPromise,
 		]).then(
 			([
 				resolvedCustomPrompt,
@@ -579,7 +580,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 				contextFiles,
 				agentsMdSearch,
 				skills,
-				hasPlugins,
+				pluginSummaries,
 			]) => ({
 				resolvedCustomPrompt,
 				resolvedAppendPrompt,
@@ -587,7 +588,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 				contextFiles,
 				agentsMdSearch,
 				skills,
-				hasPlugins,
+				pluginSummaries,
 			}),
 		);
 	})();
@@ -612,7 +613,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		files: [],
 	};
 	let skills: Skill[] = providedSkills ?? [];
-	let hasPlugins = false;
+	let pluginSummaries: XcshPluginSummary[] = [];
 
 	if (prepResult.type === "timeout") {
 		logger.warn("System prompt preparation timed out; using minimal startup context", {
@@ -635,9 +636,12 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		contextFiles = dedupeExactContextFiles(prepResult.value.contextFiles);
 		agentsMdSearch = prepResult.value.agentsMdSearch;
 		skills = prepResult.value.skills;
-		hasPlugins = prepResult.value.hasPlugins;
+		pluginSummaries = prepResult.value.pluginSummaries;
 	}
 
+	const plugins = pluginSummaries;
+	const hasPlugins = plugins.length > 0;
+
 	const date = new Date().toISOString().slice(0, 10);
 	const dateTime = date;
 	const promptCwd = resolvedCwd.replace(/\\/g, "/");
@@ -692,6 +696,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		agentsMdSearch,
 		skills: contextFilteredSkills,
 		rules: rules ?? [],
+		plugins,
 		hasPlugins,
 		alwaysApplyRules: injectedAlwaysApplyRules,
 		date,