pi-umbra 0.2.0 → 0.3.0

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/bar.ts

@@ -0,0 +1,229 @@
+import { CustomEditor, type ExtensionAPI, type ExtensionContext, type KeybindingsManager, type Theme } from "@earendil-works/pi-coding-agent";
+import { Editor, isKeyRelease, matchesKey, type Component, type EditorTheme, type TUI, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { faded, layoutList, MARK, MAX_ROWS, renderKey, renderLines } from "./bar/bar-line.ts";
+import type { RunState } from "./skills/delegate/state.ts";
+
+// Part 3: everything the widget slot below the input box draws, and the ways it opens into the
+// full panel of reference 1.
+//
+// One shape, the way Claude Code draws it: `○ main` on top, one row per agent, `└` for a nested
+// one, and `❯` on the row the user is on. Down at the end of the editor moves the `❯` into the
+// list, ↑↓ walk it, enter opens the panel on that agent, and up past the first agent, esc or
+// any other key hands the keyboard back to the editor.
+//
+// The widget is mounted once at session_start and never removed. It asks for belowEditor, and
+// repatch.mjs moves that slot below pi's status line. The slot grows a Spacer(1) the moment it holds anything, so registering and
+// unregistering it moves the input box by a row;
+// and setWidget disposes and rebuilds its component on every call, so calling it per tick would
+// be a per-tick rebuild. Register the factory once, then requestRender().
+//
+// The string[] form of setWidget is unusable here twice over: it is wrapped in a Text that
+// word-wraps a long line into two rows and yields nothing at all for a blank one, and it is
+// capped at 10 lines. Only the factory form is handed `width`, which is what makes every
+// truncation in bar/bar-line.ts possible.
+//
+// Every column of the frame itself is in bar/bar-line.ts, down to and including the string
+// concatenation, because bar.check.ts cannot import this file: `CustomEditor` is a value from
+// pi's own package, and loading that package pulls in an experimental server module that is not
+// installed. What is left here is the part a check could not have run anyway — a component, an
+// editor subclass, and four registrations.
+
+const BAR_KEY = "agent-bar";
+// Rows the list leaves to the editor, the status line and pi's own footer on a short terminal.
+const RESERVE = 6;
+
+class BarComponent implements Component {
+	constructor(
+		private tui: TUI,
+		private theme: Theme,
+		private onOpen: (stem?: string) => void,
+	) {}
+
+	// The stems the last frame drew, in order: the cursor only walks rows the user can see.
+	private stems: string[] = [];
+	private release: (() => void) | undefined;
+
+	render(width: number): string[] {
+		// terminal.rows only changes on a resize, which repaints everything anyway, so reading
+		// it per frame costs nothing and keeps the list inside a shrunk window.
+		const budget = Math.max(1, Math.min(MAX_ROWS, this.tui.terminal.rows - RESERVE));
+		const now = Date.now();
+		this.stems = layoutList(width - MARK, current, now, budget).flatMap((row) => (row.branch ? [row.branch.stem] : []));
+		// A row that left the list (the run faded, the panel took over) takes the cursor with it.
+		if (cursor && !this.stems.includes(cursor)) this.leave();
+		return renderLines(width, current, now, budget, (color, text) => this.theme.fg(color, text), panelOpen, cursor);
+	}
+
+	/** Down at the end of the editor: the `❯` moves onto the first agent. The keys go through an
+	 *  input listener rather than a focus change, because the editor keeps its text, its cursor
+	 *  and its focus while the user looks down the list. */
+	enter(): void {
+		if (this.release || panelOpen || !this.stems[0]) return;
+		cursor = this.stems[0];
+		this.release = this.tui.addInputListener((data) => this.key(data));
+		this.refresh();
+	}
+
+	private leave(): void {
+		cursor = undefined;
+		this.release?.();
+		this.release = undefined;
+		this.refresh();
+	}
+
+	private key(data: string): { consume: boolean } | undefined {
+		// Listeners see key releases before pi filters them, and a release of the ↓ that opened
+		// the list would move the cursor a second row.
+		if (isKeyRelease(data)) return undefined;
+		// A dialog that took the editor's slot (ask_user_question) owns the keys now, and the
+		// panel opening over it would leave its promise hanging.
+		if (panelOpen || !(this.tui.getFocusedComponent() instanceof Editor)) {
+			this.leave();
+			return undefined;
+		}
+		const index = this.stems.indexOf(cursor ?? "");
+		if (matchesKey(data, "down")) cursor = this.stems[Math.min(index + 1, this.stems.length - 1)];
+		else if (matchesKey(data, "up")) {
+			if (index <= 0) this.leave();
+			else cursor = this.stems[index - 1];
+		} else if (matchesKey(data, "enter") || matchesKey(data, "right")) {
+			const stem = cursor;
+			this.leave();
+			this.onOpen(stem);
+		} else if (matchesKey(data, "escape")) this.leave();
+		else {
+			// Typing goes on where it was: the key reaches the editor as if the list were not there.
+			this.leave();
+			return undefined;
+		}
+		this.refresh();
+		return { consume: true };
+	}
+
+	// Mouse reporting is only on in the alternate-screen TUI (tuiMode "fullscreen"). Clicks are
+	// routed by position, not focus, so a click while another dialog holds the editor slot
+	// (ask_user_question, a select) would swap that dialog out and leave its promise hanging:
+	// the bar only opens the panel while an editor has focus.
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (event.type !== "click" || panelOpen || !current) return undefined;
+		if (!(this.tui.getFocusedComponent() instanceof Editor)) return undefined;
+		this.onOpen();
+		return { handled: true };
+	}
+
+	invalidate(): void {
+		// Nothing is cached between frames: render() reads the snapshot fresh every time.
+	}
+
+	// setWidget disposes the old bar on every session_start; its listener must not outlive it.
+	dispose(): void {
+		this.leave();
+	}
+
+	refresh(): void {
+		// Never requestRender(true). That calls resetRenderState(), which forces a repaint of
+		// the whole screen instead of the changed band — which is the flicker.
+		this.tui.requestRender();
+	}
+}
+
+// Down is not ours to steal outright: it moves the cursor, walks prompt history and drives the
+// autocomplete list. It belongs to the bar only when the editor would do nothing with it —
+// cursor already parked at the end of the last visual line — so the editor is asked rather than
+// second-guessed. Its wrap map is private and re-deriving it would drift the first time pi
+// changes its wrapping; a no-op cannot drift. registerShortcut("down") is not an option: the
+// dispatcher consumes a matched key session-wide, history and autocomplete included.
+class BarEditor extends CustomEditor {
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		private keys: KeybindingsManager,
+		private onDownAtEnd: () => void,
+	) {
+		super(tui, theme, keys);
+	}
+
+	handleInput(data: string): void {
+		// With the autocomplete list open, down moves the highlight and changes neither the text
+		// nor the cursor, so the probe below would misread it as a no-op.
+		if (!this.keys.matches(data, "tui.editor.cursorDown") || this.isShowingAutocomplete()) {
+			super.handleInput(data);
+			return;
+		}
+		const text = this.getText();
+		const before = this.getCursor();
+		super.handleInput(data);
+		const after = this.getCursor();
+		if (this.getText() === text && after.line === before.line && after.col === before.col) this.onDownAtEnd();
+	}
+}
+
+let current: RunState | undefined;
+let panelOpen = false;
+let bar: BarComponent | undefined;
+let lastKey = "";
+// The stem the `❯` is on while the list has the keyboard; undefined leaves it on `○ main`.
+let cursor: string | undefined;
+
+/** The bar holds no state and owns no timer: the reader that already polls `<cwd>/.pi-out` for
+ *  the panel calls this every tick, so the two views can never disagree about the same run and
+ *  only one thing is ever walking the disk. */
+export const setRun = (run: RunState | undefined) => {
+	current = run;
+	const key = renderKey(run, Date.now());
+	if (key === lastKey) return;
+	lastKey = key;
+	bar?.refresh();
+};
+
+export const installBar = (pi: ExtensionAPI, openPanel: (ctx: ExtensionContext, stem?: string) => Promise<void> | void) => {
+	// `quiet` is the down arrow and the click: both fire whether or not a run exists, and a
+	// notification on every press of a key the user meant as "move the cursor" is noise. The
+	// command and the shortcut were typed on purpose, so those get told why nothing happened.
+	const open = (ctx: ExtensionContext, quiet = false, stem?: string) => {
+		if (panelOpen) return quiet ? undefined : ctx.ui.notify("agent panel is already open");
+		// Opening on nothing would draw an empty box the user cannot fill. The quiet doors also
+		// skip a run the bar has already let go of: a key meant as "move the cursor" should not
+		// bring back a run that finished minutes ago. The command and alt+a still open it.
+		if (!current || (quiet && faded(current, Date.now()))) {
+			return quiet ? undefined : ctx.ui.notify("no agent run in this directory");
+		}
+		panelOpen = true;
+		bar?.refresh();
+		void Promise.resolve(openPanel(ctx, stem)).finally(() => {
+			panelOpen = false;
+			bar?.refresh();
+		});
+	};
+
+	// umbra-inputbar's editor announces a down at the end on pi's event bus. pi keeps one editor
+	// per session and does not sort extensions before loading them (under bun the order is the
+	// filesystem's), so a second editor class of our own would win or lose at random. The event
+	// works whichever loads first; the subscription is dropped by pi on /reload.
+	pi.events.on("editor:down-at-end", () => bar?.enter());
+
+	pi.on("session_start", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		// Re-registered on every session_start, including the "reload" one that follows
+		// resetExtensionUI() clearing every widget and the custom editor. Once per session is
+		// not once per tick: each call disposes the old component and builds a new one.
+		ctx.ui.setWidget(
+			BAR_KEY,
+			(tui, theme) => {
+				bar = new BarComponent(tui, theme, (stem) => open(ctx, true, stem));
+				return bar;
+			},
+			{ placement: "belowEditor" },
+		);
+		// Fallback for a setup without umbra-inputbar: then this editor does the same probe
+		// itself. With umbra-inputbar present its editor is kept, and the event above is the way
+		// in. Only one editor is ever live, so the panel cannot be asked to open twice.
+		if (ctx.ui.getEditorComponent()) return;
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => new BarEditor(tui, theme, keybindings, () => bar?.enter()));
+	});
+
+	// Not ctrl+<letter>: every one is already bound by pi, and extension shortcuts are matched
+	// before app keybindings, so one would silently shadow a built-in.
+	pi.registerShortcut("alt+a", { description: "Open the agent panel", handler: (ctx) => open(ctx) });
+	pi.registerCommand("umb-agents", { description: "Open the agent panel", handler: async (_args, ctx) => open(ctx) });
+};

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/fan/index.ts

