@juicesharp/rpiv-pi 0.12.3 → 0.12.5

package/README.md

@@ -194,6 +194,8 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 rpiv-pi owns nicobailon's pi-subagents registration (runs it through an in-process proxy so the inline tool card stays quiet and the Subagents overlay is the live view). `/rpiv-setup` strips `"npm:pi-subagents"` from your `~/.pi/agent/settings.json#packages[]` to prevent Pi from loading it twice. If you remove rpiv-pi, subagents will stop loading until you re-add that entry.
 
+The bundled built-in agents from `pi-subagents` (`scout`, `planner`, `oracle`, …) are hidden from both the `subagent` tool that the assistant dispatches to and the `/agents` manager overlay (and `ctrl+shift+a`). The overlay filter is best-effort — if a future `pi-subagents` release changes its manager UI, rpiv-pi will print one boot-time warning to stderr and the built-in rows will reappear in `/agents` until rpiv-pi ships an update. The assistant-side filter is unaffected by upstream changes. To re-enable a built-in agent yourself, edit `subagents.disableBuiltins` in `~/.pi/agent/settings.json` (set to `false` or delete the key) and restart Pi.
+
 To fully uninstall:
 
 1. Remove rpiv-pi from Pi: `pi uninstall npm:@juicesharp/rpiv-pi`

package/extensions/subagent-widget/agent-catalog.test.ts

