pi-umbra-subagents 0.1.0

package/extensions/umbra-subagents/skills/delegate/state.check.ts

@@ -0,0 +1,137 @@
+// The one runnable check for the producer. It builds a run directory by hand — two runs, a
+// half-built third, a nested branch, a timeout, a torn file and a leftover .tmp — and asserts
+// what the panel reads back out of it. It exists as a separate file so state.ts, which the
+// panel imports on every tick, never carries node:assert or a tmpdir fixture with it.
+//
+// Run it with:  bun run state.check.ts     (or: node --experimental-strip-types state.check.ts)
+// It never starts pi.
+
+import { strict as assert } from "node:assert";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import beacon, { describe } from "./beacon.ts";
+import { type BranchState, readRun } from "./state.ts";
+
+const NOW = 1_700_000_000_000;
+// Pids on Windows are small multiples of 4, so this one has never existed and process.kill
+// answers ESRCH for it. Verified on this machine before it was written down.
+const DEAD = 2_147_483_644;
+
+const seed = (stateDir: string, over: Partial<BranchState> & Pick<BranchState, "phase" | "name" | "index">) => {
+    const state: BranchState = {
+        parent: null,
+        model: "commandcode/minimax/minimax-m3-free",
+        pid: null,
+        status: "starting",
+        activity: "Starting",
+        tokens: null,
+        startedAt: NOW - 195_000,
+        updatedAt: NOW - 195_000,
+        report: null,
+        error: null,
+        ...over,
+    };
+    writeFileSync(join(stateDir, `${state.phase}-${state.name}.json`), JSON.stringify(state));
+};
+
+const run = (dir: string, name: string, phases: string[]) =>
+    writeFileSync(
+        join(dir, "run.json"),
+        JSON.stringify({ name, description: "Map how pi renders tool calls", cwd: dir, startedAt: NOW - 196_000, phases }),
+    );
+
+const cwd = mkdtempSync(join(tmpdir(), "delegate-check-"));
+assert.equal(readRun(cwd, NOW), undefined, "no .pi-out at all is not a run");
+
+const older = join(cwd, ".pi-out", "20260101-000000-older");
+const newest = join(cwd, ".pi-out", "20260101-010000-newest");
+const building = join(cwd, ".pi-out", "20260101-020000-building");
+for (const dir of [older, newest, building]) mkdirSync(join(dir, "state"), { recursive: true });
+
+run(older, "older", ["map"]);
+seed(join(older, "state"), { phase: "map", name: "leftover", index: 1 });
+
+run(newest, "newest", ["map", "design"]);
+const state = join(newest, "state");
+seed(state, { phase: "map", name: "core-render", index: 1, pid: process.pid, status: "running", tokens: 72_700, updatedAt: NOW - 53_000 });
+seed(state, { phase: "map", name: "omp-intercept", index: 2, pid: DEAD, status: "running", tokens: 89_600 });
+seed(state, { phase: "design", name: "review", index: 3, parent: "map-core-render" });
+seed(state, { phase: "map", name: "flicker", index: 4, pid: process.pid, status: "running" });
+writeFileSync(join(state, "map-flicker.exit"), "124");
+// Neither of these may ever become a row: one is a file we did not write, the other is the
+// unfinished half of a tmp + rename.
+writeFileSync(join(state, "map-broken.json"), "{oops");
+writeFileSync(join(state, "map-core-render.json.tmp"), "{");
+
+// The newest directory has no run.json yet, so the panel must fall through to the newest
+// complete run rather than blanking for a frame.
+seed(join(building, "state"), { phase: "map", name: "unseen", index: 1 });
+
+const view = readRun(cwd, NOW);
+assert.ok(view, "a complete run directory is a run");
+assert.equal(view.name, "newest", "newest run by name, never by mtime, and never a half-built one");
+assert.deepEqual(
+    view.branches.map((branch) => `${branch.stem}@${branch.depth}`),
+    ["map-core-render@0", "design-review@1", "map-omp-intercept@0", "map-flicker@0"],
+    "parents immediately above their children, siblings by launch index",
+);
+assert.equal(view.branches[0]?.label, "map:core-render", "the colon is a render-time join");
+assert.equal(view.total, 4, "the torn file and the .tmp are not rows");
+// core-render is alive (our own pid), review has not booted yet; omp-intercept's pid is gone
+// and flicker has an exit file, so both are finished without ever saying so themselves.
+assert.equal(view.done, 2, "a dead pid and an exit file both settle a branch that still reads 'running'");
+assert.equal(view.branches[1]?.settled, false, "a seeded branch with no pid yet is pending, not done");
+assert.equal(view.branches[3]?.timedOut, true, "exit code 124 is a timeout, not a crash");
+assert.equal(view.tokens, 162_300, "null token counts contribute nothing rather than a fake 0");
+assert.equal(view.branches[0]?.idleMs, 53_000, "idle is measured from updatedAt");
+assert.equal(view.activePhase, 0, "the first phase still holding an unsettled branch");
+assert.equal(view.live, true);
+
+// Finish the map phase and the sidebar marker has to move on by itself.
+seed(state, { phase: "map", name: "core-render", index: 1, pid: DEAD, status: "done", report: "OK", tokens: 72_700 });
+const advanced = readRun(cwd, NOW);
+assert.equal(advanced?.activePhase, 1, "the marker follows the first unsettled phase");
+assert.equal(advanced?.done, 3);
+assert.equal(advanced?.live, true, "the nested branch is still pending");
+
+assert.equal(describe("read", { path: "src/hooks.server.ts" }), "Reading hooks.server.ts");
+assert.equal(describe("grep", { pattern: "localStorage", path: "src/lib/office-persist.ts" }), "Grepping localStorage in office-persist.ts");
+assert.equal(describe("grep", { pattern: "localStorage", glob: "**/*.ts" }), "Grepping localStorage in **/*.ts");
+assert.equal(describe("grep", { pattern: "x".repeat(50) }), `Grepping ${"x".repeat(31)}…`, "a runaway pattern cannot widen the row");
+assert.equal(describe("find", { pattern: "**/*.svelte" }), "Finding **/*.svelte");
+assert.equal(describe("ls", {}), "Listing .", "a default argument still reads as a sentence");
+assert.equal(describe("bash", { command: "npm test -- --run" }), "Running npm");
+assert.equal(describe("read", {}), "read", "a missing argument falls back to the tool name");
+assert.equal(describe("web_search", { query: "pi extension api" }), "web_search pi extension api", "an unknown tool still names its subject");
+assert.equal(describe("edit", { file_path: "src/lib/office-persist.ts" }), "edit office-persist.ts", "a path-shaped argument shows as its basename");
+assert.equal(describe("web_search", {}), "web_search", "an unknown tool with nothing readable is named, not narrated");
+
+// The beacon itself, driven by hand. Two tool calls overlap and the older one outlives the
+// newer: clearing the sentence on the first `end` is the bug this asserts against, because it
+// leaves the row reading "Thinking" while the branch is still mid-grep.
+const handlers = new Map<string, (event: unknown, ctx: unknown) => void>();
+const branchFile = join(cwd, "branch.json");
+seed(cwd, { phase: "map", name: "beacon", index: 1 });
+writeFileSync(branchFile, readFileSync(join(cwd, "map-beacon.json"), "utf8"));
+process.env.PI_BRANCH_STATE = branchFile;
+// SAFETY: the beacon only ever calls pi.on, so this is the whole surface it uses.
+beacon({ on: (event: string, handler: (e: unknown, c: unknown) => void) => handlers.set(event, handler) } as never);
+const fire = (event: string, payload: unknown, ctx: unknown = {}) => handlers.get(event)?.(payload, ctx);
+
+fire("session_start", {}, { model: { name: "Opus 5" } });
+fire("tool_execution_start", { toolCallId: "a", toolName: "grep", args: { pattern: "localStorage", path: "src/lib/office-persist.ts" } });
+fire("tool_execution_start", { toolCallId: "b", toolName: "read", args: { path: "src/hooks.server.ts" } });
+fire("tool_execution_end", { toolCallId: "b", toolName: "read" });
+// Tool writes are coalesced at 100 ms, so the row is read after that window rather than inside it.
+await new Promise((resolve) => setTimeout(resolve, 200));
+const live = JSON.parse(readFileSync(branchFile, "utf8")) as BranchState;
+assert.equal(live.pid, process.pid, "the pid is pi's own, not the launching shell's");
+assert.equal(live.model, "Opus 5", "session_start replaces the requested id with the display name");
+assert.equal(live.activity, "Grepping localStorage in office-persist.ts", "an end clears its own call, never the row");
+
+fire("tool_execution_end", { toolCallId: "a", toolName: "grep" });
+await new Promise((resolve) => setTimeout(resolve, 200));
+assert.equal((JSON.parse(readFileSync(branchFile, "utf8")) as BranchState).activity, "Thinking", "with nothing running the row says so");
+
+console.log("state.check.ts ok");

