@arhen/pi-core-subagent 1.3.2 → 1.3.4

package/README.md

@@ -1,6 +1,7 @@
 # @arhen/pi-core-subagent
 
 [![npm version](https://img.shields.io/npm/v/%40arhen%2Fpi-core-subagent?color=cb3837&logo=npm)](https://www.npmjs.com/package/@arhen/pi-core-subagent)
+[![CI](https://img.shields.io/github/actions/workflow/status/arhen/pi-core-subagent/ci.yml?branch=main&logo=github&label=CI)](https://github.com/arhen/pi-core-subagent/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://github.com/earendil-works/pi)
 
@@ -234,7 +235,7 @@ Background + intercom:
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (default off) |
+| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (background runs only; default off) |
 | `subagent_status` | live per-task snapshot (non-blocking), including each child's session file path |
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |

package/package.json

@@ -1,48 +1,56 @@
 {
-  "name": "@arhen/pi-core-subagent",
-  "version": "1.3.2",
-  "type": "module",
-  "description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
-  "license": "MIT",
-  "main": "./src/index.ts",
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "pi",
-    "pi-coding-agent",
-    "pi-extension",
-    "pi-package",
-    "subagent",
-    "agent-orchestration",
-    "task-graph",
-    "dag",
-    "graph-protocol"
-  ],
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.2",
-    "@earendil-works/pi-agent-core": "^0.84.2",
-    "@earendil-works/pi-coding-agent": "^0.84.2",
-    "@earendil-works/pi-tui": "^0.84.2",
-    "typebox": "^1.3.14"
-  },
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "typescript": "^7.0.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/arhen/pi-core-subagent.git"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
+	"name": "@arhen/pi-core-subagent",
+	"version": "1.3.4",
+	"type": "module",
+	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
+	"license": "MIT",
+	"main": "./src/index.ts",
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"format": "biome format --write .",
+		"check": "bun run typecheck && bun run lint && bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"pi",
+		"pi-coding-agent",
+		"pi-extension",
+		"pi-package",
+		"subagent",
+		"agent-orchestration",
+		"task-graph",
+		"dag",
+		"graph-protocol"
+	],
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "^0.84.2",
+		"@earendil-works/pi-agent-core": "^0.84.2",
+		"@earendil-works/pi-coding-agent": "^0.84.2",
+		"@earendil-works/pi-tui": "^0.84.2",
+		"typebox": "^1.3.14"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.8",
+		"@types/bun": "^1.3.14",
+		"typescript": "^7.0.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/arhen/pi-core-subagent.git"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
 }

package/src/child.ts

@@ -14,14 +14,8 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import type { MailboxMessage } from "./mailbox.ts";
 
-export interface MailboxMessage {
-	from: string;
-	text: string;
-	at: number;
-}
-
-/** Child talk tools injected when allowIntercom: true. */
 export const CHILD_TALK_TOOLS = ["ask_parent", "notify_parent", "send_agent_message", "poll_agent_messages"] as const;
 
 export interface ChildHandlers {
@@ -57,7 +51,8 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 		{
 			name: "notify_parent",
 			label: "Notify Parent",
-			description: "Send a non-blocking message to the parent agent (a finding, a risk, a heads-up). Your run continues immediately; the parent sees it on its next turn.",
+			description:
+				"Send a non-blocking message to the parent agent (a finding, a risk, a heads-up). Your run continues immediately; the parent sees it on its next turn.",
 			promptSnippet: "Send the parent a non-blocking update or finding.",
 			parameters: Type.Object({
 				message: Type.String({ description: "The message content for the parent" }),
@@ -76,13 +71,21 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 				"Send a non-blocking message to another subagent in this run (delivered to its mailbox; it will see it via poll_agent_messages). Use 'leader' to message the parent instead. Messages are small and bounded — no long transcripts.",
 			promptSnippet: "Send a short message to a sibling subagent or the leader.",
 			parameters: Type.Object({
-				to: Type.String({ description: "Target task id of another subagent in this run (e.g. task_2), or 'leader' for the parent agent" }),
+				to: Type.String({
+					description: "Target task id of another subagent in this run (e.g. task_2), or 'leader' for the parent agent",
+				}),
 				message: Type.String({ description: "Short message content (keep under ~500 chars)" }),
 			}),
 			async execute(_toolCallId, params) {
 				const { to, message } = params as { to: string; message: string };
 				if (!handlers.onSendMessage(taskId, to, message)) {
-					return { content: [{ type: "text" as const, text: `Unknown target '${to}'. Use a sibling task id in this run or 'leader'.` }], isError: true, details: {} };
+					return {
+						content: [
+							{ type: "text" as const, text: `Unknown target '${to}'. Use a sibling task id in this run or 'leader'.` },
+						],
+						isError: true,
+						details: {},
+					};
 				}
 				return { content: [{ type: "text" as const, text: "Sent." }], details: {} };
 			},
@@ -90,17 +93,16 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 		{
 			name: "poll_agent_messages",
 			label: "Poll Agent Messages",
-			description: "Check your mailbox for messages from sibling subagents. Returns and clears all pending messages. Call it before acting on assumptions about other agents' results.",
+			description:
+				"Check your mailbox for messages from sibling subagents. Returns and clears all pending messages. Call it before acting on assumptions about other agents' results.",
 			promptSnippet: "Check for messages from other subagents.",
 			parameters: Type.Object({}),
 			async execute() {
 				const messages = handlers.onPollMailbox(taskId);
 				if (messages.length === 0) return { content: [{ type: "text" as const, text: "No messages." }], details: {} };
-				const body = messages
-					.map((m) => `from ${m.from}: ${m.text}`)
-					.join("\n");
+				const body = messages.map((m) => `from ${m.from}: ${m.text}`).join("\n");
 				const capped = body.length > 4000 ? body.slice(0, 4000).replace(/[\uD800-\uDBFF]$/, "") : body; // multibyte-safe
-				return { content: [{ type: "text" as const, text: body }], details: { messages } };
+				return { content: [{ type: "text" as const, text: capped }], details: { messages } };
 			},
 		},
 	];

package/src/format.ts

@@ -0,0 +1,237 @@
+/** Rendering: task lines, usage, the widget, summaries, notices.
+ *  Pure + theme-aware — no manager state, no pi runtime. */
+
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	MAX_TASKS,
+	type RunSnapshot,
+	type RunStatus,
+	type TaskSnapshot,
+	type TaskStatus,
+	TERMINAL,
+	type UsageStats,
+} from "./types.ts";
+
+/** Cap on a single child's final output (and on full-run summaries). */
+export const FINAL_OUTPUT_CAP = 24 * 1024;
+
+export function truncateText(text: string, max = FINAL_OUTPUT_CAP): string {
+	if (Buffer.byteLength(text, "utf8") <= max) return text;
+	let out = text.slice(0, max);
+	while (Buffer.byteLength(out, "utf8") > max) out = out.slice(0, -1); // multibyte-safe
+	return `${out}\n\n[Output truncated. Full child session is available in the session file.]`;
+}
+export function getFirstText(message: AssistantMessage): string {
+	for (const part of message?.content ?? []) {
+		if (part?.type === "text" && typeof part.text === "string") return part.text;
+	}
+	return "";
+}
+export function fmtTokens(n: number): string {
+	return n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k` : String(n);
+}
+export function formatUsage(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑ ${fmtTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓ ${fmtTokens(usage.output)}`);
+	if (usage.cost > 0) parts.push(usage.cost >= 0.0001 ? `$${usage.cost.toFixed(4)}` : "$<0.0001");
+	return parts.join(" · ");
+}
+export function statusIcon(status: TaskStatus | RunStatus): string {
+	if (status === "completed") return "✓";
+	if (status === "failed") return "✗";
+	if (status === "aborted") return "⏹";
+	if (status === "awaiting_parent") return "❓";
+	if (status === "queued") return "○";
+	return "•";
+}
+export function fmtDuration(ms: number | undefined): string {
+	if (ms === undefined || !Number.isFinite(ms)) return "–";
+	const s = Math.max(0, Math.round(ms / 1000));
+	return s >= 60 ? `${Math.floor(s / 60)}m${s % 60}s` : `${s}s`;
+}
+export function taskTimer(task: TaskSnapshot): string {
+	if (task.startedAt === undefined) return "–";
+	const end = task.endedAt ?? Date.now();
+	const running = !TERMINAL.includes(task.status);
+	return `${running ? "running " : ""}${fmtDuration(end - task.startedAt)}`;
+}
+export function taskStatsWithUsage(task: TaskSnapshot): string {
+	const stats = `${task.toolCalls ?? 0} tools`;
+	const usage = formatUsage(task.usage);
+	return `${stats}${usage ? ` · ${usage}` : ""}`;
+}
+export function taskLine(task: TaskSnapshot): string {
+	return `${statusIcon(task.status)} ${task.agent} · ${taskStatsWithUsage(task)} · ${taskTimer(task)}`;
+}
+/**
+ * Numbers take the theme's number color, everything else stays muted — like the footer.
+ * Must run on RAW text: styling an already-colored string rewrites the digits
+ * inside the ANSI escape codes themselves ("38;2;139;136;122m16 tools").
+ */
+export function colorNums(text: string, theme: Theme): string {
+	// A value keeps its unit: "460.6k" and "2m30s" each color as one token, not digit-by-digit.
+	return text.replace(/((?:\d+(?:\.\d+)?[a-zA-Z]*)+)|([^\d]+)/g, (_m, num?: string, rest?: string) =>
+		num ? theme.fg("syntaxNumber", num) : theme.fg("muted", rest ?? ""),
+	);
+}
+/**
+ * Themed one-liner. Finished tasks dim entirely (stats included); live tasks
+ * keep the agent name readable with themed numbers.
+ */
+export function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""): string {
+	const tail = `${taskStatsWithUsage(task)} · ${taskTimer(task)}`;
+	// Queued task with unmet needs: show the gate it's waiting on instead of empty stats.
+	const gate =
+		task.status === "queued" && task.needs?.length ? `${theme.fg("muted", `↳ waits ${task.needs.join(",")}`)} · ` : "";
+	if (TERMINAL.includes(task.status)) {
+		return theme.fg("dim", `${statusIcon(task.status)} ${task.agent} · ${tail}`);
+	}
+	return `${statusIcon(task.status)} ${task.agent} · ${gate}${activity}${colorNums(tail, theme)}`;
+}
+/**
+ * Human-readable activity line: "Read src/index.ts", "Grep wrapSingleLine".
+ * ponytail: picks the first interesting string arg instead of a per-tool table —
+ * unknown/custom tools then read fine too. Add a case only if one reads badly.
+ */
+// Order matters: the most specific arg wins (grep's pattern beats its path).
+export const ARG_KEYS = [
+	"pattern",
+	"query",
+	"command",
+	"path",
+	"file_path",
+	"filePath",
+	"url",
+	"name",
+	"subject",
+	"task",
+];
+export function describeCall(toolName: string, args: unknown, cwd?: string): string {
+	const verb = toolName.charAt(0).toUpperCase() + toolName.slice(1);
+	const obj = args && typeof args === "object" ? (args as Record<string, unknown>) : undefined;
+	if (!obj) return verb;
+	let value = ARG_KEYS.map((k) => obj[k]).find((v) => typeof v === "string" && v.trim() !== "") as string | undefined;
+	if (value === undefined) {
+		value = Object.values(obj).find((v) => typeof v === "string" && v.trim() !== "") as string | undefined;
+	}
+	if (value === undefined) return verb;
+	let text = value.replace(/\s+/g, " ").trim();
+	if (cwd && text.startsWith(`${cwd}/`)) text = text.slice(cwd.length + 1); // absolute paths inside the task cwd read as noise
+	return `${verb} ${text.length > 60 ? `${text.slice(0, 60)}…` : text}`;
+}
+export function activitySnippet(text: string): string {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length > 90 ? `${flat.slice(0, 90)}…` : flat;
+}
+/** Static compact lines (tool-result stream, subagent_status, /subagents). */
+export function compactLines(run: RunSnapshot): string[] {
+	const lines: string[] = [];
+	for (const task of run.tasks.slice(0, MAX_TASKS)) {
+		lines.push(taskLine(task));
+	}
+	if (run.tasks.length > MAX_TASKS) lines.push(`… +${run.tasks.length - MAX_TASKS} more`);
+	return lines;
+}
+/**
+ * Above-editor widget, todo-tree style:
+ *   ● Subagents (0/1)
+ *   ├─ • code-sleuth · 4 tools · 12s
+ *   │    → read src/auth.ts
+ *   └─ ✓ reviewer · 6 tools · 44s
+ * Static icons (no animation); latest activity + tool count + runtime per agent.
+ */
+export const WIDGET_MAX_LINES = 10;
+
+export class SubagentsWidget implements Component {
+	constructor(
+		private readonly getRuns: () => RunSnapshot[],
+		private readonly theme: Theme,
+	) {}
+
+	invalidate(): void {
+		// no cached strings; render() reads live state
+	}
+
+	render(width: number): string[] {
+		// ONE flat tree: every run's tasks concatenated under a single heading.
+		// Whether the model spawned N runs or one tasks[] call, the pane reads the same.
+		const runs = this.getRuns().filter((r) => r.tasks.length > 0);
+		if (runs.length === 0) return [];
+		const total = runs.reduce((n, r) => n + r.tasks.length, 0);
+		const done = runs.reduce((n, r) => n + r.tasks.filter((t) => TERMINAL.includes(t.status)).length, 0);
+		const live = total - done;
+		const head = live > 0 ? "accent" : "dim";
+		const lines = [
+			truncateToWidth(
+				`${this.theme.fg(head, live > 0 ? "●" : "○")} ${this.theme.fg(head, `Subagents (${done}/${total})`)}`,
+				width,
+				"…",
+			),
+		];
+		const budget = WIDGET_MAX_LINES - 1;
+		let shown = 0;
+		outer: for (const run of runs) {
+			for (const task of run.tasks) {
+				if (shown >= budget) break outer;
+				shown += 1;
+				const activity = task.lastActivity ? `${this.theme.fg("dim", `→ ${task.lastActivity}`)} · ` : "";
+				// Per-TASK status drives dimming: a finished agent stays dim even while siblings run.
+				lines.push(
+					truncateToWidth(`${this.theme.fg("dim", "├─")} ${themedTaskLine(task, this.theme, activity)}`, width, "…"),
+				);
+			}
+		}
+		const hidden = total - shown;
+		if (hidden > 0) {
+			lines.push(`${this.theme.fg("dim", "└─")} ${this.theme.fg("dim", `+${hidden} more`)}`);
+		} else if (lines.length > 1) {
+			const last = lines[lines.length - 1];
+			if (last) lines[lines.length - 1] = last.replace("├─", "└─");
+		}
+		return lines;
+	}
+}
+/** Blocking-call summary: full text, because the model asked for it. */
+export function makeSummary(run: RunSnapshot): string {
+	const succeeded = run.tasks.filter((t) => t.status === "completed").length;
+	const failed = run.tasks.filter((t) => t.status === "failed").length;
+	const aborted = run.tasks.filter((t) => t.status === "aborted").length;
+	const done = TERMINAL.includes(run.status) ? "finished" : "running";
+	const lines = [
+		`Run ${run.id}: Subagents ${run.mode}${run.background ? " (background)" : ""} ${done}: ${succeeded}/${run.tasks.length} succeeded${failed ? `, ${failed} failed` : ""}${aborted ? `, ${aborted} aborted` : ""}.`,
+	];
+	const usage = formatUsage(run.aggregateUsage);
+	if (usage) lines.push(`Usage: ${usage}`);
+	for (const task of run.tasks) {
+		// Edges are named so the leader can compare what it delegated against what came back.
+		const edge = task.needs?.length ? ` (${task.id}, needs ${task.needs.join(", ")})` : ` (${task.id})`;
+		lines.push(
+			`\n## ${task.agent}${edge} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}`,
+		);
+	}
+	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.
+	return truncateText(lines.join("\n"));
+}
+/** Per-task notice: one task's outcome, small. Full output stays out of parent context. */
+export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: string): string {
+	const detail = task.error ? task.error : truncateText(task.finalText || "(no output)", 200);
+	return [
+		`Task ${task.agent} (${task.id}) ${kind} in run ${run.id}: ${detail}`,
+		`Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
+	].join("\n");
+}
+/** Notification: 3 lines max. Full output stays out of parent context. */
+export function makeNotice(run: RunSnapshot, kind: string): string {
+	const lines = [
+		`Background subagent run ${run.id} ${kind}: ${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} succeeded.`,
+	];
+	for (const task of run.tasks) {
+		lines.push(`- ${task.agent}: ${task.status}${task.error ? ` — ${truncateText(task.error, 200)}` : ""}`);
+	}
+	lines.push(`Use subagent_result(runId: "${run.id}") for full output.`);
+	return lines.join("\n");
+}

package/src/graph.ts

@@ -0,0 +1,145 @@
+/** Graph Protocol §2/§6: dependency resolution, wave notation, edge payloads,
+ *  and the wave-frontier scheduler. Pure logic — no pi imports, easily tested. */
+import type { RunMode } from "./types.ts";
+
+/**
+ * Resolve dependency edges (Graph Protocol §2). Returns one id list per task,
+ * in input order. Chain mode is just `needs: [previous]`, so both modes run
+ * through the same wave scheduler.
+ *
+ * Throws on unknown ids, self-edges, and cycles — a bad graph must fail before
+ * any child is spawned, never halfway through a run.
+ */
+export function resolveNeeds(inputs: { id?: string; needs?: string[] }[], mode: RunMode): string[][] {
+	const ids = inputs.map((input, index) => input.id ?? `task_${index + 1}`);
+	const known = new Set(ids);
+	const edges = inputs.map((input, index) => {
+		if (mode === "chain") return index === 0 ? [] : [ids[index - 1] as string];
+		const needs = input.needs ?? [];
+		for (const need of needs) {
+			if (!known.has(need)) throw new Error(`Task ${ids[index]} needs unknown task id: ${need}`);
+			if (need === ids[index]) throw new Error(`Task ${ids[index]} cannot need itself.`);
+		}
+		return [...new Set(needs)];
+	});
+	// Kahn's algorithm: if any task never becomes ready, the remainder is a cycle.
+	const done = new Set<string>();
+	let progress = true;
+	while (progress) {
+		progress = false;
+		for (const [index, id] of ids.entries()) {
+			if (done.has(id)) continue;
+			if ((edges[index] as string[]).every((need) => done.has(need))) {
+				done.add(id);
+				progress = true;
+			}
+		}
+	}
+	if (done.size !== ids.length) {
+		throw new Error(`Cycle in subagent needs: ${ids.filter((id) => !done.has(id)).join(", ")}`);
+	}
+	return edges;
+}
+
+/**
+ * Graph Protocol §2 notation: `wave1[api ∥ db] → gate → wave2[doc]`.
+ *
+ * Tolerates half-streamed args: a need pointing at an id that has not arrived yet
+ * keeps its task out of the ready set, so the layout settles as the model types.
+ * Returns "" when there are no edges — flat fan-out gets no graph vocabulary.
+ */
+export function waveNotation(tasks: { id?: string; needs?: string[] }[]): string {
+	if (!tasks.some((t) => t.needs?.length)) return "";
+	const ids = tasks.map((t, i) => t.id ?? `task_${i + 1}`);
+	const settled = new Set<string>();
+	let remaining = tasks.map((t, i) => ({ id: ids[i] as string, needs: t.needs ?? [] }));
+	const waves: string[][] = [];
+	while (remaining.length > 0) {
+		const ready = remaining.filter((t) => t.needs.every((n) => settled.has(n)));
+		if (ready.length === 0) break; // cycle, or an upstream id not typed yet
+		waves.push(ready.map((t) => t.id));
+		for (const t of ready) settled.add(t.id);
+		remaining = remaining.filter((t) => !settled.has(t.id));
+	}
+	if (remaining.length > 0) waves.push(remaining.map((t) => t.id)); // show them rather than drop them
+	if (waves.length < 2) return "";
+	const full = waves.map((w, i) => `wave${i + 1}[${w.join(" ∥ ")}]`).join(" → gate → ");
+	// Long graphs: keep the shape, drop the names.
+	return full.length <= 100 ? full : waves.map((w, i) => `wave${i + 1}[${w.length}]`).join(" → gate → ");
+}
+
+/**
+ * Graph Protocol §6: the edge carries the upstream output, not just ordering.
+ * Upstream results are prepended verbatim; `{previous}` stays supported so old
+ * chain prompts keep working (it expands to the first need's output).
+ */
+export function applyUpstream(task: string, needs: string[], outputs: Map<string, string>): string {
+	if (needs.length === 0) {
+		return task.includes("{previous}")
+			? `${task.replace(/\{previous\}/g, () => "")}\n\n(Note: {previous} was empty — no prior step output existed yet.)`
+			: task;
+	}
+	const first = outputs.get(needs[0] as string) ?? "";
+	const body = task.replace(/\{previous\}/g, () => first); // replacer fn: no $ corruption
+	const blocks = needs.map((need) => `## Output of ${need}\n${outputs.get(need) ?? "(no output)"}`);
+	return `${blocks.join("\n\n")}\n\n---\n\n${body}`;
+}
+
+export async function mapWithConcurrency<T>(
+	items: T[],
+	concurrency: number,
+	fn: (item: T, index: number) => Promise<void>,
+): Promise<void> {
+	let next = 0;
+	const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, async () => {
+		while (next < items.length) {
+			const index = next++;
+			await fn(items[index] as T, index);
+		}
+	});
+	await Promise.all(workers);
+}
+
+export interface SchedulerTask {
+	id: string;
+	needs?: string[];
+}
+
+export interface SkippedTask {
+	id: string;
+	needs: string[];
+}
+
+/** Wave-frontier scheduler (Graph Protocol §2 execution). Pure control flow:
+ *  the caller owns the settled/output bookkeeping and supplies the per-task
+ *  runner, so the loop is testable without spawning children. Tasks whose
+ *  needs never produced an output (upstream failed/aborted/canceled) are
+ *  skipped, not run. */
+export async function runWaveScheduler<T extends SchedulerTask>(
+	tasks: T[],
+	concurrency: number,
+	outputs: Map<string, string>,
+	settled: Set<string>,
+	run: (task: T, index: number) => Promise<void>,
+): Promise<{ skipped: SkippedTask[] }> {
+	let remaining = [...tasks];
+	const skipped: SkippedTask[] = [];
+	while (remaining.length > 0) {
+		const ready = remaining.filter((t) => (t.needs ?? []).every((need) => settled.has(need)));
+		// resolveNeeds() rejects cycles up front, so an empty frontier here means every
+		// remaining task is downstream of one that never settled (canceled mid-run).
+		if (ready.length === 0) break;
+		await mapWithConcurrency(ready, concurrency, async (task) => {
+			const index = tasks.indexOf(task);
+			const needs = task.needs ?? [];
+			// An upstream failure means this task's input never existed. Running it anyway
+			// burns a full child session on a prompt with a hole in it.
+			const broken = needs.filter((need) => !outputs.has(need));
+			if (broken.length > 0) skipped.push({ id: task.id, needs: broken });
+			else await run(task, index);
+		});
+		for (const task of ready) settled.add(task.id);
+		remaining = remaining.filter((t) => !settled.has(t.id));
+	}
+	return { skipped };
+}