/** * Load the dev-loops extension inside Pi subagent children * (skills/docs/cross-harness-regression-contract.md, "Read-only role enforcement on Pi"). * * The read-only role gate (`./readonly-role-gate.ts`) is a `tool_call` handler, so it only * fires when the dev-loops extension is loaded in the *calling* session. pi-subagents never * loads ambient extensions into a foreground (`async: false`) child — the shipped gate * fan-out shape — so the gate stayed inert for real judge and reviewer children even though * their system prompt carries the `` tag. * * The extension therefore registers itself as a required child extension for its own session * (`pi-subagents/required-child-extensions`). A required extension is appended to every * child's extension list on both launch hosts, so a foreground child now loads the extension * and its `tool_call` handler resolves the tag from its own prompt. * * Pi-only and optional: `extension/index.ts` is the Pi entry (`pi.extensions`), and Claude * Code never loads it. The `pi-subagents` import is guarded, so a session without * pi-subagents installed is unaffected. */ import { createRequire } from "node:module"; import os from "node:os"; import path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; /** Safe host-owned id for the registration (pi-subagents exposes ids, never paths, in evidence). */ export const REQUIRED_CHILD_EXTENSION_ID = "dev-loops-readonly-role-gate"; export type RequiredChildExtensionRegistration = { dispose(): void }; export type RegisterRequiredChildExtensions = (input: { sessionId: string; extensions: ReadonlyArray<{ id: string; path: string }>; requireForAllRunners?: boolean; }) => RequiredChildExtensionRegistration; /** * Bounded `node_modules` search roots for `pi-subagents`, mirroring the bounded-candidate * discipline used to locate the dev-loops CLI (never an unbounded filesystem walk). * * - every ancestor `node_modules` of the extension directory: covers a checkout that installs * pi-subagents locally and an installed dev-loops package that depends on it * - the Pi npm package directory: how Pi installs npm packages (`~/.pi/agent/npm/node_modules`) * - `NODE_PATH` entries * - the global npm prefix derived from the running Node binary (`/lib/node_modules`): * the container installs pi-subagents with `npm install -g` */ export function candidatePiSubagentsRoots({ extensionDir, home = os.homedir(), nodePath = process.env.NODE_PATH, execPath = process.execPath, }: { extensionDir: string; home?: string; nodePath?: string; execPath?: string; }): string[] { const roots: string[] = []; let dir = path.resolve(extensionDir); for (;;) { roots.push(path.join(dir, "node_modules")); const parent = path.dirname(dir); if (parent === dir) break; dir = parent; } roots.push(path.join(home, ".pi", "agent", "npm", "node_modules")); for (const entry of (nodePath ?? "").split(path.delimiter)) { if (entry) roots.push(entry); } roots.push(path.join(path.dirname(path.dirname(execPath)), "lib", "node_modules")); return [...new Set(roots)]; } const SPECIFIER = "pi-subagents/required-child-extensions"; /** * Resolve `registerRequiredChildExtensions` from pi-subagents, or null when pi-subagents is * not installed in any bounded root (or is too old to export the API). The subpath is * resolved through the package's own `exports` map, never a hard-coded internal file path. */ const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url)); export async function loadRegisterRequiredChildExtensions({ roots = candidatePiSubagentsRoots({ extensionDir: EXTENSION_DIR }), importer = import.meta.url, }: { roots?: string[]; importer?: string; } = {}): Promise { const require = createRequire(importer); for (const root of roots) { try { const resolved = require.resolve(SPECIFIER, { paths: [root] }); const mod = (await import(pathToFileURL(resolved).href)) as { registerRequiredChildExtensions?: unknown }; if (typeof mod.registerRequiredChildExtensions === "function") { return mod.registerRequiredChildExtensions as RegisterRequiredChildExtensions; } } catch { // Not resolvable from this root — try the next bounded candidate. } } return null; } /** * Register the dev-loops extension as a required child extension for one parent session. * * `requireForAllRunners` is requested first so a placement that cannot load the extension * (an external CLI/job runner or a remote machine) is refused instead of running ungated. * That flag exists from pi-subagents 0.75; on 0.68–0.74 it rejects the unknown key, so the * non-mandatory form is retried, which still gates every native child — the only placement * dev-loops declares for its role agents. * * The registration API (`pi-subagents/required-child-extensions`) exists only from * pi-subagents 0.68. Below that floor `require.resolve` of the subpath throws, * `loadRegisterRequiredChildExtensions` returns null and `register` no-ops, so the child * never loads the `tool_call` gate and runs ungated. */ export function registerDevLoopsRequiredChildExtension({ register, sessionId, extensionPath, }: { register: RegisterRequiredChildExtensions; sessionId: string; extensionPath: string; }): RequiredChildExtensionRegistration | null { if (!sessionId || !extensionPath) return null; const extensions = [{ id: REQUIRED_CHILD_EXTENSION_ID, path: extensionPath }]; try { return register({ sessionId, extensions, requireForAllRunners: true }); } catch { // Older pi-subagents: retry without the mandatory-runner flag. } try { return register({ sessionId, extensions }); } catch { return null; } } export type ChildRoleGateRegistrar = { /** Register for one session id; re-registering disposes the prior handle. No-ops without a loader or id. */ register(sessionId: string | undefined): Promise; /** Dispose every live registration (idempotent). */ disposeAll(): void; /** Live session ids, in registration order. */ registeredSessionIds(): string[]; }; /** * Session-scoped owner of the required-child-extension registrations. One registration is * allowed per session id, so a repeated `session_start` disposes the prior handle first, and * `session_shutdown` releases them all. */ export function createChildRoleGateRegistrar({ extensionPath, load = loadRegisterRequiredChildExtensions, }: { extensionPath: string; load?: typeof loadRegisterRequiredChildExtensions; }): ChildRoleGateRegistrar { const registrations = new Map(); return { async register(sessionId) { if (!sessionId) return; registrations.get(sessionId)?.dispose(); registrations.delete(sessionId); const register = await load(); if (!register) return; const registration = registerDevLoopsRequiredChildExtension({ register, sessionId, extensionPath }); if (registration) registrations.set(sessionId, registration); }, disposeAll() { for (const registration of registrations.values()) registration.dispose(); registrations.clear(); }, registeredSessionIds() { return [...registrations.keys()]; }, }; }