package/extensions/umbra-subagents/skills/delegate/state.ts

@@ -0,0 +1,295 @@
+// What a delegate run looks like on disk, and the one function that folds a run directory
+// into the shape the agent panel renders. It ships inside the skill folder rather than
+// beside the panel because run.sh's seed heredoc and beacon.ts are its only two writers,
+// and a schema living next to its writers cannot drift away from them.
+//
+// Nothing here registers anything with pi, so importing it costs zero prompt tokens.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Scratch root, relative to the SESSION cwd. Already gitignored by the old delegate. */
+export const OUT_DIR = ".pi-out";
+
+/** How long the widget keeps showing a finished run before dropping back to `○ main`.
+ *  It lives here rather than in the renderer because the producer has to keep its clock
+ *  ticking for exactly this long after the last branch settles - two copies of this number
+ *  in two files is precisely the drift that froze the last frame on screen. */
+export const LINGER_MS = 30_000;
+
+// ---------- ON DISK ----------
+
+/** `<run>/run.json` — written once by the skill, AFTER every seed exists. Its absence is
+ *  what makes a half-built run directory invisible, so the panel's `M` in "N/M agents" is
+ *  final from the first frame it ever draws. */
+export type Run = {
+    name: string;
+    description: string;
+    /** Absolute session cwd, captured before the skill `cd`s into a subtree. */
+    cwd: string;
+    startedAt: number;
+    /** Sidebar order. A later wave appends. */
+    phases: string[];
+    /** The process that owns this run and is the only thing that will ever launch its
+     *  remaining phases. Without it a seed for a phase that never got to run is
+     *  indistinguishable from a branch that is about to boot, so one Ctrl-C left a directory
+     *  reporting `live: true` for ever. Absent in a run written before this field existed,
+     *  which reads as "cannot tell" and keeps the old behaviour. */
+    pid?: number | null;
+};
+
+/** `<run>/state/<phase>-<name>.json` — seeded by the skill with every field populated, then
+ *  written only by beacon.ts, always whole-object through tmp + rename.
+ *
+ *  The stem is `${phase}-${name}` and never carries a colon: a colon is illegal in an NTFS
+ *  filename. The `map:core-render` the panel shows is a render-time join, never a stored
+ *  string. Both halves match ^[a-z0-9][a-z0-9._-]*$, which is why the seed heredoc contains
+ *  no free text and cannot emit invalid JSON. */
+export type BranchState = {
+    phase: string;
+    name: string;
+    /** Stem of the branch that spawned this one, or null at the top level. Branches run with
+     *  `--tools read,grep,find,ls` and so cannot nest today; the field is here because the
+     *  panel's nesting marker needs it the moment one of them is given `bash`. */
+    parent: string | null;
+    /** 1-based launch order. The panel's ONLY sort key — never readdir order, never mtime. */
+    index: number;
+    /** Seed: the requested "provider/id". Beacon: pi's own display name, e.g. "Opus 5". */
+    model: string;
+    /** null in the seed, the real OS pid at session_start. */
+    pid: number | null;
+    status: "starting" | "running" | "done" | "error";
+    /** The whole point of the panel: a short present-tense sentence, rewritten at every tool
+     *  boundary. "Grepping localStorage in office-persist.ts", not "running". Never empty —
+     *  an empty string reflows the row. */
+    activity: string;
+    /** null until the provider reports usage; the panel renders an en dash rather than a
+     *  fake 0. Once non-null it is never written back to null or to 0. */
+    tokens: number | null;
+    /** The shell's launch instant, stamped before pi boots. */
+    startedAt: number;
+    /** Stamped on every beacon write. The only input to "idle Ns". */
+    updatedAt: number;
+    report: "OK" | "PARTIAL" | "NEED_STRONGER" | "ASKING" | null;
+    error: string | null;
+};
+
+// `<run>/state/<stem>.exit` holds `$?` from the launching subshell. Its presence means the
+// process is gone whatever the JSON still says, which is the only thing that catches a
+// branch killed before its extensions ever bound. "124" means `timeout 300` fired.
+//
+// Siblings, contract unchanged from the old delegate:
+//   <run>/<stem>.md   branch stdout, the report the parent session reads
+//   <run>/<stem>.err  branch stderr
+
+// ---------- WHAT THE PANEL CONSUMES ----------
+
+export type BranchView = BranchState & {
+    /** `${phase}-${name}`, the row key and the file stem. */
+    stem: string;
+    /** `${phase}:${name}`, what the panel prints. */
+    label: string;
+    /** 0 at the top level, 1 under a parent, and so on. Drives the nesting marker. */
+    depth: number;
+    elapsedMs: number;
+    idleMs: number;
+    exitCode: number | null;
+    timedOut: boolean;
+    alive: boolean;
+    /** Finished for any reason. The N in "N/M agents". */
+    settled: boolean;
+};
+
+export type RunState = {
+    dir: string;
+    name: string;
+    description: string;
+    startedAt: number;
+    phases: string[];
+    /** First phase still holding an unsettled branch; the last phase once everything is done. */
+    activePhase: number;
+    /** Pre-ordered: a parent immediately above its children, siblings by launch order. Render
+     *  top to bottom; the component never walks a tree. */
+    branches: BranchView[];
+    done: number;
+    total: number;
+    tokens: number;
+    live: boolean;
+};
+
+// ---------- READER ----------
+
+const stemOf = (state: BranchState) => `${state.phase}-${state.name}`;
+
+// EPERM means the pid exists and belongs to someone else, which is still "not dead". Only
+// ESRCH proves the branch is gone — and on Windows that is the sole signal, because stopping
+// a branch is TerminateProcess and it never gets to write "done" into its own file.
+export const pidLive = (pid: number): boolean => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        // SAFETY: process.kill only ever throws a system error; reading .code off anything
+        // else yields undefined, which falls through to "dead".
+        return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+};
+
+type Exit = { code: number | null; at: number };
+
+const readExit = (path: string): Exit | undefined => {
+    try {
+        // The mtime is the instant the process actually died, which beats updatedAt for
+        // elapsed time on a branch killed before the beacon ever wrote.
+        const at = statSync(path).mtimeMs;
+        const code = Number(readFileSync(path, "utf8").trim());
+        return { code: Number.isFinite(code) ? code : null, at };
+    } catch {
+        return undefined;
+    }
+};
+
+// Newest by name, not by mtime: the YYYYMMDD-HHMMSS prefix is monotonic, while a run
+// directory's mtime churns as its branches write and can flip the panel to another run
+// mid-flight. A directory with no run.json is still being built, so the previous complete
+// run stays on screen instead of the panel blanking for a frame.
+const latestRun = (cwd: string): { dir: string; run: Run } | undefined => {
+    let names: string[];
+    try {
+        names = readdirSync(join(cwd, OUT_DIR), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    } catch {
+        return undefined;
+    }
+    for (let i = names.length - 1; i >= 0; i--) {
+        // SAFETY: i is bounded by names.length, so the index is always populated.
+        const dir = join(cwd, OUT_DIR, names[i] as string);
+        try {
+            // SAFETY: run.json is written by run.sh through json(), which escapes the only
+            // two free-text fields, so it either parses to Run or throws into the catch.
+            const run = JSON.parse(readFileSync(join(dir, "run.json"), "utf8")) as Run;
+            if (Array.isArray(run.phases)) return { dir, run };
+        } catch {
+            // Half-built, hand-deleted, or from an older delegate. Try the one before it.
+        }
+    }
+    return undefined;
+};
+
+const readStates = (stateDir: string): BranchState[] => {
+    let files: string[];
+    try {
+        files = readdirSync(stateDir);
+    } catch {
+        return [];
+    }
+    const states: BranchState[] = [];
+    for (const file of files) {
+        // ".json.tmp" deliberately fails this test: it is the unfinished half of a
+        // tmp + rename write and must never be parsed.
+        if (!file.endsWith(".json")) continue;
+        try {
+            // SAFETY: same contract as run.json — the seed heredoc holds constrained
+            // identifiers only, so this parses to BranchState or throws.
+            states.push(JSON.parse(readFileSync(join(stateDir, file), "utf8")) as BranchState);
+        } catch {
+            // Not a seed we wrote. Dropping the row beats throwing inside a render loop.
+        }
+    }
+    return states;
+};
+
+// Depth-first by launch order, so a parent sits immediately above its children and the
+// component can render the list top to bottom.
+const order = (states: BranchState[]): { state: BranchState; depth: number }[] => {
+    const sorted = [...states].sort((a, b) => a.index - b.index);
+    const stems = new Set(sorted.map(stemOf));
+    const byParent = new Map<string, BranchState[]>();
+    for (const state of sorted) {
+        // A parent naming a branch that is not in this run is treated as a root, so a stale
+        // PI_BRANCH_PARENT hides no rows.
+        const key = state.parent !== null && stems.has(state.parent) ? state.parent : "";
+        const siblings = byParent.get(key);
+        if (siblings) siblings.push(state);
+        else byParent.set(key, [state]);
+    }
+
+    const out: { state: BranchState; depth: number }[] = [];
+    const seen = new Set<string>();
+    const walk = (key: string, depth: number) => {
+        if (depth > 8) return;
+        for (const state of byParent.get(key) ?? []) {
+            const stem = stemOf(state);
+            if (seen.has(stem)) continue;
+            seen.add(stem);
+            out.push({ state, depth });
+            walk(stem, depth + 1);
+        }
+    };
+    walk("", 0);
+    // Anything the walk could not reach — a hand-edited parent cycle, a stem nested deeper
+    // than the cap — still gets a row. A branch the panel cannot see is worse than one drawn
+    // at the top level.
+    for (const state of sorted) {
+        const stem = stemOf(state);
+        if (seen.has(stem)) continue;
+        seen.add(stem);
+        out.push({ state, depth: 0 });
+    }
+    return out;
+};
+
+/** The whole panel-facing surface. One readdir, one run.json and one small JSON per branch:
+ *  cheap enough for a 1 s tick, which the panel needs anyway because elapsed and "idle Ns"
+ *  move with the clock rather than with the files. */
+export function readRun(cwd: string, now = Date.now()): RunState | undefined {
+    const found = latestRun(cwd);
+    if (!found) return undefined;
+
+    // Written by whoever owns the run. `undefined` is a run.json from before the field
+    // existed: unknowable, so treat it as still owned and keep the previous behaviour.
+    const orphaned = typeof found.run.pid === "number" && !pidLive(found.run.pid);
+
+    const stateDir = join(found.dir, "state");
+    const branches: BranchView[] = order(readStates(stateDir)).map(({ state, depth }) => {
+        const stem = stemOf(state);
+        const exit = readExit(join(stateDir, `${stem}.exit`));
+        // A seeded branch whose pid is still null has not booted yet: it is pending, not
+        // finished, or every row would count as done the instant the run started. Pending is
+        // only honest while the owner is still around to launch it — an abandoned run's later
+        // phases would otherwise read as alive for ever and pin the whole run to `live`.
+        const alive = exit === undefined && (state.pid === null ? !orphaned : pidLive(state.pid));
+        const settled = !alive || state.status === "done" || state.status === "error";
+        const endedAt = exit?.at ?? (settled ? state.updatedAt : now);
+        return {
+            ...state,
+            stem,
+            label: `${state.phase}:${state.name}`,
+            depth,
+            elapsedMs: Math.max(0, endedAt - state.startedAt),
+            idleMs: Math.max(0, now - state.updatedAt),
+            exitCode: exit?.code ?? null,
+            timedOut: exit?.code === 124,
+            alive,
+            settled,
+        };
+    });
+
+    const phases = found.run.phases;
+    const running = phases.findIndex((phase) => branches.some((b) => b.phase === phase && !b.settled));
+    return {
+        dir: found.dir,
+        name: found.run.name,
+        description: found.run.description,
+        startedAt: found.run.startedAt,
+        phases,
+        activePhase: running >= 0 ? running : Math.max(0, phases.length - 1),
+        branches,
+        done: branches.filter((b) => b.settled).length,
+        total: branches.length,
+        tokens: branches.reduce((sum, b) => sum + (b.tokens ?? 0), 0),
+        live: branches.some((b) => b.alive),
+    };
+}

package/extensions/umbra-subagents/skills/fan/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: fan
+description: Fan independent read-only work out to parallel pi branches and watch them live in the agent panel. Use whenever a task splits into 2+ lookups that do not need each other, or when the user writes "fan", "delegate", "subagent", or "in parallel".
+---
+
+# Fan
+
+There is no subagent tool and nothing is added to this prompt. A branch is a
+separate `pi -p` process the fan extension spawns and owns; each one writes a
+small live state file, so the panel above the input box shows what every branch
+is doing while it does it, not only what it concluded.
+
+## Run
+
+Write one fenced `fan` block at the end of your message and stop. The extension
+starts the branches when the message ends, and the answers arrive as a follow-up
+message at the top of the next turn. Do not run bash for this, and do not write
+anything after the block.
+
+````
+```fan
+name: toolcall-render
+desc: Map how pi renders tool calls
+# Map
+core-render: Read <paths> and report where a tool call becomes lines. Cite file:line.
+omp-intercept: Check whether an extension can override it. Cite file:line.
+# Design
+proposal: Given the Map results, write the design.
+```
+````
+
+- `name` and `desc` are the panel header. `# Title` starts a phase.
+- `label: task` is one branch. Phases run in order; branches inside a phase run
+  at the same time. Use a second phase only when it genuinely needs the first
+  phase's answers.
+- `label@provider/model: task` picks a model for that branch. Without it a
+  branch runs on this session's model.
+- 2 to 6 branches per phase. Each task names the files or directory and says
+  exactly what to return.
+
+## Rules
+
+- Branches are read-only: `read`, `grep`, `find`, `ls`, nothing else. Work that
+  edits files stays in this session.
+- A branch has an empty context. Repeating what you already know in the task
+  text is the only way it learns it.
+- One run at a time. A second block while a run is live is ignored.
+- Every branch writes its answer to `.pi-out/<run>/<phase>-<name>.md` as it goes,
+  and its errors to the matching `.err`. Quitting pi kills the branches, but what
+  they had already written stays on disk. `.pi-out/` is gitignored scratch.
+- A branch gets 5 minutes and is then cut off, so one wedged branch cannot
+  hold the run open. Keep each task small enough to finish in that time.

package/extensions/umbra-subagents.ts

@@ -0,0 +1,4 @@
+// The live agent view: a widget above the input box, a full-screen panel, and the fan producer
+// that feeds them. Everything is under ./umbra-subagents/; this file exists because pi scans
+// extensions/*.ts and the entry point is nested.
+export { default } from "./umbra-subagents/fan/index.ts";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-umbra-subagents",
+  "version": "0.1.0",
+  "description": "Parallel read-only pi branches with a live panel above the input box, the delegate skill that starts them, and /umb-loop, which resubmits a prompt on a count or a timer.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-skill",
+    "subagents",
+    "parallel",
+    "loop"
+  ],
+  "author": "grkn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grknbyk/pi-umbra.git",
+    "directory": "pi-umbra-subagents"
+  },
+  "homepage": "https://github.com/grknbyk/pi-umbra/tree/main/pi-umbra-subagents#readme",
+  "bugs": "https://github.com/grknbyk/pi-umbra/issues",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE",
+    "patch.mjs"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/umbra-subagents.ts",
+      "./extensions/umbra-loop.ts"
+    ],
+    "skills": [
+      "./extensions/umbra-subagents/skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/patch.mjs

@@ -0,0 +1,97 @@
+// /umb-loop needs one seam pi's extension API does not expose: the editor's own submit path,
+// which is the only way an extension can send a prompt the way the user does. This publishes it
+// as globalThis.__piSubmit. Run it after installing, and again after every pi update:
+//
+//   node <this file>           apply
+//   node <this file> --check   report only, write nothing, exit 1 if it is missing
+//
+// pi runs dist/bundle/cli.js, a self-contained bundle, and the chunk names are content-hashed,
+// so the patch finds its place by matching its own text rather than by line number.
+//
+// Nothing here is destructive. The patch is additive, text that no longer matches is reported
+// instead of forced, and reinstalling pi returns the bundle to stock. A pi upgrade replaces the
+// bundle and drops the patch silently, which is what --check is for.
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync, realpathSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// PI_UMBRA_PI points this at another pi tree. Otherwise the pi that runs is the one to patch:
+// the `pi` on PATH, followed through its symlink. Windows puts a .cmd shim there instead, so
+// npm's global root (%APPDATA%\npm\node_modules) comes next, then bun's. The copy npm installs
+// beside this package as a peer dependency is last: pi never runs it. The first that has a built
+// bundle wins.
+const resolvePi = () => {
+	if (process.env.PI_UMBRA_PI) return process.env.PI_UMBRA_PI;
+	const quiet = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 20_000 };
+	const candidates = [];
+	try {
+		const bin = execSync(process.platform === "win32" ? "where pi" : "command -v pi", quiet).split(/\r?\n/)[0].trim();
+		for (let dir = dirname(realpathSync(bin)); dir !== dirname(dir); dir = dirname(dir)) candidates.push(dir);
+	} catch {}
+	try {
+		const root = execSync("npm root -g", quiet).trim();
+		if (root) candidates.push(join(root, "@earendil-works", "pi-coding-agent"));
+	} catch {}
+	candidates.push(join(homedir(), ".bun", "install", "global", "node_modules", "@earendil-works", "pi-coding-agent"));
+	try {
+		candidates.push(dirname(createRequire(import.meta.url).resolve("@earendil-works/pi-coding-agent/package.json")));
+	} catch {}
+	return candidates.find((dir) => existsSync(join(dir, "dist", "bundle"))) ?? candidates[0];
+};
+
+const BUNDLE = join(resolvePi(), "dist/bundle");
+if (!existsSync(BUNDLE)) {
+	console.error(`no pi bundle at ${BUNDLE} - set PI_UMBRA_PI to your pi install`);
+	process.exit(1);
+}
+
+const PATCHES = [
+	{
+		// The extension API cannot submit a prompt, so /umb-loop borrows the editor's own path.
+		reason: "publish the editor submit handler for /umb-loop",
+		from: "this.setupEditorSubmitHandler(),",
+		to: "this.setupEditorSubmitHandler(),globalThis.__piSubmit=text=>this.defaultEditor.onSubmit?.(text),",
+	},
+];
+
+const files = [join(BUNDLE, "cli.js"), ...readdirSync(join(BUNDLE, "chunks")).map((name) => join(BUNDLE, "chunks", name))];
+const CHECK = process.argv.includes("--check");
+const unapplied = [];
+const gone = [];
+
+for (const patch of PATCHES) {
+	let done = false;
+	for (const path of files) {
+		const source = readFileSync(path, "utf8");
+		// A multi-line patch is written with newline escapes; match whatever line ending the file uses.
+		const eol = source.includes("\r\n") ? "\r\n" : "\n";
+		const from = patch.from.split("\n").join(eol);
+		const to = patch.to.split("\n").join(eol);
+		if (source.includes(to)) {
+			if (!CHECK) console.log(`already patched: ${patch.reason}`);
+			done = true;
+			break;
+		}
+		if (!source.includes(from)) continue;
+		if (CHECK) {
+			unapplied.push(patch.reason);
+			done = true;
+			break;
+		}
+		writeFileSync(path, source.replace(from, to));
+		console.log(`patched: ${patch.reason}`);
+		done = true;
+		break;
+	}
+	// Neither the original text nor the patched text is there, so pi changed the code this
+	// patch names. Report it rather than force anything.
+	if (!done) gone.push(patch.reason);
+}
+
+for (const reason of unapplied) console.log(`NOT APPLIED: ${reason}`);
+for (const reason of gone) console.log(`SEAM GONE:   ${reason}`);
+const bad = unapplied.length + gone.length;
+console.log(bad ? `${bad} of ${PATCHES.length} not in place` : `all ${PATCHES.length} patches applied`);
+process.exit(bad ? 1 : 0);