@@ -0,0 +1,141 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { installBar, setRun } from "../bar.ts";
+import { openPanel, type PanelSource } from "../panel.ts";
+import { canReach, describeOffer, fanSettings, forget, offerModels, reachableModels, RUN_SH, type Offer } from "./models.ts";
+import { findBlock, parseSpec, TEMPLATE, type RunSpec } from "./spec.ts";
+import { piCommand, reportOf, store } from "./store.ts";
+import type { RunState } from "../skills/delegate/state.ts";
+
+// Wiring only. store.ts owns the branches, bar.ts and panel.ts render them.
+//
+// Three ways in, all free: `/umb-fan` for the user, a fenced ```fan block in the model's own
+// answer, and a bash call that turns out to be the delegate skill — the same run directory
+// either way, so the panel does not care which one started it. No pi.registerTool anywhere,
+// so the prompt is byte-for-byte unchanged.
+
+// A branch that stopped on a question goes to the model first: most questions are answered by
+// the conversation the branch never saw, and only the rest reach the user.
+const askingNote = (run: RunState): string => {
+	const asking = run.branches.filter((branch) => branch.report === "ASKING");
+	if (!asking.length) return "";
+	return (
+		`\n\n${asking.map((branch) => branch.stem).join(", ")} stopped on a question. Answer it from this ` +
+		"conversation if you can; if only the user can decide, ask them with ask_user_question first. " +
+		"Then continue each one in a single bash call and read its new report:\n\n" +
+		`. '${RUN_SH}'; ${asking.map((branch) => `dresume '${run.dir}' ${branch.stem} '<answer>'`).join("; ")}; wait; ` +
+		asking.map((branch) => `cat '${run.dir}/${branch.stem}.md'`).join("; ")
+	);
+};
+
+// A branch starts with --no-extensions, so a model that only an extension provides is not there
+// for it. Rather than guess another one, the model asks the user: which model to spend on is
+// theirs to choose.
+const modelNote = (missing: string[], offer: Offer): string =>
+	`The fan run did not start: branches run without extensions, so ${missing.join(", ")} is not ` +
+	"available to them. Ask the user with ask_user_question which model the branches should use, " +
+	`offering ${describeOffer(offer)}. Then write the fan block again with \`label@provider/model\` ` +
+	"on each branch.";
+
+const modelOf = (ctx: ExtensionContext) =>
+	process.env.FAN_MODEL || (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "");
+
+// The one adapter between the producer and the two renderers. store keys a branch by its
+// stem because that is its filename; the panel hands back the whole BranchView it drew,
+// because a row it did not draw must not be stoppable. Converting here keeps both sides
+// honest instead of widening either signature to meet the other.
+const source: PanelSource = {
+	run: () => store.run(),
+	stop: (branch) => void store.stop(branch.stem),
+	subscribe: (fn) => store.subscribe(fn),
+};
+
+export default function (pi: ExtensionAPI) {
+	// The widget above the editor, the alt+a shortcut, the /umb-agents command and the down arrow
+	// out of the last editor line. All four open the same panel over the same source.
+	installBar(pi, (ctx, stem) => openPanel(ctx, source, stem));
+	// The bar is pushed to rather than polling a second time: store already ticks once a
+	// second while branches are live, and a second reader could only disagree with it.
+	store.subscribe(() => setRun(store.run()));
+
+	// The run directory this session started, and has therefore promised to report back on.
+	// A run the delegate skill started in bash is left alone: that caller reads $run/*.md
+	// itself, and a follow-up would hand the model the same text twice.
+	let awaiting: string | undefined;
+
+	// Branches must not outlive the pi that started them: nothing would be watching, and a
+	// branch left running keeps spending. Their reports are already on disk.
+	pi.on("session_shutdown", () => store.stopAll());
+
+	// A bash call may be the delegate skill mid-run. Arming the tick when one starts is what
+	// makes a skill-started run appear on the bar from its first frame rather than at the end;
+	// the turn's end disarms it, because no bash call outlives its turn.
+	pi.on("tool_execution_start", (event, ctx) => {
+		if (event.toolName === "bash") store.arm(ctx.cwd);
+	});
+	pi.on("agent_end", () => store.disarm());
+	pi.on("session_start", (_event, ctx) => store.watch(ctx.cwd));
+
+	// Every branch's model is checked before anything is seeded. A model a branch cannot reach
+	// stops the run here, with the user told and, for a run the model asked for, the model asked
+	// to get a choice from the user. Returns the run directory, or undefined when nothing started.
+	const launch = async (spec: RunSpec, ctx: ExtensionContext, brief: string, reply: boolean) => {
+		const settings = await fanSettings();
+		const fallback = modelOf(ctx);
+		const reachable = await reachableModels(piCommand(), settings.load);
+		const wanted = [...new Set(spec.phases.flatMap((phase) => phase.branches.map((branch) => branch.model || fallback)))];
+		// An empty listing means pi could not be asked, not that nothing is reachable.
+		const missing = reachable.length ? wanted.filter((model) => !canReach(model, reachable)) : [];
+		if (missing.length) {
+			// The user may fix it with /login or models.json before the retry.
+			forget(settings.load);
+			const offer = offerModels(ctx.cwd, reachable);
+			ctx.ui.notify(`fan: ${missing.join(", ")} is not available to branches; pick ${describeOffer(offer)}`, "warning");
+			if (reply) pi.sendUserMessage(modelNote(missing, offer), { deliverAs: "followUp" });
+			return undefined;
+		}
+		const dir = store.start(spec, fallback, ctx.cwd, brief, settings);
+		if (!dir) ctx.ui.notify("fan: a run is already in flight — stop it from the panel first", "warning");
+		return dir;
+	};
+
+	pi.on("message_end", (event, ctx) => {
+		if (ctx.mode !== "tui" || event.message.role !== "assistant") return;
+		const text = event.message.content
+			.filter((part) => part.type === "text")
+			.map((part) => part.text)
+			.join("\n");
+		const block = findBlock(text);
+		if (!block) return;
+		const spec = parseSpec(block);
+		// The whole assistant message, not just the fenced block: the reasoning around the
+		// block is the half a branch cannot reconstruct from its own task line.
+		// Caught here: a throw after the awaits (a read-only cwd, a full disk) is no longer inside
+		// pi's handler, and an unhandled rejection can take pi down with it.
+		if (spec)
+			launch(spec, ctx, text, true)
+				.then((dir) => (awaiting = dir ?? awaiting))
+				.catch((error: unknown) => ctx.ui.notify(`fan: ${error instanceof Error ? error.message : String(error)}`, "error"));
+	});
+
+	// The branches' answers come back as a follow-up rather than as a tool result: the turn
+	// that asked for them already ended, so the model reads them at the top of the next one.
+	store.subscribe(() => {
+		const run = store.run();
+		if (!run || run.dir !== awaiting || run.live) return;
+		awaiting = undefined;
+		pi.sendUserMessage(`Branch results for ${run.name}:\n\n${reportOf(run)}${askingNote(run)}`, { deliverAs: "followUp" });
+	});
+
+	pi.registerCommand("umb-fan", {
+		description: "Run parallel pi branches and watch them in the agent panel",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const text = args.trim() || (await ctx.ui.editor("fan", TEMPLATE));
+			if (!text) return;
+			const spec = parseSpec(text);
+			if (!spec) return ctx.ui.notify("fan: no branches in that spec", "warning");
+			// Started by the user, so the results are theirs to read on the panel; the model is
+			// only told about a run it asked for itself. launch says why when nothing started.
+			await launch(spec, ctx, text, false);
+		},
+	});
+}

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/fan/models.ts

