@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/bridge-server.js

@@ -0,0 +1,490 @@
+import { chmod, lstat, unlink } from "node:fs/promises";
+import { connect, createServer } from "node:net";
+import { errorMessage, isRecord } from "@hheei/pi-ext-core";
+import { PROTOCOL_VERSION } from "./domain.js";
+import { attachJsonLineReader, serializeJsonLine } from "./json-lines.js";
+import { BRIDGE_OPERATIONS, BridgeError, DEFAULT_MAX_FRAME_BYTES, DEFAULT_MAX_PENDING_REQUESTS, failureResponse, isEventFrame, isHelloFrame, isRequestFrame, isResponseFrame, successResponse, } from "./protocol.js";
+/**
+ * A handshake must arrive promptly: a socket that connects and then stays silent is either a
+ * probe or a broken client, and neither may occupy the server.
+ */
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+/** How long the parent waits for a child's answer before failing the call visibly. */
+export const DEFAULT_CHILD_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Reports are at-least-once: a child that loses the connection before the answer arrives sends the
+ * same request again, and the parent answers it from the first result instead of acting twice. The
+ * cache is per child and in memory — it covers a reconnect, not a parent restart.
+ */
+const MAX_SERVED_REQUESTS = 256;
+/** How long adoption waits for a surviving child to reconnect. */
+const DEFAULT_ADOPT_WAIT_MS = 5_000;
+/**
+ * The parent side of the child bridge: one Unix socket per parent session, one long-lived
+ * connection per child, carrying both directions of control.
+ *
+ * Control lives in the parent process instead of a helper process, so a child presented in a host
+ * panel and a child running headless are driven by exactly the same requests. A child that
+ * reconnects (parent restart, extension reload, dropped socket) replaces its previous connection
+ * and is otherwise treated as the same runtime.
+ */
+export class ChildBridgeServer {
+    #options;
+    #connections = new Map();
+    /**
+     * Requests already answered, keyed by runtime and request id, so a retry is not executed twice.
+     * The runtime identity belongs in the key: a relaunched child starts counting its request ids
+     * from the beginning again, and answering its first report with the previous runtime's result
+     * would silently drop a report the child believes was delivered.
+     */
+    #served = new Map();
+    /** Requests being handled right now, so two copies in flight share one answer. */
+    #serving = new Map();
+    /** Sockets that have connected but not finished their handshake, so close() can end them. */
+    #handshaking = new Set();
+    #adoptWaiters = new Set();
+    #eventListeners = new Set();
+    #connectionListeners = new Set();
+    #server;
+    #boundEndpoint = false;
+    #requestSeq = 0;
+    #closed = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    get endpoint() {
+        return this.#options.endpoint;
+    }
+    /** Binds the endpoint, refusing one that another live bridge server still owns. */
+    async listen() {
+        if (this.#server !== undefined)
+            throw new Error("bridge server is already listening");
+        await this.#clearStaleEndpoint();
+        const server = createServer({ allowHalfOpen: false });
+        this.#server = server;
+        server.on("connection", (socket) => this.#accept(socket));
+        server.on("error", (error) => this.#diagnose(`socket server error: ${errorMessage(error)}`));
+        const listening = new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(this.#options.endpoint, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        });
+        try {
+            await listening;
+        }
+        catch (error) {
+            this.#server = undefined;
+            server.close();
+            throw error instanceof Error ? error : new Error(errorMessage(error));
+        }
+        this.#boundEndpoint = true;
+        await this.#restrictEndpoint();
+    }
+    isConnected(childId) {
+        const connection = this.#connections.get(childId);
+        return connection !== undefined && !connection.closed;
+    }
+    connectedChildren() {
+        return [...this.#connections.values()]
+            .filter((entry) => !entry.closed)
+            .map((entry) => entry.childId);
+    }
+    /** Sends a request to a connected child and waits for its answer. */
+    async request(childId, operation, payload, options = {}) {
+        const connection = this.#connections.get(childId);
+        if (connection === undefined || connection.closed) {
+            throw new BridgeError("child_not_connected", `Child ${childId} has no live bridge connection`);
+        }
+        if (!BRIDGE_OPERATIONS.includes(operation)) {
+            // The child closes a connection that carries a frame it cannot parse, so an operation
+            // outside the protocol must fail here instead of hanging until the request timeout.
+            throw new BridgeError("unsupported_operation", `${operation} is not a bridge operation`);
+        }
+        const maxPending = this.#options.maxPendingRequests ?? DEFAULT_MAX_PENDING_REQUESTS;
+        if (connection.pending.size >= maxPending) {
+            throw new BridgeError("too_many_pending_requests", `Child ${childId} has too many requests in flight`);
+        }
+        const id = `bridge-${++this.#requestSeq}`;
+        const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs ?? DEFAULT_CHILD_REQUEST_TIMEOUT_MS;
+        const frame = {
+            version: PROTOCOL_VERSION,
+            type: "request",
+            id,
+            operation,
+            ...(payload === undefined ? {} : { payload }),
+        };
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                connection.pending.delete(id);
+                reject(new BridgeError("timeout", `Child ${childId} did not answer ${operation} in time`));
+            }, timeoutMs);
+            connection.pending.set(id, { resolve, reject, timer });
+            if (this.#write(connection, frame))
+                return;
+            // A request that never left the parent must fail now, not after the timeout.
+            connection.pending.delete(id);
+            clearTimeout(timer);
+            reject(new BridgeError("write_failed", `Could not send ${operation} to child ${childId}`));
+        });
+    }
+    /**
+     * Waits for a child's bridge to come up. A child that survived a parent restart reconnects on
+     * its own schedule, so adoption is a bounded wait rather than a spawn.
+     */
+    async waitForConnection(childId, options = {}) {
+        if (this.isConnected(childId))
+            return true;
+        return await new Promise((resolve) => {
+            let settled = false;
+            const finish = (connected) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.#adoptWaiters.delete(waiter);
+                options.signal?.removeEventListener("abort", onAbort);
+                resolve(connected);
+            };
+            const waiter = { childId, notify: finish };
+            const timer = setTimeout(() => finish(false), options.timeoutMs ?? DEFAULT_ADOPT_WAIT_MS);
+            const onAbort = () => finish(false);
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            this.#adoptWaiters.add(waiter);
+        });
+    }
+    /**
+     * Ends a child's connection from this side. The parent uses it when the process stopped being the
+     * child: leaving the socket open would let a relaunch mistake the old connection for the new
+     * runtime and send into a session the parent no longer owns.
+     */
+    disconnect(childId) {
+        const connection = this.#connections.get(childId);
+        if (connection === undefined)
+            return;
+        this.#connections.delete(childId);
+        this.#drop(connection, "the child left the delegated session");
+        this.#emitConnection(childId, false);
+    }
+    /** Subscribes to the fire-and-forget frames a child pushes: Pi events, lifecycle, input. */
+    onEvent(listener) {
+        this.#eventListeners.add(listener);
+        return () => {
+            this.#eventListeners.delete(listener);
+        };
+    }
+    /** Subscribes to connection transitions; a reconnect is what tells the parent a child is alive. */
+    onConnectionChange(listener) {
+        this.#connectionListeners.add(listener);
+        return () => {
+            this.#connectionListeners.delete(listener);
+        };
+    }
+    #emitEvent(childId, event) {
+        for (const listener of [...this.#eventListeners]) {
+            try {
+                listener(childId, event);
+            }
+            catch (error) {
+                this.#diagnose(`event listener failed: ${errorMessage(error)}`);
+            }
+        }
+    }
+    #emitConnection(childId, connected) {
+        for (const listener of [...this.#connectionListeners]) {
+            try {
+                listener(childId, connected);
+            }
+            catch (error) {
+                this.#diagnose(`connection listener failed: ${errorMessage(error)}`);
+            }
+        }
+    }
+    #notifyAdopters(childId) {
+        for (const waiter of [...this.#adoptWaiters]) {
+            if (waiter.childId === childId)
+                waiter.notify(true);
+        }
+    }
+    /** Closes every connection and removes the socket this server created. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const connection of [...this.#connections.values()]) {
+            this.#drop(connection, "bridge server is closing");
+        }
+        this.#connections.clear();
+        // A handshake that is still waiting for its answer holds a socket that would otherwise keep
+        // the server open, so teardown must end it here.
+        for (const socket of [...this.#handshaking])
+            socket.destroy();
+        this.#handshaking.clear();
+        for (const waiter of [...this.#adoptWaiters])
+            waiter.notify(false);
+        const server = this.#server;
+        this.#server = undefined;
+        if (server !== undefined) {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+            });
+        }
+        if (!this.#boundEndpoint)
+            return;
+        this.#boundEndpoint = false;
+        try {
+            await unlink(this.#options.endpoint);
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT")) {
+                this.#diagnose(`could not remove endpoint: ${errorMessage(error)}`);
+            }
+        }
+    }
+    #accept(socket) {
+        let connection;
+        this.#handshaking.add(socket);
+        const handshake = setTimeout(() => {
+            if (connection !== undefined)
+                return;
+            this.#diagnose("closing a connection that never completed the bridge handshake");
+            socket.destroy();
+        }, HANDSHAKE_TIMEOUT_MS);
+        const stop = attachJsonLineReader(socket, {
+            maxFrameBytes: this.#frameLimit(),
+            onValue: (value) => {
+                if (connection === undefined) {
+                    // A child waits for `hello_ack` before sending anything else, so nothing is pipelined
+                    // behind the hello: the handshake can complete asynchronously without losing frames.
+                    void this.#handshake(socket, value).then((accepted) => {
+                        if (accepted === undefined)
+                            return;
+                        clearTimeout(handshake);
+                        connection = accepted;
+                    });
+                    return;
+                }
+                this.#receive(connection, value);
+            },
+            onError: (error) => {
+                this.#diagnose(`bridge connection frame error: ${error.message}`);
+                socket.destroy();
+            },
+        });
+        const teardown = () => {
+            clearTimeout(handshake);
+            stop();
+            this.#handshaking.delete(socket);
+            const current = connection;
+            if (current === undefined)
+                return;
+            connection = undefined;
+            // A replaced connection already stopped being the child's connection.
+            if (current.closed || this.#connections.get(current.childId) !== current)
+                return;
+            this.#connections.delete(current.childId);
+            this.#drop(current, "bridge connection closed");
+            this.#emitConnection(current.childId, false);
+        };
+        socket.on("close", teardown);
+        socket.on("error", (error) => this.#diagnose(`bridge connection error: ${error.message}`));
+    }
+    async #handshake(socket, value) {
+        if (!isHelloFrame(value)) {
+            this.#diagnose("refused a bridge connection with an invalid hello frame");
+            socket.destroy();
+            return undefined;
+        }
+        if (value.parentSessionId !== this.#options.parentSessionId) {
+            this.#diagnose(`refused a bridge hello for another parent session: ${value.parentSessionId}`);
+            socket.destroy();
+            return undefined;
+        }
+        // The parent may need to read persisted state to answer this, so the handshake waits for it:
+        // a connection is never accepted on a partially verified hello. The socket can be gone by the
+        // time the answer arrives (a handshake timeout or a disconnect), and then there is nothing to
+        // accept.
+        const refusal = await this.#options.authorize(value);
+        // The answer can arrive after the server started closing, or after the socket went away; a late
+        // handshake must not create a connection that teardown is no longer waiting for.
+        if (this.#closed || socket.destroyed || !this.#handshaking.has(socket))
+            return undefined;
+        if (refusal !== undefined) {
+            this.#diagnose(`refused a bridge hello for ${value.subagentId}: ${refusal}`);
+            socket.destroy();
+            return undefined;
+        }
+        const previous = this.#connections.get(value.subagentId);
+        const connection = {
+            childId: value.subagentId,
+            runtimeIdentity: value.runtimeIdentity,
+            socket,
+            pending: new Map(),
+            closed: false,
+        };
+        this.#connections.set(value.subagentId, connection);
+        this.#write(connection, { version: PROTOCOL_VERSION, type: "hello_ack" });
+        if (previous !== undefined && previous !== connection) {
+            // The child reconnected: the newer socket is the live one, the old one is stale.
+            this.#drop(previous, "replaced by a newer bridge connection");
+            return connection;
+        }
+        this.#emitConnection(connection.childId, true);
+        this.#notifyAdopters(connection.childId);
+        return connection;
+    }
+    #receive(connection, value) {
+        if (isEventFrame(value)) {
+            this.#emitEvent(connection.childId, value.event);
+            return;
+        }
+        if (isResponseFrame(value)) {
+            const pending = connection.pending.get(value.id);
+            if (pending === undefined)
+                return;
+            connection.pending.delete(value.id);
+            clearTimeout(pending.timer);
+            if (value.ok)
+                pending.resolve(value.data);
+            else
+                pending.reject(new BridgeError(value.error.code, value.error.message));
+            return;
+        }
+        if (isRequestFrame(value)) {
+            const key = this.#requestKey(connection, value.id);
+            const answered = this.#served.get(key);
+            if (answered !== undefined) {
+                // The child did not receive the first answer, so it sent the same request again. It is
+                // answered from that first result: the parent already acted on it.
+                this.#write(connection, answered);
+                return;
+            }
+            const inFlight = this.#serving.get(key);
+            if (inFlight !== undefined) {
+                // The same request arrived twice, either because the answer was lost or because the child
+                // reconnected while the first copy was still being handled. Both askers want that one
+                // result, and the one asking now gets it on the connection it is asking on.
+                void inFlight.then((response) => this.#write(connection, response));
+                return;
+            }
+            const pending = this.#serve(connection, key, value.id, value.operation, value.payload);
+            this.#serving.set(key, pending);
+            return;
+        }
+        this.#diagnose("closing a bridge connection that sent an unrecognised frame");
+        connection.socket.destroy();
+    }
+    /**
+     * A request is identified by the runtime that sent it. A relaunched child — the same session, a
+     * new process — counts its request ids from one again, so the child alone is not an identity.
+     */
+    #requestKey(connection, id) {
+        return `${connection.childId}:${connection.runtimeIdentity}:${id}`;
+    }
+    /** Handles one child request and returns the frame that answers it. */
+    async #serve(connection, key, id, operation, payload) {
+        let response;
+        try {
+            const data = await this.#options.handleRequest({
+                childId: connection.childId,
+                runtimeIdentity: connection.runtimeIdentity,
+                operation,
+                payload,
+            });
+            response = successResponse(id, data);
+        }
+        catch (error) {
+            const code = error instanceof BridgeError ? error.code : "bridge_error";
+            response = failureResponse(id, code, errorMessage(error));
+        }
+        this.#serving.delete(key);
+        this.#served.set(key, response);
+        while (this.#served.size > MAX_SERVED_REQUESTS) {
+            const oldest = this.#served.keys().next();
+            if (oldest.done === true)
+                break;
+            this.#served.delete(oldest.value);
+        }
+        this.#write(connection, response);
+        return response;
+    }
+    /** Reports whether the frame left the parent; a frame that did not is diagnosed. */
+    #write(connection, frame) {
+        if (connection.closed || connection.socket.destroyed) {
+            this.#diagnose(`dropped a frame for child ${connection.childId}: the connection is gone`);
+            return false;
+        }
+        let encoded;
+        try {
+            encoded = serializeJsonLine(frame, this.#frameLimit());
+        }
+        catch (error) {
+            this.#diagnose(`could not serialize a frame for child ${connection.childId}: ${errorMessage(error)}`);
+            return false;
+        }
+        connection.socket.write(encoded);
+        return true;
+    }
+    #frameLimit() {
+        return this.#options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
+    }
+    /** Fails every request in flight for a connection that is going away. */
+    #drop(connection, reason) {
+        if (connection.closed)
+            return;
+        connection.closed = true;
+        for (const [id, pending] of connection.pending) {
+            connection.pending.delete(id);
+            clearTimeout(pending.timer);
+            pending.reject(new BridgeError("connection_lost", `Child ${connection.childId} connection closed: ${reason}`));
+        }
+        connection.socket.destroy();
+    }
+    async #clearStaleEndpoint() {
+        const endpoint = this.#options.endpoint;
+        try {
+            const stats = await lstat(endpoint);
+            if (!stats.isSocket()) {
+                throw new Error(`bridge endpoint path exists and is not a Unix socket: ${endpoint}`);
+            }
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return;
+            throw error instanceof Error ? error : new Error(errorMessage(error));
+        }
+        if (await isEndpointLive(endpoint)) {
+            throw new Error(`a live bridge server already owns endpoint ${endpoint}`);
+        }
+        await unlink(endpoint);
+        this.#diagnose(`removed stale endpoint ${endpoint}`);
+    }
+    async #restrictEndpoint() {
+        try {
+            await chmod(this.#options.endpoint, 0o600);
+        }
+        catch (error) {
+            this.#diagnose(`could not restrict endpoint permissions: ${errorMessage(error)}`);
+        }
+    }
+    #diagnose(message) {
+        this.#options.diagnose?.(message);
+    }
+}
+/** Probes whether something is still listening on a socket path. */
+function isEndpointLive(endpoint) {
+    return new Promise((resolve) => {
+        const socket = connect(endpoint);
+        const done = (live) => {
+            socket.destroy();
+            resolve(live);
+        };
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+        setTimeout(() => done(false), 1_000).unref();
+    });
+}
+function isErrno(error, code) {
+    return isRecord(error) && error.code === code;
+}

