pi-better-subagents 0.1.0

package/capacity.mjs

@@ -0,0 +1,112 @@
+/**
+ * Shared capacity admission for subagent_spawn and subagent_spawn_batch.
+ *
+ * Running metas alone are not enough: between "admit" and "writeMeta" an
+ * async yield can let another spawn oversubscribe maxConcurrent. This gate
+ * keeps in-process pending reservations that count against the same cap for
+ * every spawn path in the parent process.
+ *
+ * Contract:
+ *   - tryReserve(n) is all-or-nothing for n slots.
+ *   - commit(n) after a run becomes "running" (pending → running).
+ *   - release(n) after a pre-spawn failure (pending freed for backfill).
+ *   - available = max(0, maxConcurrent - running - pending).
+ */
+
+/**
+ * Free slots after subtracting durable running metas and in-flight reservations.
+ */
+export function availableSlots({ runningCount, pendingCount = 0, maxConcurrent }) {
+    return Math.max(0, maxConcurrent - runningCount - pendingCount);
+}
+
+/**
+ * Error text for reject-mode whole-batch capacity failure. Kept identical to
+ * planBatchLaunches so callers can throw without re-planning.
+ */
+export function formatCapacityRejectMessage({
+    jobCount,
+    runningCount,
+    pendingCount = 0,
+    maxConcurrent,
+}) {
+    const available = availableSlots({ runningCount, pendingCount, maxConcurrent });
+    return (
+        `Batch of ${jobCount} jobs exceeds available capacity ` +
+        `(${available}/${maxConcurrent} subagent slots free). ` +
+        'Stop some runs or set onCapacity to "launch-available".'
+    );
+}
+
+/**
+ * Process-local capacity gate. One instance is shared by single-spawn and
+ * batch-spawn so reservations cannot race each other inside the parent.
+ *
+ * @param {() => number} countRunning durable running metas owned by this parent
+ */
+export function createCapacityGate(countRunning) {
+    let pending = 0;
+
+    return {
+        get pending() {
+            return pending;
+        },
+
+        /**
+         * Reserve `count` slots atomically against current running+pending.
+         * Returns false without mutating state when capacity is insufficient.
+         */
+        tryReserve(count, maxConcurrent) {
+            if (count <= 0) return true;
+            const available = availableSlots({
+                runningCount: countRunning(),
+                pendingCount: pending,
+                maxConcurrent,
+            });
+            if (count > available) return false;
+            pending += count;
+            return true;
+        },
+
+        /** Convert reserved slots into durable running occupancy. */
+        commit(count = 1) {
+            if (count <= 0) return;
+            if (count > pending) {
+                throw new Error(
+                    `capacity commit(${count}) exceeds pending reservations (${pending})`,
+                );
+            }
+            pending -= count;
+        },
+
+        /** Free reserved slots that never became a running run (pre-spawn failure). */
+        release(count = 1) {
+            if (count <= 0) return;
+            if (count > pending) {
+                throw new Error(
+                    `capacity release(${count}) exceeds pending reservations (${pending})`,
+                );
+            }
+            pending -= count;
+        },
+    };
+}
+
+/** Singleton used by the extension so single and batch tools share one ledger. */
+let sharedGate;
+
+/**
+ * Return the process-wide gate, creating it with `countRunning` on first use.
+ * Tests may call `_resetSharedCapacityGateForTests` between cases.
+ */
+export function getSharedCapacityGate(countRunning) {
+    if (!sharedGate) {
+        sharedGate = createCapacityGate(countRunning);
+    }
+    return sharedGate;
+}
+
+/** Test-only: drop the singleton so a suite starts from a clean ledger. */
+export function _resetSharedCapacityGateForTests() {
+    sharedGate = undefined;
+}

package/completion.mjs