@@ -0,0 +1,137 @@
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Which models a branch can run on, checked before a run starts. A branch is `pi -p
+// --no-extensions`, so a model that only an extension provides is not there for it unless $LOAD
+// puts that extension back. Checking first costs one `--list-models` per session; finding out
+// afterwards cost a started run of failed branches, read back from pi's error text.
+
+export type FanSettings = { load: string[]; timeoutMs: number };
+export type Offer = { from: "scoped" | "free" | "reachable"; models: string[] };
+
+export const RUN_SH = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "delegate", "run.sh");
+
+const run = (command: string, args: string[], timeout: number) =>
+	new Promise<string>((resolve) =>
+		execFile(command, args, { timeout, maxBuffer: 4 << 20, windowsHide: true }, (_error, stdout) => resolve(stdout ?? "")),
+	);
+
+/** The environment alone: what a caller with no bash, and the check, get. */
+export const envSettings = (load = "", timeout = ""): FanSettings => ({
+	load: (process.env.FAN_LOAD ?? load).split(/\s+/).filter(Boolean),
+	timeoutMs: Number(process.env.FAN_TIMEOUT_MS) || Number(timeout) * 1000 || 300_000,
+});
+
+/** $LOAD and $DELEGATE_TIMEOUT through run.sh's own dconfig, so fan and the delegate skill
+ *  read one set of files the same way. FAN_LOAD and FAN_TIMEOUT_MS win. */
+export const fanSettings = async (): Promise<FanSettings> => {
+	const script = '. "$1"; dconfig; printf "%s\\n%s" "$LOAD" "$DELEGATE_TIMEOUT"';
+	const [load = "", timeout = ""] = (await run("bash", ["-c", script, "fan", RUN_SH], 5_000)).split("\n");
+	return envSettings(load, timeout);
+};
+
+// One listing per extension set. A failed listing is not kept, and forget() drops one after a
+// refusal, so a /login or a models.json edit is seen on the next try.
+const listings = new Map<string, Promise<string[]>>();
+
+export const forget = (load: string[]) => listings.delete(load.join(" "));
+
+/** `provider/id` for every model a branch started with `load` can reach. Empty when the listing
+ *  failed, which the caller reads as "cannot tell", never as "nothing is reachable". */
+export const reachableModels = (pi: string[], load: string[]): Promise<string[]> => {
+	const key = load.join(" ");
+	if (!listings.has(key)) {
+		const [command, ...prefix] = pi;
+		const listing = run(command as string, [...prefix, "--no-extensions", "--no-skills", ...load, "--list-models"], 60_000).then((out) => {
+			const models = parseListing(out);
+			if (!models.length) listings.delete(key);
+			return models;
+		});
+		listings.set(key, listing);
+	}
+	return listings.get(key) as Promise<string[]>;
+};
+
+/** The table after its `provider model ...` header. Anything a LOAD extension printed while
+ *  loading comes before the header, so it is skipped rather than read as a provider. */
+export const parseListing = (out: string): string[] => {
+	const lines = out.split("\n").map((line) => line.trim().split(/\s+/));
+	const header = lines.findIndex(([first, second]) => first === "provider" && second === "model");
+	return header === -1
+		? []
+		: lines
+				.slice(header + 1)
+				.filter((cells) => cells.length > 1)
+				.map(([provider, model]) => `${provider}/${model}`);
+};
+
+const THINKING = /:(off|minimal|low|medium|high|xhigh|max)$/i;
+
+/** pi's own rule, loosely: a known model, an id some provider lists as is (`anthropic/x` under
+ *  openrouter), any id under a known provider (pi then runs it as a custom id and only warns),
+ *  or a bare name that some known id contains. */
+export const canReach = (model: string, reachable: string[]): boolean => {
+	const id = model.replace(THINKING, "").toLowerCase();
+	const known = reachable.map((entry) => entry.toLowerCase());
+	if (known.includes(id) || known.some((entry) => entry.slice(entry.indexOf("/") + 1) === id)) return true;
+	const slash = id.indexOf("/");
+	if (slash > 0) return known.some((entry) => entry.startsWith(`${id.slice(0, slash)}/`));
+	return known.some((entry) => entry.includes(id));
+};
+
+/** An `enabledModels` entry against the list, the way pi reads them: exact, glob or fuzzy,
+ *  case-insensitive, with an optional thinking suffix. */
+const matches = (pattern: string, reachable: string[]): string[] => {
+	const bare = pattern.replace(THINKING, "").toLowerCase();
+	if (bare.includes("*")) {
+		const glob = new RegExp(`^${bare.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "i");
+		return reachable.filter((entry) => glob.test(entry) || glob.test(entry.slice(entry.indexOf("/") + 1)));
+	}
+	const exact = reachable.filter((entry) => entry.toLowerCase() === bare || entry.toLowerCase().endsWith(`/${bare}`));
+	return exact.length ? exact : reachable.filter((entry) => entry.toLowerCase().includes(bare));
+};
+
+/** What to offer instead: the user's scoped models (global, then project settings) that a
+ *  branch can reach; else the free ones it can reach; else the first few it can reach. */
+export const offerModels = (cwd: string, reachable: string[]): Offer => {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+	const scoped = [join(agentDir, "settings.json"), join(cwd, ".pi", "settings.json")]
+		.flatMap((file) => {
+			try {
+				return (JSON.parse(readFileSync(file, "utf8")).enabledModels as string[] | undefined) ?? [];
+			} catch {
+				return [];
+			}
+		})
+		.flatMap((pattern) => matches(pattern, reachable));
+	if (scoped.length) return { from: "scoped", models: [...new Set(scoped)].slice(0, 6) };
+	const free = reachable.filter((model) => model.endsWith(":free"));
+	return free.length ? { from: "free", models: free.slice(0, 6) } : { from: "reachable", models: reachable.slice(0, 6) };
+};
+
+export const describeOffer = (offer: Offer): string =>
+	offer.models.length
+		? `${{ scoped: "from your scoped models", free: "free models", reachable: "models a branch can reach" }[offer.from]}: ${offer.models.join(", ")}`
+		: "no model a branch can reach was found (`pi --no-extensions --list-models` shows them)";
+
+// The matching rules above against a fixed listing, so a drift from pi's resolver shows here.
+const demo = () => {
+	const reachable = parseListing(
+		"loading provider...\nprovider    model                 context\nopenrouter  anthropic/claude-x    200K\nopenrouter  nvidia/nemo:free      128K\nanthropic   claude-opus-5         1M\n",
+	);
+	console.assert(reachable.length === 3 && reachable[0] === "openrouter/anthropic/claude-x", `listing: ${reachable}`);
+	console.assert(canReach("anthropic/claude-x", reachable), "an id a provider lists under a slash");
+	console.assert(canReach("anthropic/claude-opus-5:high", reachable), "thinking suffix");
+	console.assert(canReach("anthropic/custom-id", reachable), "custom id under a known provider");
+	console.assert(canReach("opus-5", reachable), "bare name");
+	console.assert(!canReach("openai/gpt-5", reachable), "unknown provider");
+	console.assert(matches("openrouter/*", reachable).length === 2, "glob");
+	console.assert(matches("claude-opus-5:high", reachable)[0] === "anthropic/claude-opus-5", "exact with a suffix");
+	console.assert(parseListing("no table here").length === 0, "no header is no listing");
+	console.log("models.ts ok");
+};
+
+if (process.argv[1]?.endsWith("models.ts")) demo();

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/fan/spec.ts

@@ -0,0 +1,88 @@
+import type { RunSpec } from "./store.ts";
+
+// The one text format a run is described in. `/umb-fan` opens it in an editor, and the fan
+// skill tells the model to emit the same thing in a ```fan block, so there is one parser
+// and no schema for the model to get wrong.
+//
+//   name: pi-toolcall-render
+//   desc: Map how pi renders tool calls
+//   # Map
+//   core-render: Read the render path and report where a tool call becomes lines.
+//   omp-intercept@openai/gpt-5: Check whether an extension can override it.
+//   # Design
+//   proposal: Given the Map phase, write the design.
+//
+// Phases run in order; every branch inside one phase runs at the same time.
+
+export const TEMPLATE = ["name: ", "desc: ", "# Phase one", "label: task", ""].join("\n");
+
+export const parseSpec = (text: string): RunSpec | undefined => {
+	const spec: RunSpec = { name: "", description: "", phases: [] };
+	for (const raw of text.split("\n")) {
+		const line = raw.trim();
+		if (!line || line.startsWith("//")) continue;
+		if (line.startsWith("#")) {
+			spec.phases.push({ title: line.replace(/^#+\s*/, "") || `Phase ${spec.phases.length + 1}`, branches: [] });
+			continue;
+		}
+		// A task is full of colons (file:line, URLs), so the key ends at the first one. A model id
+		// can carry colons too (`openrouter/x:free`, `openai/gpt-5:high`), so a key with `@` ends
+		// at the first colon followed by a space instead, falling back to the first colon.
+		const spaced = line.search(/:(\s|$)/);
+		const colon = /^[^:\s]+@/.test(line) && spaced !== -1 ? spaced : line.indexOf(":");
+		if (colon === -1) continue;
+		const key = line.slice(0, colon).trim();
+		const value = line.slice(colon + 1).trim();
+		if (!value) continue;
+		if (key === "name") spec.name = value;
+		else if (key === "desc") spec.description = value;
+		else {
+			// A branch before any "#" gets an implicit first phase, so the common
+			// single-phase run needs no header at all.
+			const phase = spec.phases[spec.phases.length - 1] ?? pushPhase(spec, "Branches");
+			const [label, model] = key.split("@");
+			if (label) phase.branches.push({ label, model, task: value });
+		}
+	}
+	spec.phases = spec.phases.filter((phase) => phase.branches.length > 0);
+	if (!spec.phases.length) return undefined;
+	if (!spec.name) spec.name = spec.phases[0]?.branches[0]?.label ?? "run";
+	return spec;
+};
+
+const pushPhase = (spec: RunSpec, title: string) => {
+	const phase = { title, branches: [] as { label: string; model?: string; task: string }[] };
+	spec.phases.push(phase);
+	return phase;
+};
+
+/** The fenced block the fan skill tells the model to write. */
+export const findBlock = (text: string) => /```fan\s*\n([\s\S]*?)```/.exec(text)?.[1];
+
+// One check for the two things that are easy to get wrong: a colon inside a task, and a
+// branch written before any phase header.
+const demo = () => {
+	const spec = parseSpec(`
+name: toolcall
+desc: Map how pi renders tool calls
+lone: Read tui.d.ts:68 and report.
+# Design
+plan@openai/gpt-5: Write it up.
+free@openrouter/nvidia/nemotron-3-super-120b-a12b:free: Check src/a.ts:12.
+`);
+	if (!spec) throw new Error("parseSpec returned undefined for a valid spec");
+	console.assert(spec.name === "toolcall", "name");
+	console.assert(spec.description === "Map how pi renders tool calls", "desc");
+	console.assert(spec.phases.length === 2, `expected 2 phases, got ${spec.phases.length}`);
+	console.assert(spec.phases[0]?.title === "Branches", "implicit first phase");
+	console.assert(spec.phases[0]?.branches[0]?.task === "Read tui.d.ts:68 and report.", "colon in task");
+	console.assert(spec.phases[1]?.branches[0]?.model === "openai/gpt-5", "per-branch model");
+	const free = spec.phases[1]?.branches[1];
+	console.assert(free?.model === "openrouter/nvidia/nemotron-3-super-120b-a12b:free", "colon in model");
+	console.assert(free?.task === "Check src/a.ts:12.", "task after a model with a colon");
+	console.assert(parseSpec("name: empty") === undefined, "a spec with no branches is not a run");
+	console.assert(findBlock("blah\n```fan\nx: y\n```\nblah") === "x: y\n", "block extraction");
+	console.log("spec.ts ok");
+};
+
+if (process.argv[1]?.endsWith("spec.ts")) demo();