package/dist/builtin-agents.d.ts

@@ -0,0 +1,24 @@
+import type { DiscoveredAgent } from "./agent-resolver.js";
+/**
+ * A synthetic path, not a file: it names the definition in errors and UI without pretending
+ * to be an editable location.
+ */
+export declare const BUILTIN_AGENT_PREFIX = "<builtin>/";
+/**
+ * The tools the scout must keep: reading and searching, plus the channel it reports on. Anything
+ * missing is a configuration failure, not a shrug.
+ */
+export declare const SCOUT_REQUIRED_TOOLS: readonly ["read", "grep", "find", "ls", "contact_parent"];
+/** The tools a worker must keep: it exists to change code and to say what it changed. */
+export declare const WORKER_REQUIRED_TOOLS: readonly ["read", "edit", "write", "bash", "contact_parent"];
+/** The tools a reviewer must keep: it reads the code, runs the checks, and reports. */
+export declare const REVIEWER_REQUIRED_TOOLS: readonly ["read", "grep", "bash", "contact_parent"];
+/** The built-in definitions, parsed once. A malformed constant is a build-time bug, not user input. */
+export declare function builtinAgents(): readonly DiscoveredAgent[];
+/**
+ * Why a resolved tool allowlist would break a built-in agent's promise, or `undefined` when it
+ * does not. A built-in ships exactly the tools it names, so an allowlist that lost them, gained
+ * others, or became empty (which Pi reads as "every tool") would give the agent different powers
+ * than its definition advertises; resolution fails instead.
+ */
+export declare function builtinAgentToolProblem(sourcePath: string, tools: readonly string[]): string | undefined;