@@ -0,0 +1,165 @@
+/**
+ * Pure formatter functions for subagent completion messages.
+ * 
+ * These functions produce lightweight messages that:
+ * - callback=true (trigger): Signal completion and direct to subagent_result
+ * - callback=false (quiet): Note completion without auto-posting
+ * 
+ * The actual result is NEVER embedded in the trigger message to avoid
+ * double-display (model presents it AND it's embedded).
+ */
+
+/**
+ * Format a callback trigger message for callback:true.
+ * 
+ * This is a SHORT message that:
+ * - Announces the subagent finished
+ * - Tells the model to call/use subagent_result id="<id>"
+ * - Does NOT contain "--- result ---" or any result payload
+ * - MAY include label, verdict, stat, and tools list
+ * 
+ * @param p.id - The run id
+ * @param p.label - Human-readable label (e.g., "reviewer (abc123)")
+ * @param p.verdict - Status line (e.g., "✓ completed" or "✗ failed (exit 1)")
+ * @param p.stat - Statistics line (e.g., "45s · 1.2k tok · $0.0034")
+ * @param p.tools - Optional tools used (e.g., "read,bash,web_fetch")
+ */
+export function formatCallbackTrigger(p) {
+    const tools = p.tools ? ` ·${p.tools.replace(/\n/, " ")}` : "";
+    const lifecycle = p.lifecycleClassification ? ` · lifecycle ${p.lifecycleClassification}` : "";
+    const announcement = p.incomplete
+        ? "ATTENTION: a background subagent exited unexpectedly before producing a coherent final result."
+        : "A background subagent you launched has returned.";
+    const instruction = p.incomplete
+        ? `Inspect the diagnostic with subagent_result id="${p.id}" before deciding how to continue.`
+        : `Ingest this signal and call subagent_result id="${p.id}" to retrieve the actual result, then use/present it as appropriate.`;
+    return `${announcement}\nsubagent: ${p.label} · ${p.verdict} · ${p.stat}${tools}${lifecycle}\n\n${instruction}`;
+}
+
+/**
+ * Format a quiet completion message for callback:false.
+ * 
+ * This message:
+ * - Announces the subagent finished
+ * - Explicitly states result is NOT auto-posted
+ * - Directs to subagent_result for on-demand retrieval
+ * 
+ * @param p.id - The run id
+ * @param p.label - Human-readable label
+ * @param p.verdict - Status line
+ * @param p.stat - Statistics line
+ */
+export function formatCallbackQuiet(p) {
+    const lifecycle = p.lifecycleClassification ? ` · lifecycle ${p.lifecycleClassification}` : "";
+    if (p.incomplete) {
+        return `ATTENTION: background subagent ${p.label} ended unexpectedly · ${p.verdict} · ${p.stat}${lifecycle}. ` +
+            `Diagnostic NOT auto-posted (callback:false). Inspect it with subagent_result id="${p.id}".`;
+    }
+    return (
+        `Background subagent ${p.label} ${p.verdict} · ${p.stat}${lifecycle}. ` +
+        `Result NOT auto-posted (callback:false). ` +
+        `Read it with subagent_result id="${p.id}" when wanted.`
+    );
+}
+
+/**
+ * Build the completion delivery from run outcome.
+ *
+ * This is the SINGLE place where sendMessage content and options are assembled.
+ * `resultText` is accepted so callers can pass it without tests breaking, but
+ * it is NEVER placed into `content` for either branch — the actual result is
+ * always fetched via subagent_result, not embedded in the trigger/quiet message.
+ *
+ * @param p.id       - Run id
+ * @param p.label    - Human-readable label
+ * @param p.verdict  - Status line (e.g. "✓ completed")
+ * @param p.stat     - Statistics line (e.g. "45s · 1.2k tok")
+ * @param p.tools    - Optional tools list
+ * @param p.callback - Whether to trigger a turn (true) or be quiet (false)
+ * @param p.resultText - The parsed final answer; MUST NOT appear in content
+ */
+export function buildCompletionDelivery(p) {
+    if (p.callback) {
+        return {
+            content: formatCallbackTrigger({
+                id: p.id,
+                label: p.label,
+                verdict: p.verdict,
+                stat: p.stat,
+                tools: p.tools,
+                incomplete: p.incomplete,
+                lifecycleClassification: p.lifecycleClassification,
+            }),
+            options: { deliverAs: "followUp", triggerTurn: true },
+        };
+    }
+    return {
+        content: formatCallbackQuiet({
+            id: p.id,
+            label: p.label,
+            verdict: p.verdict,
+            stat: p.stat,
+            incomplete: p.incomplete,
+            lifecycleClassification: p.lifecycleClassification,
+        }),
+        options: { deliverAs: "nextTurn" },
+    };
+}
+
+/**
+ * Format a health-attention trigger for orphaned/lost transitions (#65).
+ *
+ * Distinct from completion triggers: this is an ATTENTION signal that
+ * supervision broke (or ran out), not that a coherent result is ready.
+ * Never embeds artifacts — the coordinator inspects via tools.
+ *
+ * @param p.id     - Run id
+ * @param p.label  - Human-readable label
+ * @param p.status - "orphaned" | "lost"
+ */
+export function formatHealthCallbackTrigger(p) {
+    const inspect =
+        `Inspect with subagent_result id="${p.id}" and subagent_output id="${p.id}". ` +
+        `You may wait, stop (subagent_stop id="${p.id}"), or retry from the original task.`;
+    if (p.status === "orphaned") {
+        return (
+            `ATTENTION: a background subagent lost supervision and is now orphaned.\n` +
+            `subagent: ${p.label} · status orphaned\n\n` +
+            `Supervision was lost; related process-group work may still be alive. ` +
+            `This is not a final result.\n\n` +
+            inspect
+        );
+    }
+    return (
+        `ATTENTION: a background subagent is lost.\n` +
+        `subagent: ${p.label} · status lost\n\n` +
+        `No related process remains and no coherent terminal completion was observed. ` +
+        `This is a terminal unknown outcome, not a normal failure.\n\n` +
+        inspect
+    );
+}
+
+/**
+ * Build the model delivery for an orphaned/lost health transition.
+ *
+ * Uses the same non-interrupting mechanics as completion
+ * (`deliverAs: "followUp", triggerTurn: true`) but distinct ATTENTION wording.
+ * Returns null when callback is false — model follow-up is suppressed; the
+ * caller still owns human ui.notify / TUI-visible state.
+ *
+ * @param p.id       - Run id
+ * @param p.label    - Human-readable label
+ * @param p.status   - "orphaned" | "lost"
+ * @param p.callback - Whether to trigger a coordinator turn (default true)
+ */
+export function buildHealthCallbackDelivery(p) {
+    if (p.callback === false) return null;
+    return {
+        content: formatHealthCallbackTrigger({
+            id: p.id,
+            label: p.label,
+            status: p.status,
+        }),
+        options: { deliverAs: "followUp", triggerTurn: true },
+    };
+}