@@ -0,0 +1,110 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { AGENT_CATALOG, buildAgentEnumDescription } from "./agent-catalog.js";
+import { RPIV_SPECIALISTS } from "./hide-builtin-subagents.js";
+
+const AGENTS_DIR = fileURLToPath(new URL("../../agents/", import.meta.url));
+
+function readFrontmatterDescription(name: string): string {
+	const content = readFileSync(join(AGENTS_DIR, `${name}.md`), "utf8");
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) throw new Error(`${name}.md has no frontmatter`);
+	const fm = parseYaml(match[1]) as Record<string, unknown>;
+	return fm.description as string;
+}
+
+describe("AGENT_CATALOG — frontmatter-sourced per-agent descriptions", () => {
+	it("contains exactly one entry per RPIV_SPECIALISTS name, in declaration order", () => {
+		expect(AGENT_CATALOG.map((e) => e.name)).toEqual([...RPIV_SPECIALISTS]);
+	});
+
+	it("every entry has a non-empty description string", () => {
+		for (const entry of AGENT_CATALOG) {
+			expect(typeof entry.description).toBe("string");
+			expect(entry.description.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("each entry's description is a byte-for-byte mirror of the agents/<name>.md frontmatter", () => {
+		// Hard invariant: no trimming, no truncation, no transformation — the
+		// value the LLM sees is exactly the value authored in the .md file.
+		for (const entry of AGENT_CATALOG) {
+			expect(entry.description).toBe(readFrontmatterDescription(entry.name));
+		}
+	});
+});
+
+describe("AGENTS_DIR resolution — cross-platform URL walk via fileURLToPath(new URL(...))", () => {
+	// WHATWG URL resolution is OS-agnostic: `new URL("../../agents/", base)` uses
+	// forward-slash URL semantics regardless of what OS the test runs on. We can
+	// therefore simulate POSIX, Windows, and Windows-UNC base URLs from any host
+	// platform and assert the resolved URL is correct — no actual file I/O, no
+	// need for a Windows CI runner to catch URL-walk bugs.
+	const MODULE_REL = "/packages/rpiv-pi/extensions/subagent-widget/agent-catalog.ts";
+
+	it("POSIX base: resolves to the rpiv-pi/agents/ directory URL", () => {
+		const base = `file:///Users/alice/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		expect(resolved.href).toBe("file:///Users/alice/repo/packages/rpiv-pi/agents/");
+	});
+
+	it("Windows drive-letter base: resolves preserving the C: drive and backslash-free URL form", () => {
+		const base = `file:///C:/Users/alice/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		expect(resolved.href).toBe("file:///C:/Users/alice/repo/packages/rpiv-pi/agents/");
+	});
+
+	it("Windows UNC share base: preserves the //server/share/ authority across the relative walk", () => {
+		const base = `file:////server/share/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		// WHATWG keeps the empty-host + path-with-leading-// form of UNC file URLs;
+		// Node's fileURLToPath on Windows later converts this to \\server\share\... .
+		expect(resolved.href).toBe("file:////server/share/repo/packages/rpiv-pi/agents/");
+	});
+
+	it("URL-encoded characters in the path (space, %20): round-trip through fileURLToPath correctly", () => {
+		// Typical hazard: installing under a path with a space (e.g. "Program Files").
+		// import.meta.url encodes the space as %20; fileURLToPath decodes it back.
+		const base = `file:///Users/alice/Program%20Files/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		expect(resolved.href).toBe("file:///Users/alice/Program%20Files/repo/packages/rpiv-pi/agents/");
+		// fileURLToPath decodes %20 back to a literal space in the filesystem path.
+		const fsPath = fileURLToPath(resolved);
+		expect(fsPath).toContain("Program Files");
+		expect(fsPath).not.toContain("%20");
+	});
+
+	it("current-platform sanity: AGENTS_DIR points at a real directory containing the specialists", () => {
+		// Closes the loop — the URL walk is correct on this runner AND the
+		// resulting path is a real dir that readFileSync can subsequently read.
+		const stat = statSync(AGENTS_DIR);
+		expect(stat.isDirectory()).toBe(true);
+		for (const name of RPIV_SPECIALISTS) {
+			const entryStat = statSync(join(AGENTS_DIR, `${name}.md`));
+			expect(entryStat.isFile()).toBe(true);
+		}
+	});
+});
+
+describe("buildAgentEnumDescription — flattens catalog into an LLM-facing bullet list", () => {
+	const text = buildAgentEnumDescription();
+
+	it("starts with a contextual header line before the bullet list", () => {
+		expect(text.split("\n")[0]).toBe("Agent name (SINGLE mode) or target for management get/update/delete. Options:");
+	});
+
+	it("emits one '- <name>: <description>' bullet per specialist", () => {
+		for (const entry of AGENT_CATALOG) {
+			expect(text).toContain(`- ${entry.name}: ${entry.description}`);
+		}
+	});
+
+	it("orders bullets by RPIV_SPECIALISTS declaration order", () => {
+		const bullets = text.split("\n").slice(1);
+		const names = bullets.map((line) => line.replace(/^- /, "").split(":")[0]);
+		expect(names).toEqual([...RPIV_SPECIALISTS]);
+	});
+});

package/extensions/subagent-widget/agent-catalog.ts

@@ -0,0 +1,58 @@
+// Loads per-agent descriptions from packages/rpiv-pi/agents/<name>.md YAML
+// frontmatter so the `agent` tool parameter can carry a rich enum-with-table
+// description instead of duplicating copy across the monorepo. Runs once at
+// module init; crashes loudly if an expected agent file is missing.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { RPIV_SPECIALISTS } from "./hide-builtin-subagents.js";
+
+// extensions/subagent-widget/agent-catalog.ts → packages/rpiv-pi/agents/
+// URL form matches the monorepo idiom (see root guidance: prompts loaded via
+// `fileURLToPath(new URL("./prompts/…", import.meta.url))`) and cross-platform
+// safely handles both POSIX and Windows file URLs.
+const AGENTS_DIR = fileURLToPath(new URL("../../agents/", import.meta.url));
+
+// Splits a markdown file on its leading `---` frontmatter fences and parses
+// the YAML block. Returns undefined when no frontmatter is present.
+function extractFrontmatter(content: string): Record<string, unknown> | undefined {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return undefined;
+	const parsed = parseYaml(match[1]) as unknown;
+	if (typeof parsed !== "object" || parsed === null) return undefined;
+	return parsed as Record<string, unknown>;
+}
+
+export interface AgentCatalogEntry {
+	readonly name: string;
+	readonly description: string;
+}
+
+function loadAgentEntry(name: string): AgentCatalogEntry {
+	const path = join(AGENTS_DIR, `${name}.md`);
+	const content = readFileSync(path, "utf8");
+	const fm = extractFrontmatter(content);
+	if (!fm) throw new Error(`agent-catalog: ${name}.md has no YAML frontmatter`);
+	const description = fm.description;
+	if (typeof description !== "string" || description.length === 0) {
+		throw new Error(`agent-catalog: ${name}.md frontmatter is missing a string 'description'`);
+	}
+	return { name, description };
+}
+
+// Eager load at module init: one readFileSync per specialist. Failure modes
+// (missing file, missing description) fail Pi's boot rather than surfacing as
+// a runtime tool-registration error — consistent with rpiv-todo / rpiv-advisor
+// loading their prompts at module init.
+export const AGENT_CATALOG: ReadonlyArray<AgentCatalogEntry> = RPIV_SPECIALISTS.map(loadAgentEntry);
+
+// Flattens the catalog into the LLM-facing string used as the `agent` param's
+// `description`. Format: header line + "- <name>: <desc>" bullets. Keeps the
+// list parameter-adjacent so the LLM sees agent capabilities inline with the
+// enum choice instead of having to cross-reference a separate doc.
+export function buildAgentEnumDescription(): string {
+	const bullets = AGENT_CATALOG.map((entry) => `- ${entry.name}: ${entry.description}`).join("\n");
+	return `Agent name (SINGLE mode) or target for management get/update/delete. Options:\n${bullets}`;
+}

package/extensions/subagent-widget/catalog-drift.test.ts

@@ -0,0 +1,21 @@
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { RPIV_SPECIALISTS } from "./hide-builtin-subagents.js";
+
+const AGENTS_DIR = fileURLToPath(new URL("../../agents/", import.meta.url));
+
+function discoverAgentStems(): string[] {
+	return readdirSync(AGENTS_DIR)
+		.filter((name) => name.endsWith(".md"))
+		.map((name) => name.slice(0, -".md".length))
+		.sort();
+}
+
+describe("RPIV_SPECIALISTS catalog drift guard", () => {
+	it("matches the bundled packages/rpiv-pi/agents/*.md filenames", () => {
+		const onDisk = discoverAgentStems();
+		const declared = [...RPIV_SPECIALISTS].sort();
+		expect(declared).toEqual(onDisk);
+	});
+});

package/extensions/subagent-widget/hide-builtin-manager-rows.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	__resetManagerRowFilterForTests,
+	INSTALLED_SENTINEL,
+	installManagerRowFilter,
+	LOAD_ENTRIES_SOURCE_FRAGMENT,
+	type SkipReason,
+} from "./hide-builtin-manager-rows.js";
+
+interface AgentEntry {
+	name: string;
+}
+interface AgentDataFixture {
+	builtin: AgentEntry[];
+	user: AgentEntry[];
+	project: AgentEntry[];
+}
+interface ManagerLike {
+	agentData: AgentDataFixture;
+	_walkedBuiltin: string[];
+}
+
+// Synthetic constructor whose `loadEntries` mirrors the load-bearing shape
+// of upstream agent-manager.ts:120-124 — references `this.agentData.builtin`
+// (drift anchor) and walks it, recording names into a side-channel so tests
+// can assert what would have been rendered.
+function makeFixtureCtor(): new () => ManagerLike {
+	function FixtureCtor(this: ManagerLike) {
+		this.agentData = { builtin: [], user: [], project: [] };
+		this._walkedBuiltin = [];
+	}
+	FixtureCtor.prototype.loadEntries = function (this: ManagerLike) {
+		this._walkedBuiltin = [];
+		// Keep the literal substring so the drift guard accepts this fixture.
+		for (const config of this.agentData.builtin) {
+			this._walkedBuiltin.push(config.name);
+		}
+	};
+	return FixtureCtor as unknown as new () => ManagerLike;
+}
+
+describe("installManagerRowFilter", () => {
+	it("filters PI_SUBAGENTS_BUILTINS rows from the walked list", () => {
+		const Ctor = makeFixtureCtor();
+		const result = installManagerRowFilter(Ctor);
+		expect(result).toBe("installed");
+
+		const instance = new Ctor();
+		instance.agentData = {
+			builtin: [{ name: "scout" }, { name: "planner" }, { name: "general-purpose" }, { name: "codebase-locator" }],
+			user: [],
+			project: [],
+		};
+		instance._walkedBuiltin = [];
+		instance.constructor.prototype.loadEntries.call(instance);
+
+		expect(instance._walkedBuiltin).toEqual(["general-purpose", "codebase-locator"]);
+		__resetManagerRowFilterForTests();
+	});
+
+	it("filters on every invocation (covers refreshAgentData re-call)", () => {
+		const Ctor = makeFixtureCtor();
+		installManagerRowFilter(Ctor);
+		const instance = new Ctor();
+
+		instance.agentData = { builtin: [{ name: "scout" }, { name: "thoughts-locator" }], user: [], project: [] };
+		instance.constructor.prototype.loadEntries.call(instance);
+		expect(instance._walkedBuiltin).toEqual(["thoughts-locator"]);
+
+		instance.agentData = { builtin: [{ name: "oracle" }, { name: "diff-auditor" }], user: [], project: [] };
+		instance.constructor.prototype.loadEntries.call(instance);
+		expect(instance._walkedBuiltin).toEqual(["diff-auditor"]);
+
+		__resetManagerRowFilterForTests();
+	});
+
+	it("restores the unfiltered agentData reference after loadEntries returns", () => {
+		const Ctor = makeFixtureCtor();
+		installManagerRowFilter(Ctor);
+		const instance = new Ctor();
+		const unfiltered = {
+			builtin: [{ name: "scout" }, { name: "general-purpose" }],
+			user: [],
+			project: [],
+		};
+		instance.agentData = unfiltered;
+		instance.constructor.prototype.loadEntries.call(instance);
+
+		expect(instance.agentData).toBe(unfiltered);
+		expect(instance.agentData.builtin.map((c) => c.name)).toEqual(["scout", "general-purpose"]);
+		__resetManagerRowFilterForTests();
+	});
+
+	it("is idempotent — second install returns 'skipped' with reason 'already-installed'", () => {
+		const Ctor = makeFixtureCtor();
+		const first = installManagerRowFilter(Ctor);
+		const patched = (Ctor.prototype as { loadEntries: () => void }).loadEntries;
+
+		const onSkip = vi.fn<(reason: SkipReason) => void>();
+		const second = installManagerRowFilter(Ctor, { onSkip });
+		expect(first).toBe("installed");
+		expect(second).toBe("skipped");
+		expect(onSkip).toHaveBeenCalledWith("already-installed");
+		expect((Ctor.prototype as { loadEntries: () => void }).loadEntries).toBe(patched);
+		expect((Ctor as { [INSTALLED_SENTINEL]?: boolean })[INSTALLED_SENTINEL]).toBe(true);
+
+		__resetManagerRowFilterForTests();
+	});
+
+	it.each<[string, unknown, SkipReason]>([
+		["missing constructor (undefined)", undefined, "missing-constructor"],
+		["missing constructor (null)", null, "missing-constructor"],
+		["missing prototype", { prototype: undefined }, "missing-prototype"],
+		["missing loadEntries", { prototype: {} }, "missing-loadentries"],
+		["loadEntries lacks drift anchor", { prototype: { loadEntries: () => 1 } }, "drift-detected"],
+	])("fails soft on %s — onSkip(%s) and never throws", (_label, ctor, expectedReason) => {
+		const onSkip = vi.fn<(reason: SkipReason) => void>();
+		expect(() => installManagerRowFilter(ctor, { onSkip })).not.toThrow();
+		expect(onSkip).toHaveBeenCalledExactlyOnceWith(expectedReason);
+	});
+
+	it("survives invocation when agentData.builtin is missing", () => {
+		const Ctor = makeFixtureCtor();
+		installManagerRowFilter(Ctor);
+		const instance = new Ctor();
+		instance.agentData = { builtin: undefined as unknown as AgentEntry[], user: [], project: [] };
+		expect(() => instance.constructor.prototype.loadEntries.call(instance)).not.toThrow();
+		__resetManagerRowFilterForTests();
+	});
+});
+
+describe("real pi-subagents AgentManagerComponent contract", () => {
+	// Canary: this is the only test that touches the live upstream module.
+	// Failing here means upstream pi-subagents drifted between our pin and
+	// our release — bump the dep, update LOAD_ENTRIES_SOURCE_FRAGMENT (or
+	// retire the patch), and re-snapshot. At user runtime the patch fails
+	// soft via onSkip; this test exists so we catch drift before shipping.
+	it("loadEntries body still contains the load-bearing drift anchor", async () => {
+		// Dynamic import: matches the runtime guarded import in renderer-override.ts
+		// and avoids tsc resolving into the upstream .ts source via the path stub.
+		const mod = (await import("pi-subagents/agent-manager")) as {
+			AgentManagerComponent?: { prototype?: { loadEntries?: () => void } };
+		};
+		const proto = mod.AgentManagerComponent?.prototype;
+		const fn = proto?.loadEntries;
+		expect(typeof fn).toBe("function");
+		expect(fn?.toString()).toContain(LOAD_ENTRIES_SOURCE_FRAGMENT);
+	});
+});

package/extensions/subagent-widget/hide-builtin-manager-rows.ts

@@ -0,0 +1,129 @@
+// Hides the upstream pi-subagents built-in agent rows from the `/agents`
+// manager overlay (and ctrl+shift+a). Companion to hide-builtin-subagents.ts,
+// which hides the same names from the LLM-facing `subagent` tool surface.
+//
+// Strategy: monkey-patch `AgentManagerComponent.prototype.loadEntries` — the
+// single chokepoint that converts agentData → rendered AgentEntry rows. The
+// constructor calls it, refreshAgentData() calls it after every in-overlay
+// mutation, so one patch covers both code paths.
+//
+// Fail-soft contract: never throw at user runtime. Drift, missing class, or
+// missing method routes through the caller-supplied `onSkip` so Pi can
+// surface a single warning notify and continue booting. The /agents overlay
+// silently regains the upstream rows; the LLM-facing filter (Proxy in
+// renderer-override.ts) is unaffected because it lives on a different layer.
+
+import { PI_SUBAGENTS_BUILTINS } from "./hide-builtin-subagents.js";
+
+const BUILTIN_NAMES_SET = new Set<string>(PI_SUBAGENTS_BUILTINS);
+
+// Drift anchor: the load-bearing substring inside upstream
+// agent-manager.ts:120-124 loadEntries. If upstream rewrites the method to
+// stop reading agentData.builtin (rename, inline into ctor, route through a
+// helper), this fragment disappears and we skip with reason "drift-detected"
+// before mutating the prototype.
+export const LOAD_ENTRIES_SOURCE_FRAGMENT = "this.agentData.builtin";
+
+export const INSTALLED_SENTINEL = Symbol.for("rpiv-pi.manager-row-filter-installed");
+
+export type InstallResult = "installed" | "skipped";
+
+export type SkipReason =
+	| "missing-constructor"
+	| "missing-prototype"
+	| "missing-loadentries"
+	| "drift-detected"
+	| "already-installed";
+
+export interface InstallOptions {
+	onSkip?: (reason: SkipReason) => void;
+}
+
+interface AgentDataLike {
+	builtin?: Array<{ name?: unknown }>;
+}
+
+interface ManagerInstanceLike {
+	agentData?: AgentDataLike;
+}
+
+interface ManagerCtorLike {
+	prototype?: { loadEntries?: (this: ManagerInstanceLike) => void };
+	[INSTALLED_SENTINEL]?: boolean;
+}
+
+interface PatchRecord {
+	ctor: ManagerCtorLike;
+	original: (this: ManagerInstanceLike) => void;
+}
+
+let installedPatch: PatchRecord | undefined;
+
+function isFilteredBuiltin(entry: { name?: unknown }): boolean {
+	return typeof entry.name === "string" && BUILTIN_NAMES_SET.has(entry.name);
+}
+
+export function installManagerRowFilter(managerCtor: unknown, options: InstallOptions = {}): InstallResult {
+	const onSkip = options.onSkip ?? (() => {});
+	const ctor = managerCtor as ManagerCtorLike | undefined | null;
+
+	if (!ctor) {
+		onSkip("missing-constructor");
+		return "skipped";
+	}
+	if (ctor[INSTALLED_SENTINEL] === true) {
+		onSkip("already-installed");
+		return "skipped";
+	}
+	const proto = ctor.prototype;
+	if (!proto) {
+		onSkip("missing-prototype");
+		return "skipped";
+	}
+	const original = proto.loadEntries;
+	if (typeof original !== "function") {
+		onSkip("missing-loadentries");
+		return "skipped";
+	}
+	let source: string;
+	try {
+		source = original.toString();
+	} catch {
+		onSkip("drift-detected");
+		return "skipped";
+	}
+	if (!source.includes(LOAD_ENTRIES_SOURCE_FRAGMENT)) {
+		onSkip("drift-detected");
+		return "skipped";
+	}
+
+	proto.loadEntries = function patchedLoadEntries(this: ManagerInstanceLike): void {
+		// Defensive clone: never mutate the agentData reference we received.
+		// Other manager screens (override-scope, edit) read agentData directly
+		// and may rely on the unfiltered shape.
+		const original = this.agentData;
+		const builtin = Array.isArray(original?.builtin) ? original.builtin : [];
+		const filteredBuiltin = builtin.filter((c) => !isFilteredBuiltin(c ?? {}));
+		const filteredAgentData = { ...(original ?? {}), builtin: filteredBuiltin };
+		this.agentData = filteredAgentData as AgentDataLike;
+		try {
+			(installedPatch?.original ?? (() => {})).call(this);
+		} finally {
+			// Restore the unfiltered view for downstream reads outside loadEntries.
+			this.agentData = original;
+		}
+	};
+	ctor[INSTALLED_SENTINEL] = true;
+	installedPatch = { ctor, original };
+	return "installed";
+}
+
+// Test-only: undo the prototype mutation so each test sees a fresh slate.
+// Wired into test/setup.ts beforeEach. No-op when nothing is installed.
+export function __resetManagerRowFilterForTests(): void {
+	if (!installedPatch) return;
+	const { ctor, original } = installedPatch;
+	if (ctor.prototype) ctor.prototype.loadEntries = original;
+	delete ctor[INSTALLED_SENTINEL];
+	installedPatch = undefined;
+}