package/dist/builtin-agents.js

@@ -0,0 +1,152 @@
+/**
+ * Built-in agent definitions.
+ *
+ * These ship inside the package so a fresh install has usable roles without writing anything
+ * into the user's home: reconnaissance, implementation, and review. A user definition at the
+ * same name always wins, because discovery only falls back here after every filesystem scope
+ * has been searched.
+ */
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+/**
+ * A synthetic path, not a file: it names the definition in errors and UI without pretending
+ * to be an editable location.
+ */
+export const BUILTIN_AGENT_PREFIX = "<builtin>/";
+/**
+ * The tools the scout must keep: reading and searching, plus the channel it reports on. Anything
+ * missing is a configuration failure, not a shrug.
+ */
+export const SCOUT_REQUIRED_TOOLS = ["read", "grep", "find", "ls", "contact_parent"];
+/** The tools a worker must keep: it exists to change code and to say what it changed. */
+export const WORKER_REQUIRED_TOOLS = ["read", "edit", "write", "bash", "contact_parent"];
+/** The tools a reviewer must keep: it reads the code, runs the checks, and reports. */
+export const REVIEWER_REQUIRED_TOOLS = ["read", "grep", "bash", "contact_parent"];
+const SCOUT_DEFINITION = `---
+name: scout
+description: Read-only reconnaissance of a codebase or a question, reported back to the parent.
+hidden: false
+tools: read,grep,find,ls,contact_parent
+---
+
+You are a read-only scout. Your job is to look things up and report exactly what you found.
+
+Rules:
+- Read and search only. You cannot write files, run commands, or change state; do not pretend otherwise.
+- Ground every claim in a file path and the line you read. If you could not verify something, say so.
+- Finish by writing your final findings and summary as normal text in your response; the harness automatically delivers it to the parent once completed.
+- Use contact_parent ONLY if you are blocked or urgently require a parent decision midway; NEVER call contact_parent to report success or task completion.
+`;
+const WORKER_DEFINITION = `---
+name: worker
+description: Carries out an implementation task in the repository and reports what it changed.
+hidden: false
+tools: read,grep,find,ls,bash,edit,write,contact_parent
+model: inherit
+---
+
+You are a worker. Carry out the task in the repository you were given, and report what you did.
+
+Rules:
+- Read the surrounding code and the repository's own conventions before you edit. Keep the change
+  focused on the task; do not refactor unrelated code.
+- Run the focused checks the change needs (tests, typecheck, lint) and report their real output,
+  including failures. Do not describe a check you did not run.
+- Do not commit, push, or open a pull request unless the task asks for it explicitly.
+- Finish by writing what changed, what you verified, and what you could not verify as normal text
+  in your response; the harness automatically delivers it to the parent once completed.
+- Use contact_parent ONLY if you are blocked or urgently require a parent decision midway; NEVER
+  call contact_parent to report success or task completion.
+`;
+const REVIEWER_DEFINITION = `---
+name: reviewer
+description: Reviews code or a change and reports findings, using the review skills it is given.
+hidden: false
+skills: true
+tools: read,grep,find,ls,bash,contact_parent
+model: inherit
+---
+
+You are a reviewer. Inspect what you were pointed at and report findings. Do not change files unless
+the task asks you to fix what you find.
+
+Rules:
+- Ground every finding in a file path and the line you read. If you could not verify something, say
+  so instead of guessing.
+- Order findings by severity and report the smallest set of real defects, risks and simplifications.
+  A padded list costs the parent more than it tells it.
+- When the code-review skill is listed in your prompt and the task is a review of a change, follow
+  it: review along its two axes (the repository's own standards, and the spec the change came from)
+  and report them separately, as the skill describes.
+- When the ponytail-review skill is listed and the question is whether something is over-engineered,
+  follow it: one line per finding — location, what to cut, what replaces it.
+- Use bash to run the checks a finding depends on (tests, typecheck, a reproduction) and report the
+  real output, not your expectation.
+- A child cannot delegate further, so when a skill or a plan asks for parallel sub-agents, run those
+  passes yourself instead of trying to spawn them, and say that is what you did.
+- Finish by writing your findings as normal text in your response; the harness automatically
+  delivers it to the parent once completed.
+- Use contact_parent ONLY if you are blocked or urgently require a parent decision midway; NEVER
+  call contact_parent to report success or task completion.
+`;
+const DEFINITIONS = [
+    { text: SCOUT_DEFINITION, requiredTools: SCOUT_REQUIRED_TOOLS },
+    { text: WORKER_DEFINITION, requiredTools: WORKER_REQUIRED_TOOLS },
+    { text: REVIEWER_DEFINITION, requiredTools: REVIEWER_REQUIRED_TOOLS },
+];
+/** Reads the comma form used by built-in definitions. */
+function toolNames(value) {
+    if (typeof value !== "string")
+        return [];
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+let parsed;
+/** The built-in definitions, parsed once. A malformed constant is a build-time bug, not user input. */
+export function builtinAgents() {
+    parsed ??= DEFINITIONS.map(parseDefinition);
+    return parsed;
+}
+function parseDefinition(definition) {
+    const { frontmatter, body } = parseFrontmatter(definition.text);
+    const name = frontmatter.name;
+    if (typeof name !== "string" || name === "") {
+        throw new Error("Built-in agent definition has no name");
+    }
+    const declared = toolNames(frontmatter.tools);
+    // An empty `tools` list means "every tool" downstream, which is the opposite of what a
+    // built-in promises, so the definition is rejected rather than widened.
+    if (declared.length === 0) {
+        throw new Error(`Built-in agent ${name} must name the tools it may use`);
+    }
+    const missing = definition.requiredTools.filter((tool) => !declared.includes(tool));
+    if (missing.length > 0) {
+        throw new Error(`Built-in agent ${name} must keep its required tools; missing: ${missing.join(", ")}`);
+    }
+    return { name, path: `${BUILTIN_AGENT_PREFIX}${name}.md`, frontmatter, body };
+}
+/**
+ * Why a resolved tool allowlist would break a built-in agent's promise, or `undefined` when it
+ * does not. A built-in ships exactly the tools it names, so an allowlist that lost them, gained
+ * others, or became empty (which Pi reads as "every tool") would give the agent different powers
+ * than its definition advertises; resolution fails instead.
+ */
+export function builtinAgentToolProblem(sourcePath, tools) {
+    const definition = builtinAgents().find((agent) => agent.path === sourcePath);
+    if (definition === undefined)
+        return undefined;
+    if (tools.length === 0) {
+        return "its tool list was lost, which would give it every tool";
+    }
+    const declared = toolNames(definition.frontmatter.tools);
+    const missing = declared.filter((tool) => !tools.includes(tool));
+    if (missing.length > 0) {
+        return `tools it declares are missing: ${missing.join(", ")}`;
+    }
+    const gained = tools.filter((tool) => !declared.includes(tool) && tool !== "codemode");
+    if (gained.length > 0) {
+        return `it would gain tools it never declared: ${gained.join(", ")}`;
+    }
+    return undefined;
+}