package/completion.ts

@@ -0,0 +1,11 @@
+/**
+ * TypeScript re-export of completion.mjs formatters.
+ * The actual logic lives in completion.mjs for ESM test compatibility.
+ */
+export {
+    formatCallbackTrigger,
+    formatCallbackQuiet,
+    buildCompletionDelivery,
+    formatHealthCallbackTrigger,
+    buildHealthCallbackDelivery,
+} from "./completion.mjs";

package/config.json

@@ -0,0 +1,14 @@
+{
+  "defaultModel": null,
+  "defaultTools": "read, bash, edit, write, web_search, web_fetch",
+  "maxConcurrent": 4,
+
+  "toolExtensions": {
+    "web_search": "npm:@juicesharp/rpiv-web-tools",
+    "web_fetch": "npm:@juicesharp/rpiv-web-tools"
+  },
+
+  "providerExtensions": {},
+
+  "inheritExtensions": false
+}

package/config.ts

@@ -0,0 +1,104 @@
+/**
+ * Extension config — a single `config.json` next to this file sets defaults for
+ * every subagent, each overridable per `subagent_spawn` call.
+ *
+ *   { "defaultModel": "xai/grok-4.5", "defaultTools": "read, bash, web_fetch" }
+ *
+ * `defaultModel: null` / absent → inherit the foreground model.
+ * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { SELF_SPEC } from "./extensions.ts";
+
+export interface SubagentConfig {
+    defaultModel?: string | null;
+    defaultTools?: string | null;
+    /** Max subagents allowed to run at once. */
+    maxConcurrent?: number | null;
+    /**
+     * Tool name → extension package(s) that provide it. Drives which extension
+     * CODE loads in a child: only packages backing a requested tool are loaded.
+     * Builtins (read/bash/edit/write) need no entry.
+     */
+    toolExtensions?: Record<string, string | string[]> | null;
+    /**
+     * Provider → extension package(s) that authenticate it. Model auth is not
+     * tool-shaped: `xai/grok-4.5` needs pi-xai-oauth loaded whatever the tools.
+     */
+    providerExtensions?: Record<string, string | string[]> | null;
+    /**
+     * OPERATOR-ONLY escape hatch: load every globally-installed extension in
+     * children (pre-#17 behavior). Never model-selectable. Re-exposes the
+     * mid-turn exit-0 drain if any installed package breaks process lifetime.
+     */
+    inheritExtensions?: boolean | null;
+    /**
+     * Optional health-observation thresholds (issue #66). Milliseconds.
+     * Override the defaults used by `resolveHealthThresholds` /
+     * `loadHealthThresholdsFromConfig` without expanding the spawn tool API.
+     */
+    healthQuietMs?: number | null;
+    healthStaleMs?: number | null;
+    healthLongToolMs?: number | null;
+    healthLongCompactionMs?: number | null;
+}
+
+/** Concurrency cap when config.json sets none. */
+export const DEFAULT_MAX_CONCURRENT = 4;
+
+/** Built-in default tool set when config.json sets nothing. */
+export const SAFE_DEFAULT_TOOLS = "read, bash, edit, write, web_search, web_fetch";
+/** Safe default for a hermetic (clean) child where extension tools don't exist. */
+export const SAFE_CLEAN_TOOLS = "read, bash";
+
+let cached: SubagentConfig | undefined;
+
+/** Load config.json from the extension directory. Missing/invalid → {}. */
+export function loadConfig(): SubagentConfig {
+    if (cached) return cached;
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        cached = JSON.parse(readFileSync(join(dir, "config.json"), "utf-8")) as SubagentConfig;
+    } catch {
+        cached = {};
+    }
+    return cached;
+}
+
+/** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */
+export function normalizeTools(list: string): string {
+    return list.split(",").map((t) => t.trim()).filter(Boolean).join(",");
+}
+
+/** This package's own root — the extension dir, which is also `self`. */
+export function selfDir(): string {
+    return dirname(fileURLToPath(import.meta.url));
+}
+
+/** Where pi installs npm packages (honors PI_CODING_AGENT_DIR). */
+function piAgentDir(): string {
+    return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+/**
+ * Materialize an extension spec to an on-disk path pi's `-e` accepts.
+ *
+ *   "self"                 → this package's dir
+ *   "npm:<pkg>"            → <agentDir>/npm/node_modules/<pkg>
+ *   "/abs/path"            → as-is
+ *
+ * Returns undefined when the package is not installed, so the caller can report
+ * a missing dependency instead of silently launching a child without it.
+ * (`-e` accepts either a package directory or an entrypoint file — verified.)
+ */
+export function resolveExtensionPath(spec: string): string | undefined {
+    if (spec === SELF_SPEC) return selfDir();
+    const path = spec.startsWith("npm:")
+        ? join(piAgentDir(), "npm", "node_modules", spec.slice(4))
+        : spec;
+    return existsSync(path) ? path : undefined;
+}

package/extensions.mjs

@@ -0,0 +1,147 @@
+/**
+ * Headless extension resolution — decide which extension CODE loads in a child.
+ *
+ * Why this exists (issue #17): a subagent that loads every globally-installed
+ * package inherits their startup side effects. `pi-patty-bg-tasks` replaces the
+ * builtin `bash` with a `detached` + `unref()` spawn; in `pi -p` a parallel
+ * `bash` + `read` batch then drains the Node event loop and the child EXITS 0
+ * mid-turn — no `tool_execution_end`, no `agent_end`. Measured: 30 recorded runs,
+ * 17 died this way and every one was reported as "completed".
+ *
+ * A tool allowlist CANNOT fix this. `--tools` restricts what the model may CALL;
+ * the offending package has already overridden builtin `bash` at startup, so the
+ * `bash` in your allowlist IS the broken one. Verified: extensions on + exactly
+ * `read,bash,edit,write,web_search,web_fetch` still dies 2-start / 1-end.
+ *
+ * pi also has no "load everything except X" flag — only `--extension/-e <path>`
+ * (add one) and `--no-extensions` (all off). So a package DENYLIST is not
+ * expressible at the CLI at all. The only mechanism that excludes a package is
+ * to stop loading everything and name what you want:
+ *
+ *     pi -p --no-extensions -e <needed> -e <needed>
+ *
+ * That is what this module computes. The needed set is DERIVED from the tool
+ * allowlist the caller already passes, so least privilege falls out with no new
+ * vocabulary for the model to get wrong, and every future lifetime-breaking
+ * package is excluded by default rather than by name.
+ *
+ * Pure: no fs, no env. Path materialization lives in index.ts.
+ */
+
+/**
+ * Tools pi provides with `--no-extensions`. Verified empirically:
+ *   pi -p --no-extensions "list your tools" -> read, bash, edit, write
+ * A builtin needs no extension, so it never counts as unmapped.
+ */
+export const BUILTIN_TOOLS = ["read", "bash", "edit", "write"];
+
+/** Marker spec meaning "this extension's own package" (for allow_nested). */
+export const SELF_SPEC = "self";
+
+/** Split "xai/grok-4.5" -> "xai". Returns undefined when there is no provider. */
+export function providerOf(model) {
+    if (typeof model !== "string") return undefined;
+    const i = model.indexOf("/");
+    return i > 0 ? model.slice(0, i) : undefined;
+}
+
+/** Normalize a config value that may be a single spec or a list of them. */
+function toSpecList(value) {
+    if (typeof value === "string") return value.trim() ? [value.trim()] : [];
+    if (Array.isArray(value)) return value.filter((s) => typeof s === "string" && s.trim()).map((s) => s.trim());
+    return [];
+}
+
+/** Parse a comma/space separated tool allowlist into unique bare names. */
+export function toolList(tools) {
+    if (!tools) return [];
+    const out = [];
+    for (const raw of String(tools).split(",")) {
+        const t = raw.trim();
+        if (t && !out.includes(t)) out.push(t);
+    }
+    return out;
+}
+
+/**
+ * Decide the child's extension set.
+ *
+ * @param {object} a
+ * @param {string} [a.tools]        Tool allowlist (comma form) the child will get.
+ * @param {string} [a.model]        Model as "provider/id" — pulls in provider auth.
+ * @param {boolean} [a.clean]       Hermetic builtins-only child.
+ * @param {boolean} [a.allowNested] Child may spawn its own subagents.
+ * @param {object} [a.config]       Extension config (toolExtensions, providerExtensions, inheritExtensions).
+ * @returns {{mode: "isolated"|"clean"|"inherit", specs: string[], unmapped: string[], reasons: Record<string,string[]>}}
+ *   mode     — "isolated" passes --no-extensions + explicit -e (the default);
+ *              "clean" passes --no-extensions with no -e;
+ *              "inherit" passes neither (operator opt-out, NOT model-selectable).
+ *   specs    — extension specs to load, deduped, in a stable order.
+ *   unmapped — requested tools that are neither builtin nor mapped to an
+ *              extension. They simply will not exist in the child; surfaced so
+ *              the human sees it instead of the child silently lacking a tool.
+ *   reasons  — spec -> what pulled it in, for the spawn diagnostic.
+ */
+export function resolveExtensions(a = {}) {
+    const cfg = a.config ?? {};
+    const specs = [];
+    const reasons = {};
+    const add = (spec, why) => {
+        if (!spec) return;
+        if (!specs.includes(spec)) specs.push(spec);
+        (reasons[spec] ??= []).push(why);
+    };
+
+    // allow_nested is honored in every mode: it is an explicit caller request,
+    // and without our own package loaded the child has no subagent tools at all.
+    if (a.allowNested) add(SELF_SPEC, "allow_nested");
+
+    if (cfg.inheritExtensions === true) {
+        return { mode: "inherit", specs: [], unmapped: [], reasons: {} };
+    }
+    if (a.clean === true) {
+        return { mode: "clean", specs, unmapped: [], reasons };
+    }
+
+    const toolMap = cfg.toolExtensions ?? {};
+    const unmapped = [];
+    for (const tool of toolList(a.tools)) {
+        if (BUILTIN_TOOLS.includes(tool)) continue;
+        const mapped = toSpecList(toolMap[tool]);
+        if (mapped.length === 0) {
+            if (!unmapped.includes(tool)) unmapped.push(tool);
+            continue;
+        }
+        for (const spec of mapped) add(spec, `tool:${tool}`);
+    }
+
+    // Model auth is not tool-shaped: xai/grok needs pi-xai-oauth loaded or the
+    // child cannot authenticate at all, whatever tools it was granted.
+    const provider = providerOf(a.model);
+    if (provider) {
+        for (const spec of toSpecList((cfg.providerExtensions ?? {})[provider])) {
+            add(spec, `provider:${provider}`);
+        }
+    }
+
+    return { mode: "isolated", specs, unmapped, reasons };
+}
+
+/**
+ * Build the pi CLI flags for a resolution. `resolvePath` maps a spec to an
+ * on-disk path (or undefined when the package is not installed); unresolvable
+ * specs are reported rather than silently dropped.
+ *
+ * @returns {{args: string[], missing: string[]}}
+ */
+export function extensionArgs(resolution, resolvePath) {
+    if (resolution.mode === "inherit") return { args: [], missing: [] };
+    const args = ["--no-extensions"];
+    const missing = [];
+    for (const spec of resolution.specs) {
+        const path = resolvePath(spec);
+        if (!path) { missing.push(spec); continue; }
+        args.push("--extension", path);
+    }
+    return { args, missing };
+}

package/extensions.ts

@@ -0,0 +1,19 @@
+/**
+ * TypeScript re-export of extensions.mjs pure helpers.
+ * Logic lives in extensions.mjs for ESM unit-test compatibility (mirrors widget.ts).
+ */
+export {
+    BUILTIN_TOOLS,
+    SELF_SPEC,
+    providerOf,
+    toolList,
+    resolveExtensions,
+    extensionArgs,
+} from "./extensions.mjs";
+
+export interface ExtensionResolution {
+    mode: "isolated" | "clean" | "inherit";
+    specs: string[];
+    unmapped: string[];
+    reasons: Record<string, string[]>;
+}