pi-daddy 0.28.0 → 0.32.0

package/dist/kernel/run-child.js

@@ -0,0 +1,324 @@
+/**
+ * Run a governed child process under hard limits.
+ *
+ * G8 (review findings A-R1/B-I5, A-R3). `delegate` used to spawn `pi` with no output cap, no timeout,
+ * an abort listener attached too late to observe an already-aborted signal, and a non-zero exit reported
+ * to the model as an ordinary result. Each of those is a way for a child to outlive or overwhelm the
+ * orchestrator that is supposed to be governing it — which is the whole premise of this package.
+ *
+ * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
+ */
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { parseBound } from "./propagation.js";
+import { ENV_CHILD_IDLE_TIMEOUT, ENV_CHILD_TIMEOUT } from "./env-names.js";
+export { ENV_CHILD_IDLE_TIMEOUT, ENV_CHILD_TIMEOUT } from "./env-names.js";
+const TEST_CONTROL = Symbol.for("pi-daddy.internal.run-child-test-control");
+function currentRunChildTestControl() {
+    if (process.env.NODE_TEST_CONTEXT !== "child-v8")
+        return undefined;
+    const storage = globalThis[TEST_CONTROL];
+    return storage?.getStore();
+}
+/**
+ * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
+ *
+ * Both halves matter. Truncating by `String.prototype.slice` counts UTF-16 code units against a byte budget,
+ * which overruns by the encoding width of whatever the child printed. Truncating the *buffer* instead would
+ * respect the budget and split a multi-byte character or a surrogate pair, putting a lone `\ud83d` in the
+ * result. So the walk is by code POINT (`for…of` iterates code points, keeping surrogate pairs whole) and the
+ * budget is checked in bytes before each one is admitted.
+ *
+ * Exported for the test that feeds it CJK and emoji: an ASCII-only test cannot fail on any of this, which is
+ * exactly why the original defect survived a test named for it.
+ */
+export function takeBytes(text, budget) {
+    if (budget <= 0)
+        return "";
+    if (Buffer.byteLength(text) <= budget)
+        return text;
+    let out = "";
+    let used = 0;
+    for (const character of text) {
+        const size = Buffer.byteLength(character);
+        if (used + size > budget)
+            break;
+        out += character;
+        used += size;
+    }
+    return out;
+}
+/**
+ * Operator override for the child wall-clock limit, in seconds.
+ *
+ * Deliberately NOT in `GRANT_ENV_KEYS`: those are stripped from a child's environment and re-supplied
+ * only by the spawn plan, which is right for capability state and wrong for an operator preference. This
+ * one should simply inherit, so a bound set at the root applies all the way down.
+ */
+/** Read the override, falling back to the default on absent *or* malformed input (G7's rule). */
+export function timeoutFromEnv(raw) {
+    const seconds = parseBound(raw);
+    // `null` (malformed) and `0` both fall back rather than disabling the limit: a timeout that can be
+    // switched off by a typo is the A-S4 defect wearing different clothes.
+    return seconds === undefined || seconds === null || seconds === 0 ? DEFAULT_TIMEOUT_MS : seconds * 1000;
+}
+/** The inactivity bound, same rule: absent, malformed and zero all select the default rather than disabling it. */
+export function idleTimeoutFromEnv(raw) {
+    const seconds = parseBound(raw);
+    return seconds === undefined || seconds === null || seconds === 0 ? DEFAULT_IDLE_TIMEOUT_MS : seconds * 1000;
+}
+/** 1 MiB. A delegation returns a summary; anything larger is a runaway, not an answer. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * Six hours (PR 3e, 2026-09-22). No longer the working bound: `DEFAULT_IDLE_TIMEOUT_MS` is what stops a hung child.
+ * This is the runaway ceiling for a child that keeps producing events forever, and it exists so that no typo in the
+ * inactivity variable can make a child unbounded. The history: ten minutes, twenty (ADR-0038), sixty (its note), each
+ * time because a working child was cut off by a wall clock that cannot tell working from hung.
+ */
+export const DEFAULT_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+/** Fifteen minutes with no stdout byte and no session-file change. A hung child is a silent one; a build is not. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
+export const DEFAULT_ACTIVITY_PROBE_INTERVAL_MS = 2000;
+/** Grace between SIGTERM and SIGKILL. A child that ignores SIGTERM must not make the timeout advisory. */
+export const DEFAULT_KILL_GRACE_MS = 5000;
+export function runChild(request) {
+    const testControl = currentRunChildTestControl();
+    const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const killGraceMs = request.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    const hardDeadlineAt = request.hardDeadlineAt;
+    // A-R3: checked BEFORE spawning. `AbortSignal` does not replay, so a listener attached after an
+    // `await` cannot observe an abort that already happened — and the child would then run to completion
+    // outside the cancellation that was supposed to stop it. Nothing is started at all here.
+    if (request.signal?.aborted) {
+        return Promise.resolve({ code: null, text: "", truncated: false, timedOut: false, aborted: true });
+    }
+    return new Promise((settle) => {
+        let child;
+        try {
+            child = spawn(request.command, request.args, {
+                env: request.env,
+                cwd: request.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            settle({ code: null, text: "", truncated: false, timedOut: false, aborted: false, spawnError: String(error) });
+            return;
+        }
+        try {
+            if (child.pid !== undefined)
+                request.onSpawn?.(child.pid);
+        }
+        catch (error) {
+            const failed = {
+                code: null,
+                text: "",
+                truncated: false,
+                timedOut: false,
+                aborted: false,
+                spawnError: String(error),
+            };
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.once("error", () => settle(failed));
+            child.once("close", () => settle(failed));
+            child.kill("SIGKILL");
+            return;
+        }
+        // One decoder for BOTH streams is deliberate: they are already interleaved into one `text`, and two
+        // decoders would each hold their own partial character, so a split byte could surface out of order.
+        const decoder = new StringDecoder("utf8");
+        let text = "";
+        let bytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        let idle = false;
+        let aborted = false;
+        let done = false;
+        const timers = [];
+        const clearTimers = () => timers.forEach(clearTimeout);
+        /** SIGTERM, then SIGKILL if the child is still alive — so a handler cannot ignore its way out. */
+        const stop = () => {
+            child.kill("SIGTERM");
+            timers.push(setTimeout(() => child.kill("SIGKILL"), killGraceMs));
+        };
+        // A timer phase may run before libuv delivers an exit that the OS already observed, especially after the
+        // controller event loop was blocked across the deadline. Give pending child-process events one turn to
+        // publish exitCode/signalCode before deciding that a governed PID is still live.
+        const controlIfRunning = (control) => {
+            setImmediate(() => {
+                if (done || child.exitCode !== null || child.signalCode !== null)
+                    return;
+                control();
+            });
+        };
+        /** How much of `text` the progress display has already been shown. */
+        let emittedUpTo = 0;
+        /**
+         * Stream whatever `text` has gained since the last call.
+         *
+         * **Derived from `text` rather than from the incoming chunk**, and that is the whole correctness argument:
+         * what gets streamed is then *by construction* a prefix of what gets returned, so the output cap bounds the
+         * parent's transcript exactly as it bounds the result. The first version emitted the raw chunk and pushed
+         * 1924 bytes through a 1024-byte cap on the truncating write — the cap bounded memory and not the screen
+         * it had just been extended to protect. Found by the test, not by reading it.
+         *
+         * Swallowing is deliberate: `onOutput` renders, and a renderer that throws must not become a way to kill a
+         * governed child. Nothing downstream depends on it having run.
+         */
+        const flush = () => {
+            if (!request.onOutput || text.length <= emittedUpTo)
+                return;
+            const chunk = text.slice(emittedUpTo);
+            emittedUpTo = text.length;
+            try {
+                request.onOutput(chunk);
+            }
+            catch {
+                /* display only */
+            }
+        };
+        const capture = (chunk) => {
+            if (truncated)
+                return;
+            // **Decoded through a StringDecoder, not `String(chunk)`.** A pipe splits on byte boundaries, not
+            // character ones, so a multi-byte character straddling two `data` events was decoded as two invalid
+            // halves and became U+FFFD — in the child's ANSWER, not merely the display. Measured: 300,000 bytes of
+            // CJK produced **twelve** replacement characters, because 65536 % 3 == 1. Emoji happened to survive
+            // (65536 % 4 == 0), which is why width-dependent corruption went unnoticed. The decoder holds the
+            // partial bytes until the rest arrives.
+            const s = decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+            if (s.length === 0)
+                return;
+            const size = Buffer.byteLength(s);
+            if (bytes + size > maxOutputBytes) {
+                // Keep what fits, mark it, and stop the child: an unbounded producer must not be able to exhaust the
+                // orchestrator's memory just because it was granted a tool that prints.
+                //
+                // **Trimmed by BYTES, and that is a fix rather than a refinement.** This was
+                // `text.slice(0, maxOutputBytes)` — a count of UTF-16 code units against a budget measured in bytes,
+                // so any non-ASCII output overran the cap by its own encoding width: 300 bytes of CJK through a
+                // 100-byte cap, and a measured **2048 bytes through the real 1024 default**. It is the same defect as
+                // the 1924-byte one already fixed here, one layer down: that fix bounded the *unit* count, and the
+                // budget was never in units. An odd cap also split a surrogate pair, putting a lone `\ud83d` into
+                // both the transcript and the returned answer.
+                text += takeBytes(s, maxOutputBytes - bytes);
+                bytes = maxOutputBytes;
+                truncated = true;
+                flush();
+                stop();
+                return;
+            }
+            bytes += size;
+            text += s;
+            flush();
+        };
+        const observe = (stream, chunk) => {
+            armIdle();
+            capture(chunk);
+            try {
+                request.onObservation?.(stream, chunk);
+            }
+            catch {
+                /* observation only */
+            }
+        };
+        child.stdout?.on("data", (chunk) => observe("stdout", chunk));
+        child.stderr?.on("data", (chunk) => observe("stderr", chunk));
+        for (const stream of ["stdout", "stderr"])
+            child[stream]?.on("end", () => {
+                try {
+                    request.onStreamEnd?.(stream);
+                }
+                catch {
+                    /* passive observation only */
+                }
+            });
+        timers.push(setTimeout(() => controlIfRunning(() => {
+            timedOut = true;
+            stop();
+        }), timeoutMs));
+        // The inactivity bound. Re-armed by every output byte and by every probe change; a child that is working but
+        // quiet on stdout (a build, a long tool call) keeps its session file growing, and that is enough.
+        let idleTimer;
+        function armIdle() {
+            if (request.idleTimeoutMs === undefined || done)
+                return;
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => controlIfRunning(() => {
+                timedOut = true;
+                idle = true;
+                stop();
+            }), request.idleTimeoutMs);
+        }
+        armIdle();
+        let probeTimer;
+        if (request.idleTimeoutMs !== undefined && request.activityProbe) {
+            let lastMarker;
+            let probing = false;
+            probeTimer = setInterval(() => {
+                if (probing || done)
+                    return;
+                probing = true;
+                void Promise.resolve()
+                    .then(() => request.activityProbe?.())
+                    .then((marker) => {
+                    if (marker !== undefined && marker !== lastMarker) {
+                        lastMarker = marker;
+                        armIdle();
+                    }
+                })
+                    .catch(() => undefined) // an unreadable probe is "no activity seen", never a control decision
+                    .finally(() => {
+                    probing = false;
+                });
+            }, request.activityProbeIntervalMs ?? DEFAULT_ACTIVITY_PROBE_INTERVAL_MS);
+        }
+        const activeHardDeadlineAt = testControl?.hardDeadlineAtAfterSpawn() ?? hardDeadlineAt;
+        if (activeHardDeadlineAt !== undefined) {
+            // Independent of the soft timer and measured from the recorded epoch, not from `spawn`: neither a
+            // delayed soft callback nor spawn/setup time may start a fresh grace period beyond the lifecycle bound.
+            timers.push(setTimeout(() => controlIfRunning(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }), Math.max(0, activeHardDeadlineAt - Date.now())));
+        }
+        const onAbort = () => {
+            aborted = true;
+            stop();
+        };
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimers();
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            if (probeTimer)
+                clearInterval(probeTimer);
+            request.signal?.removeEventListener("abort", onAbort);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            settle(result);
+        };
+        child.on("error", (error) => finish({
+            code: null,
+            text,
+            truncated,
+            timedOut,
+            ...(idle ? { idle: true } : {}),
+            aborted,
+            spawnError: String(error),
+        }));
+        // `close` waits for every inherited pipe, including one retained by a detached grandchild. Once the
+        // governed PID exits, allow a short drain and settle anyway so timeout/output bounds remain bounds.
+        child.on("exit", (code, signal) => {
+            timers.push(setTimeout(() => finish({ code, signal, text, truncated, timedOut, ...(idle ? { idle: true } : {}), aborted }), 100));
+        });
+        child.on("close", (code, signal) => finish({ code, signal, text, truncated, timedOut, ...(idle ? { idle: true } : {}), aborted }));
+    });
+}
+//# sourceMappingURL=run-child.js.map

