@juicesharp/rpiv-pi 0.12.4 → 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/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;
+}

package/extensions/subagent-widget/pi-subagents-stubs/agent-manager.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compile-time stub for `pi-subagents/agent-manager` — see `./index.d.ts`
+ * for the stub rationale.
+ *
+ * Surface kept opaque on purpose: we touch exactly one thing on this
+ * class — `prototype.loadEntries` — via a runtime prototype patch in
+ * hide-builtin-manager-rows.ts. Typing the full upstream class (30+
+ * private fields, a dozen managed screens) would force us to mirror
+ * internal state we never read.
+ */
+
+export declare class AgentManagerComponent {
+	private readonly __piSubagentsAgentManagerComponent: true;
+}

package/extensions/subagent-widget/renderer-override.test.ts

@@ -63,6 +63,19 @@ Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", tas
 	});
 vi.mock("pi-subagents", () => ({ default: registerSubagentExtensionMock }));
 vi.mock("pi-subagents/render", () => ({ renderSubagentResult: vi.fn() }));
+// Stub AgentManagerComponent for the manager-row-filter install. Body
+// includes "this.agentData.builtin" to satisfy the drift anchor — the
+// install path is exercised end-to-end without touching the real upstream
+// class. Per-test prototype reset is wired in test/setup.ts.
+vi.mock("pi-subagents/agent-manager", () => {
+	class AgentManagerComponent {
+		agentData: { builtin: Array<{ name: string }> } = { builtin: [] };
+		loadEntries() {
+			void this.agentData.builtin;
+		}
+	}
+	return { AgentManagerComponent };
+});
 
 import { registerSubagentsWithQuietRenderer } from "./renderer-override.js";
 

package/extensions/subagent-widget/renderer-override.ts

@@ -6,6 +6,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import registerSubagentExtension from "pi-subagents";
 import { buildAgentEnumDescription } from "./agent-catalog.js";
+import { installManagerRowFilter, type SkipReason } from "./hide-builtin-manager-rows.js";
 import {
 	filterDisabledFromListResult,
 	getCuratedSubagentDescription,
@@ -87,6 +88,33 @@ function interceptRegisterTool(pi: ExtensionAPI): ExtensionAPI {
 	});
 }
 
+// Fail-soft install: the /agents overlay row-filter is best-effort UI polish
+// tied to pi-subagents@0.17.5 internals (AgentManagerComponent.prototype.
+// loadEntries). On any drift — module moved, class renamed, method body
+// changed — we log one stderr line and continue. The LLM-side filter
+// (interceptRegisterTool above) lives entirely on our boundary and is
+// unaffected. See hide-builtin-manager-rows.ts for skip-reason semantics.
+async function tryInstallManagerRowFilter(): Promise<void> {
+	let mod: { AgentManagerComponent?: unknown };
+	try {
+		mod = (await import("pi-subagents/agent-manager")) as { AgentManagerComponent?: unknown };
+	} catch {
+		process.stderr.write(
+			"[rpiv-pi] /agents overlay built-in filter disabled: pi-subagents/agent-manager not found.\n",
+		);
+		return;
+	}
+	installManagerRowFilter(mod.AgentManagerComponent, {
+		onSkip: (reason: SkipReason) => {
+			if (reason === "already-installed") return;
+			process.stderr.write(
+				`[rpiv-pi] /agents overlay built-in filter disabled (${reason}); built-in agents will be visible until rpiv-pi updates.\n`,
+			);
+		},
+	});
+}
+
 export async function registerSubagentsWithQuietRenderer(pi: ExtensionAPI): Promise<void> {
+	await tryInstallManagerRowFilter();
 	await registerSubagentExtension(interceptRegisterTool(pi));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": [
     "pi-package",