package/dist/kernel/run-child.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-child.js","sourceRoot":"","sources":["../../src/kernel/run-child.ts"],"names":[],"mappings":"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"}

package/dist/kernel/skill-packages.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Setup discovers enabled Pi resources in place through its package resolver. Configured packages
+ * are never copied into another autoload root. For legacy npm installs unregistered with Pi only,
+ * the explicit package.json pi.skills declaration remains a scaffold source (ADR-0074).
+ * Names, ceilings and bytes are checked before they can enter the generated shell grant.
+ */
+import { type SkillDefinition } from "./definitions.ts";
+import { isSafeCapability } from "./capabilities.ts";
+export interface DiscoveredSkill {
+    definition: SkillDefinition;
+    /** The file verbatim. `init` copies it rather than regenerating it, so nothing is lost in a round trip. */
+    text: string;
+    path: string;
+    /** Already enabled by Pi; setup must reference it rather than making a competing copy. */
+    referenced?: boolean;
+}
+/** Why a declared skill was refused before it could be planned. Each has a different fix. */
+export type RefusalReason = 
+/** The name cannot be a capability id, a line in a sourced file, or a path segment. */
+"unsafe-name"
+/** A declared `allowed-tools` entry cannot be one either — R-78, the sibling of R-77. */
+ | "unsafe-capability"
+/** The declaration claims `tool:*` or `agent:*`: root authority, which a package may not hand itself. */
+ | "wildcard"
+/** The bytes are not valid UTF-8, so "copied verbatim" could not be honoured. */
+ | "not-utf8";
+export interface RefusedSkill {
+    /** The `pi.skills` entry or the definition name, whichever the operator can act on. */
+    subject: string;
+    reason: RefusalReason;
+    /** The offending id(s), when the reason names any. */
+    detail: string[];
+}
+export interface SkillPackage {
+    name: string;
+    version: string;
+    /** Paths `pi.skills` named that could not be read as a `SKILL.md`, so the report can say so out loud. */
+    unreadable: string[];
+    /** Skills refused for a reason that would otherwise reach a generated file. Never silently dropped. */
+    refused: RefusedSkill[];
+    skills: DiscoveredSkill[];
+}
+/**
+ * May this definition's name be written into a capability id, a shell file and a path?
+ *
+ * **Measured before it was written, and it was a defect in this module's first version (R-77).** A
+ * definition's identity is its directory name, and `init` interpolates that name into three places at once:
+ * `agent:<name>` inside a **comma-separated** `PI_DADDY_GRANT`, a `.pi/grants.env` an operator **sources**,
+ * and the path it writes the copy to. An installed package with a directory called `a,tool:bash` produced
+ *
+ * ```
+ * export PI_DADDY_GRANT="agent:a,tool:bash,tool:delegate,tool:read"
+ * ```
+ *
+ * — `tool:bash` in an operator's grant, declared by nobody. A quote character reaches a file that gets
+ * `source`d, and a name of `..` writes outside `.pi/skills/`. One rule closes all three, and it is
+ * deliberately a **whitelist**: the safe set here is small and the unsafe set is the rest of Unicode.
+ *
+ * The first character must be alphanumeric, so `..` and dotfiles are refused along with everything else.
+ */
+export declare function isSafeName(name: string): boolean;
+/**
+ * May this DECLARED capability id be written into the generated grant? — R-78.
+ *
+ * **R-77's other half, and the reason a whitelist beats a blocklist twice.** R-77 was closed on the name
+ * channel; the `allowed-tools` *value* travels to the identical interpolation site and was unchecked, so a
+ * package declaring
+ *
+ * ```yaml
+ * allowed-tools: Read,ext:x";touch /tmp/pwned;PI_DADDY_GRANT="
+ * ```
+ *
+ * produced a `.pi/grants.env` that executed arbitrary code the moment the operator ran the `source` line
+ * `init` itself prints. Reproduced end to end before this existed. `ceilingForDefinition` passes `ext:`,
+ * `skill:` and `agent:` entries through **as written** by design (a translation table would invent or drop
+ * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
+ * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
+ *
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`,
+ * `workspace:<id>`, and `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused
+ * separately and loudly, because "you tried to grant yourself everything" is a different fact from "that is
+ * not a name".
+ *
+ * `workspace:` was absent until 2026-08-21, so the boundary that GENERATES grants could not emit the one
+ * capability ADR-0035's breaking change made mandatory: a package needing to route was reported as declaring
+ * something that "is not a name". A namespace has to be added here as well as to the enforcing path, and
+ * that is the whole lesson of the review this came out of.
+ */
+export { isSafeCapability };
+/** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
+export declare function readSkillPackage(packageDir: string): Promise<SkillPackage | null>;
+/**
+ * Every installed package under `<cwd>/node_modules` that declares `pi.skills`, sorted by name.
+ *
+ * Top level and one scope deep, which is what npm's layout has. Nothing recurses into a dependency's own
+ * `node_modules`: a transitive skill package is not something an operator asked to install definitions
+ * from, and scaffolding one into their project would be a surprise wearing a helpful face.
+ */
+/**
+ * Every place a pi package can be installed, most specific first (R-75).
+ *
+ * **Two roots, because pi has two install paths and only one of them is `npm install`.** `pi install
+ * npm:principal-pi-skills` — the documented, pi-native way, and the only one that registers the package so
+ * pi will auto-load its extension — puts it in `$PI_CODING_AGENT_DIR/npm/node_modules`, and leaves the
+ * project without a `node_modules` at all. Searching only `<cwd>/node_modules` therefore found **nothing**
+ * for an operator who followed pi's own instructions, and said "install principal-pi-skills" to somebody
+ * who just had.
+ *
+ * Measured, in a fresh `PI_CODING_AGENT_DIR` with an empty project: `pi install` populates the agent root
+ * and creates no project root.
+ *
+ * Project first when both exist, because a package pinned in the repository is the one the team agreed on.
+ */
+export declare function skillPackageRoots(cwd: string): string[];
+export declare function discoverSkillPackages(cwd: string): Promise<SkillPackage[]>;
+//# sourceMappingURL=skill-packages.d.ts.map

package/dist/kernel/skill-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-packages.d.ts","sourceRoot":"","sources":["../../src/kernel/skill-packages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAIpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,2GAA2G;IAC3G,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa;AACvB,uFAAuF;AACrF,aAAa;AACf,yFAAyF;GACvF,mBAAmB;AACrB,yGAAyG;GACvG,UAAU;AACZ,iFAAiF;GAC/E,UAAU,CAAC;AAEf,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,sDAAsD;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,yGAAyG;IACzG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uGAAuG;IACvG,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,gBAAgB,EAAE,CAAC;AA+D5B,2GAA2G;AAC3G,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAkCvF;AAED;;;;;;GAMG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAGvD;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAwEhF"}