@d3ara1n/pi-subagent 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @d3ara1n/pi-subagent
+
+Role-based subagent orchestration for [pi](https://github.com/earendil-works/pi).
+
+Provides a `delegate` tool that lets the main model delegate tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries.
+
+## How it works
+
+1. Main model calls the `delegate` tool with a role and task description
+2. The extension resolves the role to a model via pi-model-roles
+3. Spawns an isolated pi child process with the configured model, tools, and system prompt
+4. **Real-time TUI progress** shows tool calls, turns, and elapsed time as the subagent runs
+5. After completion, an **AI-generated one-line summary** is produced for compact display
+6. Returns the result to the main model with usage statistics (turns, tokens, cost)
+
+## Built-in Roles
+
+| Role | Model Role | Tools | Description |
+|------|-----------|-------|-------------|
+| `explorer` | fast | read, bash, find, grep, glob | Fast code search (read-only) |
+| `reviewer` | heavy | read, bash, grep, glob | Deep code review (read-only) |
+| `worker` | default | read, bash, edit, write, grep, glob | Implementation with file editing |
+| `researcher` | fast | web_search, fetch_content, read | Web research and docs lookup |
+
+## TUI Display
+
+- **During execution**: Shows role, elapsed time, turn count, and live tool calls
+- **Collapsed result**: `✓ explorer · 找到了登录/注册/token三块逻辑` + recent tool calls + usage stats
+- **Expanded result** (Ctrl+O): Full task text, all tool calls, final output as rendered Markdown, and usage details
+
+## Requirements
+
+- **@d3ara1n/pi-model-roles** must be installed and configured
+- **@earendil-works/pi-tui** — bundled with pi, no separate install needed
+- Role definitions must exist in `modelRoles` settings
+
+## Installation
+
+```bash
+pi extension add @d3ara1n/pi-subagent
+```
+
+## Configuration
+
+Edit `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "subagent": {
+    // Default timeout per subagent (5 minutes)
+    "timeoutMs": 300000,
+
+    // Summary generation — uses a lightweight model to create
+    // a one-line Chinese summary for the TUI display
+    "summary": {
+      "role": "utility",    // pi-model-roles role for summarization
+      "enabled": true        // set false to disable
+    }
+  }
+}
+```
+
+All fields are optional. Defaults: `timeoutMs: 300000`, `summary.role: "utility"`, `summary.enabled: true`.
+
+## Usage (by the main model)
+
+```json
+{
+  "role": "explorer",
+  "task": "Find all files that import the ModelRegistry and trace how they use it"
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@d3ara1n/pi-subagent",
+  "version": "0.1.0",
+  "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@d3ara1n/pi-model-roles": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@d3ara1n/pi-model-roles": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@d3ara1n/pi-model-roles": "^0.1.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d3ara1n/pi-extensions",
+    "directory": "packages/pi-subagent"
+  },
+  "license": "MIT"
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+/**
+ * Read subagent configuration from settings files.
+ *
+ * Global (~/.pi/agent/settings.json) + project (.pi/settings.json),
+ * project overrides global.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { SubagentConfig } from "./types.ts";
+import { DEFAULT_CONFIG } from "./types.ts";
+
+function getAgentDir(): string {
+	const envDir = process.env.PI_AGENT_DIR;
+	if (envDir) return envDir;
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+function readSettingsFile(filePath: string): any {
+	try {
+		if (!fs.existsSync(filePath)) return {};
+		const content = fs.readFileSync(filePath, "utf-8");
+		const stripped = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+		return JSON.parse(stripped);
+	} catch {
+		return {};
+	}
+}
+
+function merge(target: any, source: any): any {
+	if (!source || typeof source !== "object") return target;
+	if (!target || typeof target !== "object") return source;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+			result[key] = merge(result[key], source[key]);
+		} else {
+			result[key] = source[key];
+		}
+	}
+	return result;
+}
+
+export function loadSubagentConfig(cwd?: string): SubagentConfig {
+	const globalSettings = readSettingsFile(path.join(getAgentDir(), "settings.json"));
+	const projectSettings = cwd
+		? readSettingsFile(path.join(cwd, ".pi", "settings.json"))
+		: {};
+	const settings = merge(globalSettings, projectSettings);
+
+	const raw = settings?.subagent;
+	if (!raw) return DEFAULT_CONFIG;
+
+	const rawSummary = raw?.summary;
+	return {
+		timeoutMs: raw.timeoutMs ?? DEFAULT_CONFIG.timeoutMs,
+		summary: {
+			role: rawSummary?.role ?? DEFAULT_CONFIG.summary.role,
+			enabled: rawSummary?.enabled ?? DEFAULT_CONFIG.summary.enabled,
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,481 @@
+/**
+ * pi-subagent — Role-based subagent orchestration with TUI rendering.
+ *
+ * Delegates tasks to specialized pi child processes with:
+ * - Real-time progress streaming via TUI (tool calls, turns, elapsed time)
+ * - AI-generated one-line summary for compact display (configurable role)
+ * - All messages collected for expanded view (Ctrl+O)
+ * - Accurate, concise output for the main model
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { complete } from "@earendil-works/pi-ai";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
+import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
+import type { SubagentConfig, SubagentDetails, SubagentResult } from "./types.ts";
+import { DEFAULT_CONFIG } from "./types.ts";
+import { loadSubagentConfig } from "./config.ts";
+import { BUILTIN_ROLES } from "./roles.ts";
+import { spawnSubagent } from "./spawn.ts";
+import * as os from "node:os";
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}
+
+function formatUsageStats(usage: SubagentResult["usage"], model?: string): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`\u2191${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`\u2193${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+type DisplayItem =
+	| { type: "text"; text: string }
+	| { type: "toolCall"; name: string; args: Record<string, any> };
+
+function getDisplayItems(messages: SubagentResult["messages"]): DisplayItem[] {
+	const items: DisplayItem[] = [];
+	for (const msg of messages) {
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text" && part.text) items.push({ type: "text", text: part.text });
+				else if (part.type === "toolCall" && part.name)
+					items.push({ type: "toolCall", name: part.name, args: part.arguments ?? {} });
+			}
+		}
+	}
+	return items;
+}
+
+function shortenPath(p: string): string {
+	const home = os.homedir();
+	return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
+function formatToolCall(
+	toolName: string,
+	args: Record<string, unknown>,
+	fg: (color: string, text: string) => string,
+): string {
+	switch (toolName) {
+		case "bash": {
+			const command = (args.command as string) || "...";
+			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+			return fg("muted", "$ ") + fg("toolOutput", preview);
+		}
+		case "read": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			const filePath = shortenPath(rawPath);
+			const offset = args.offset as number | undefined;
+			const limit = args.limit as number | undefined;
+			let text = fg("accent", filePath);
+			if (offset !== undefined || limit !== undefined) {
+				const startLine = offset ?? 1;
+				const endLine = limit !== undefined ? startLine + limit - 1 : "";
+				text += fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			}
+			return fg("muted", "read ") + text;
+		}
+		case "write": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			const content = (args.content || "") as string;
+			const lines = content.split("\n").length;
+			let text = fg("muted", "write ") + fg("accent", shortenPath(rawPath));
+			if (lines > 1) text += fg("dim", ` (${lines} lines)`);
+			return text;
+		}
+		case "edit": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			return fg("muted", "edit ") + fg("accent", shortenPath(rawPath));
+		}
+		case "grep": {
+			const pattern = (args.pattern || "") as string;
+			const rawPath = (args.path || ".") as string;
+			return fg("muted", "grep ") + fg("accent", `/${pattern}/`) + fg("dim", ` in ${shortenPath(rawPath)}`);
+		}
+		case "find": {
+			const pattern = (args.pattern || "*") as string;
+			return fg("muted", "find ") + fg("accent", pattern);
+		}
+		case "glob": {
+			const pattern = (args.pattern || "*") as string;
+			return fg("muted", "glob ") + fg("accent", pattern);
+		}
+		default: {
+			const argsStr = JSON.stringify(args);
+			const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
+			return fg("accent", toolName) + fg("dim", ` ${preview}`);
+		}
+	}
+}
+
+function renderDisplayItems(
+	items: DisplayItem[],
+	limit: number | undefined,
+	fg: (color: string, text: string) => string,
+): string {
+	const toShow = limit ? items.slice(-limit) : items;
+	const skipped = limit && items.length > limit ? items.length - limit : 0;
+	let text = "";
+	if (skipped > 0) text += fg("muted", `... ${skipped} earlier items\n`);
+	for (const item of toShow) {
+		if (item.type === "text") {
+			const preview = item.text.split("\n").slice(0, 3).join("\n");
+			text += `${fg("toolOutput", preview.length > 120 ? preview.slice(0, 120) + "..." : preview)}\n`;
+		} else {
+			text += `${fg("muted", "\u2192 ")}${formatToolCall(item.name, item.args, fg)}\n`;
+		}
+	}
+	return text.trimEnd();
+}
+
+function getFinalOutput(messages: SubagentResult["messages"]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text" && part.text) return part.text;
+			}
+		}
+	}
+	return "";
+}
+
+function isFailedResult(r: SubagentResult): boolean {
+	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+}
+
+// ── Summary generation ─────────────────────────────────────────────
+
+async function generateSummary(
+	rolesApi: ModelRolesAPI,
+	outputText: string,
+	summaryConfig: SubagentConfig["summary"],
+): Promise<string | undefined> {
+	if (!summaryConfig.enabled || !outputText.trim()) return undefined;
+
+	try {
+		const resolved = await rolesApi.resolveRoleAsync(summaryConfig.role);
+		if (!resolved.model) return undefined;
+
+		const result = await complete(
+			resolved.model,
+			{
+				systemPrompt:
+					"Summarize the following agent output in one concise Chinese sentence (max 60 characters). Focus on what was accomplished, not how. Output only the summary, no preamble.",
+				messages: [{ role: "user", content: outputText }],
+			},
+			{
+				maxTokens: 100,
+				apiKey: resolved.apiKey,
+				headers: resolved.headers,
+			},
+		);
+
+		const text = result.content
+			?.filter((block: any) => block.type === "text")
+			?.map((block: any) => block.text)
+			?.join("")
+			?.trim();
+
+		return text || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// ── Extension entry ────────────────────────────────────────────────
+
+export default function subagentExtension(pi: ExtensionAPI) {
+	let config: SubagentConfig = DEFAULT_CONFIG;
+
+	pi.on("session_start", async (_event, ctx) => {
+		config = loadSubagentConfig(ctx.cwd);
+	});
+
+	pi.registerTool({
+		name: "delegate",
+		label: "Delegate to subagent",
+		description: [
+			"Delegate a task to a specialized subagent with isolated context.",
+			"Available roles:",
+			"  - explorer: fast code search and navigation (read-only)",
+			"  - reviewer: deep code review with evidence (read-only)",
+			"  - worker: implementation with file editing capabilities",
+			"  - researcher: web research and documentation lookup",
+			"",
+			"Progress is shown in real-time via TUI (tool calls, turns, elapsed time).",
+			"Use Ctrl+O on a completed result to see full details.",
+			"",
+			"Note: Subagents only have built-in tools (read, bash, edit, write, grep, glob, find, web_search, fetch_content). They do NOT have access to MCP tools or custom tools from the main session.",
+		].join("\n"),
+
+		parameters: Type.Object({
+			role: Type.Union(
+				[
+					Type.Literal("explorer"),
+					Type.Literal("reviewer"),
+					Type.Literal("worker"),
+					Type.Literal("researcher"),
+				],
+				{ description: "Subagent role to use" },
+			),
+			task: Type.String({ description: "Specific task for the subagent" }),
+			cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),
+		}),
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const roleDef = BUILTIN_ROLES[params.role];
+			if (!roleDef) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown subagent role: ${params.role}. Available: ${Object.keys(BUILTIN_ROLES).join(", ")}`,
+						},
+					],
+				};
+			}
+
+			// Resolve model from pi-model-roles
+			let rolesApi: ModelRolesAPI;
+			try {
+				rolesApi = getModelRolesAPI();
+			} catch {
+				return {
+					content: [{ type: "text", text: "pi-model-roles is not initialized. Cannot resolve model for subagent." }],
+				};
+			}
+
+			const resolved = await rolesApi.resolveRoleAsync(roleDef.role);
+			if (!resolved.model) {
+				return {
+					content: [{ type: "text", text: `Role "${roleDef.role}" could not be resolved. Model not available.` }],
+				};
+			}
+
+			const modelRef = `${resolved.model.provider}/${resolved.model.id}`;
+			const startTime = Date.now();
+
+			// Emit initial placeholder for TUI
+			if (onUpdate) {
+				const placeholder: SubagentResult = {
+					role: params.role,
+					task: params.task,
+					exitCode: -1,
+					messages: [],
+					output: "",
+					stderr: "",
+					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+				};
+				onUpdate({
+					content: [{ type: "text", text: `${params.role}: running...` }],
+					details: { mode: "single", results: [placeholder] },
+				});
+			}
+
+			try {
+				const result = await spawnSubagent(modelRef, params.task, {
+					cwd: params.cwd ?? ctx.cwd,
+					tools: roleDef.tools,
+					systemPrompt: roleDef.systemPrompt,
+					timeoutMs: config.timeoutMs,
+					signal,
+					onProgress: (partial) => {
+						if (!onUpdate) return;
+						const elapsed = Math.round((Date.now() - startTime) / 1000);
+						const liveResult: SubagentResult = {
+							role: params.role,
+							task: params.task,
+							exitCode: -1,
+							messages: partial.messages ?? [],
+							output: partial.output ?? "",
+							stderr: "",
+							usage: partial.usage ?? {
+								input: 0,
+								output: 0,
+								cacheRead: 0,
+								cacheWrite: 0,
+								cost: 0,
+								contextTokens: 0,
+								turns: 0,
+							},
+							model: partial.model,
+							stopReason: partial.stopReason,
+						};
+						const statusText = `${params.role}  ${elapsed}s  ${liveResult.usage.turns} turn${liveResult.usage.turns !== 1 ? "s" : ""}`;
+						onUpdate({
+							content: [{ type: "text", text: statusText }],
+							details: { mode: "single", results: [liveResult] },
+						});
+					},
+				});
+
+				// Generate summary for TUI display
+				if (config.summary.enabled && result.output.trim()) {
+					result.summary = await generateSummary(rolesApi, result.output, config.summary);
+				}
+
+				if (result.exitCode !== 0 || result.errorMessage) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Subagent (${params.role}) failed: ${result.errorMessage || result.stderr || "unknown error"}\n\nPartial output:\n${result.output}`,
+							},
+						],
+						details: { mode: "single", results: [result] },
+						isError: true,
+					};
+				}
+
+				// Build concise output for the main model with usage info
+				const usageParts: string[] = [];
+				if (result.usage.turns) usageParts.push(`${result.usage.turns} turn${result.usage.turns > 1 ? "s" : ""}`);
+				if (result.usage.input) usageParts.push(`\u2191${formatTokens(result.usage.input)}`);
+				if (result.usage.output) usageParts.push(`\u2193${formatTokens(result.usage.output)}`);
+				if (result.usage.cost) usageParts.push(`$${result.usage.cost.toFixed(4)}`);
+				if (result.model) usageParts.push(result.model);
+				const usageLine = usageParts.length > 0 ? `\n\n--- ${usageParts.join(" ")} ---` : "";
+
+				return {
+					content: [{ type: "text", text: result.output + usageLine }],
+					details: { mode: "single", results: [result] },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Subagent (${params.role}) error: ${err.message || err}` }],
+					details: { mode: "single", results: [] },
+					isError: true,
+				};
+			}
+		},
+
+		// ── renderCall: what the user sees when the tool is invoked ──────
+
+		renderCall(args, theme, _context) {
+			const roleName = (args as any).role || "...";
+			const task = (args as any).task || "";
+			const preview = task.length > 60 ? `${task.slice(0, 60)}...` : task;
+			const text =
+				theme.fg("toolTitle", theme.bold("subagent ")) +
+				theme.fg("accent", roleName) +
+				"\n  " +
+				theme.fg("dim", preview);
+			return new Text(text, 0, 0);
+		},
+
+		// ── renderResult: TUI display when the tool finishes ─────────────
+
+		renderResult(result, { expanded }, theme, _context) {
+			const details = result.details as SubagentDetails | undefined;
+			if (!details || details.results.length === 0) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+			}
+
+			const r = details.results[0];
+			const isRunning = r.exitCode === -1;
+			const isError = !isRunning && isFailedResult(r);
+			let icon: string;
+			if (isRunning) {
+				icon = theme.fg("warning", "\u23F3"); // hourglass
+			} else if (isError) {
+				icon = theme.fg("error", "\u2717");
+			} else {
+				icon = theme.fg("success", "\u2713");
+			}
+			const displayItems = getDisplayItems(r.messages);
+			const finalOutput = getFinalOutput(r.messages);
+			const mdTheme = getMarkdownTheme();
+
+			if (expanded) {
+				const container = new Container();
+
+				// Header
+				let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.role))}`;
+				if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+				container.addChild(new Text(header, 0, 0));
+				if (isError && r.errorMessage)
+					container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
+
+				if (!isRunning) {
+					container.addChild(new Spacer(1));
+					container.addChild(new Text(theme.fg("muted", "\u2500\u2500\u2500 Task \u2500\u2500\u2500"), 0, 0));
+					container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+				}
+
+				container.addChild(new Spacer(1));
+				const toolCalls = displayItems.filter((item) => item.type === "toolCall");
+				if (toolCalls.length === 0) {
+					const runningLabel = isRunning ? "(waiting for first event...)" : "(none)";
+					container.addChild(new Text(theme.fg("muted", runningLabel), 0, 0));
+				} else {
+					for (const item of toolCalls) {
+						container.addChild(
+							new Text(
+								theme.fg("muted", "\u2192 ") +
+									formatToolCall(item.name, item.args, theme.fg.bind(theme)),
+								0,
+								0,
+							),
+						);
+					}
+				}
+
+				if (!isRunning && finalOutput) {
+					container.addChild(new Spacer(1));
+					container.addChild(new Text(theme.fg("muted", "\u2500\u2500\u2500 Output \u2500\u2500\u2500"), 0, 0));
+					container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+				}
+
+				const usageStr = formatUsageStats(r.usage, r.model);
+				if (usageStr) {
+					container.addChild(new Spacer(1));
+					container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+				}
+
+				return container;
+			}
+
+			// Collapsed view
+			let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.role))}`;
+
+			if (isRunning) {
+				// Running: show recent tool calls only
+				const toolCalls = displayItems.filter((item) => item.type === "toolCall");
+				if (toolCalls.length === 0) {
+					text += `\n${theme.fg("muted", "(running...)")}`;
+				} else {
+					const rendered = renderDisplayItems(toolCalls, 5, theme.fg.bind(theme));
+					if (rendered) text += `\n${rendered}`;
+				}
+			} else {
+				// Finished: summary + usage, no tool calls
+				if (r.summary) {
+					text += ` ${theme.fg("dim", "\u00b7")} ${theme.fg("text", r.summary)}`;
+				}
+				if (isError && r.errorMessage) {
+					text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+				}
+				const usageStr = formatUsageStats(r.usage, r.model);
+				if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+			}
+			return new Text(text, 0, 0);
+		},
+	});
+}

package/src/roles.ts

@@ -0,0 +1,57 @@
+/**
+ * Built-in subagent role definitions.
+ *
+ * Each maps to a pi-model-roles role and has a tailored system prompt
+ * and tool set. Prompts are in English — concise, efficient, task-focused.
+ * Final output should be accurate and concise, stating conclusions directly.
+ */
+
+import type { SubagentRole } from "./types.ts";
+
+export const BUILTIN_ROLES: Record<string, SubagentRole> = {
+  explorer: {
+    role: "fast",
+    tools: ["read", "bash", "find", "grep", "glob"],
+    systemPrompt: [
+      "You are a fast code explorer. Investigate the codebase and answer the task query.",
+      "You must NOT edit any files.",
+      "",
+      "Output accurately and concisely. State findings directly with file paths and line numbers.",
+      "Keep the final output as short as possible while preserving all actionable information.",
+    ].join("\n"),
+  },
+  reviewer: {
+    role: "heavy",
+    tools: ["read", "bash", "grep", "glob"],
+    systemPrompt: [
+      "You are a senior code reviewer. Inspect code for correctness, maintainability, and security issues.",
+      "You must NOT edit any files.",
+      "",
+      "Provide evidence-backed findings with file/line references.",
+      'Use bash only for read-only commands: git diff, git log, git show.',
+      "",
+      "Output accurately and concisely. Prioritize critical issues first.",
+    ].join("\n"),
+  },
+  worker: {
+    role: "default",
+    tools: ["read", "bash", "edit", "write", "grep", "glob"],
+    systemPrompt: [
+      "You are an implementation worker. Follow the given plan precisely.",
+      "Make minimal, focused changes. Validate your work after each change.",
+      "",
+      "When finished, report what you changed and what validation you ran.",
+      "Output accurately and concisely — summarize changes, don't repeat full diffs.",
+    ].join("\n"),
+  },
+  researcher: {
+    role: "fast",
+    tools: ["web_search", "fetch_content", "read"],
+    systemPrompt: [
+      "You are a web researcher. Find relevant documentation, examples, and best practices.",
+      "",
+      "Return concise summaries with source links.",
+      "Output accurately and concisely — state key findings first, then supporting details if needed.",
+    ].join("\n"),
+  },
+};

package/src/spawn.ts

@@ -0,0 +1,208 @@
+/**
+ * Spawn a pi child process and collect structured output with real-time progress.
+ *
+ * Uses pi's --mode json to get a JSON event stream.
+ * Collects all messages (assistant + tool results) for TUI rendering.
+ * Fires onProgress on each event for streaming updates.
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { SubagentMessage, SubagentResult } from "./types.ts";
+
+/** Determine how to invoke pi.
+ *
+ * Always uses the `pi` CLI command. On Windows with Bun-compiled pi,
+ * process.execPath returns a virtual path (B:/~BUN/root/pi.exe) that
+ * leaks into the child model's context and causes it to run stray
+ * diagnostic commands. Using the `pi` command from PATH avoids this.
+ */
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	return { command: "pi", args };
+}
+
+/** Write a system prompt to a temp file for --append-system-prompt. */
+async function writeTempPromptFile(prefix: string, content: string): Promise<{ dir: string; filePath: string }> {
+	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
+	const safeName = prefix.replace(/[^\w.-]+/g, "_");
+	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+	await fs.promises.writeFile(filePath, content, { encoding: "utf-8", mode: 0o600 });
+	return { dir: tmpDir, filePath };
+}
+
+/**
+ * Spawn a pi child process with the given model and configuration.
+ * Fires onProgress on each JSON event for streaming TUI updates.
+ *
+ * @param modelRef - Model identifier like "deepseek/deepseek-v4-flash"
+ * @param task - The task prompt
+ * @param options - Spawn options
+ * @returns SubagentResult with collected messages and usage stats
+ */
+export async function spawnSubagent(
+	modelRef: string,
+	task: string,
+	options: {
+		cwd?: string;
+		tools?: string[];
+		systemPrompt?: string;
+		timeoutMs?: number;
+		signal?: AbortSignal;
+		onProgress?: (update: Partial<SubagentResult>) => void;
+	},
+): Promise<SubagentResult> {
+	const result: SubagentResult = {
+		role: "",
+		task,
+		exitCode: 0,
+		messages: [],
+		output: "",
+		stderr: "",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+	};
+
+	let tmpDir: string | null = null;
+	let tmpFile: string | null = null;
+
+	try {
+		// Build CLI args
+		const args: string[] = ["--mode", "json", "--no-session", "--model", modelRef];
+
+		if (options.tools && options.tools.length > 0) {
+			args.push("--tools", options.tools.join(","));
+		}
+
+		if (options.systemPrompt?.trim()) {
+			const tmp = await writeTempPromptFile("delegate", options.systemPrompt);
+			tmpDir = tmp.dir;
+			tmpFile = tmp.filePath;
+			args.push("--append-system-prompt", tmpFile);
+		}
+
+		args.push(`Task: ${task}`);
+
+		// Spawn process
+		const invocation = getPiInvocation(args);
+		let wasAborted = false;
+		let buffer = "";
+
+		const emitProgress = () => {
+			options.onProgress?.({
+				output: result.output,
+				messages: [...result.messages],
+				usage: { ...result.usage },
+				model: result.model,
+				stopReason: result.stopReason,
+			});
+		};
+
+		const processLine = (line: string) => {
+			if (!line.trim()) return;
+			let event: any;
+			try {
+				event = JSON.parse(line);
+			} catch {
+				return;
+			}
+
+			if (event.type === "message_end" && event.message) {
+				const msg = event.message as SubagentMessage;
+				result.messages.push(msg);
+
+				if (msg.role === "assistant") {
+					result.usage.turns++;
+					const usage = msg.usage;
+					if (usage) {
+						result.usage.input += usage.input || 0;
+						result.usage.output += usage.output || 0;
+						result.usage.cacheRead += usage.cacheRead || 0;
+						result.usage.cacheWrite += usage.cacheWrite || 0;
+						result.usage.cost += usage.cost?.total || 0;
+						result.usage.contextTokens = usage.totalTokens || 0;
+					}
+					if (!result.model && msg.model) result.model = msg.model;
+					if (msg.stopReason) result.stopReason = msg.stopReason;
+					if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+
+					// Track last assistant text
+					for (const part of msg.content) {
+						if (part.type === "text" && part.text) {
+							result.output = part.text;
+						}
+					}
+				}
+
+				emitProgress();
+			}
+
+			if (event.type === "tool_result_end" && event.message) {
+				result.messages.push(event.message as SubagentMessage);
+				emitProgress();
+			}
+		};
+
+		const exitCode = await new Promise<number>((resolve) => {
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: options.cwd,
+				shell: false,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+
+			proc.stdout.on("data", (data: Buffer) => {
+				buffer += data.toString();
+				const lines = buffer.split("\n");
+				buffer = lines.pop() || "";
+				for (const line of lines) processLine(line);
+			});
+
+			proc.stderr.on("data", (data: Buffer) => {
+				result.stderr += data.toString();
+			});
+
+			proc.on("close", (code) => {
+				if (buffer.trim()) processLine(buffer);
+				resolve(code ?? 0);
+			});
+
+			proc.on("error", () => {
+				resolve(1);
+			});
+
+			// Handle abort signal
+			if (options.signal) {
+				const killProc = () => {
+					wasAborted = true;
+					proc.kill("SIGTERM");
+					setTimeout(() => {
+						if (!proc.killed) proc.kill("SIGKILL");
+					}, 5000);
+				};
+				if (options.signal.aborted) killProc();
+				else options.signal.addEventListener("abort", killProc, { once: true });
+			}
+
+			// Handle timeout
+			if (options.timeoutMs && options.timeoutMs > 0) {
+				setTimeout(() => {
+					if (!proc.killed) {
+						proc.kill("SIGTERM");
+						setTimeout(() => {
+							if (!proc.killed) proc.kill("SIGKILL");
+						}, 5000);
+					}
+				}, options.timeoutMs);
+			}
+		});
+
+		result.exitCode = exitCode;
+		if (wasAborted) throw new Error("Subagent was aborted");
+	} finally {
+		// Cleanup temp files
+		if (tmpFile) try { fs.unlinkSync(tmpFile); } catch { /* ignore */ }
+		if (tmpDir) try { fs.rmdirSync(tmpDir); } catch { /* ignore */ }
+	}
+
+	return result;
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Subagent configuration and types.
+ */
+
+/** Configuration for the subagent extension. */
+export interface SubagentConfig {
+  timeoutMs: number;
+  summary: SubagentSummaryConfig;
+}
+
+export interface SubagentSummaryConfig {
+  role: string;
+  enabled: boolean;
+}
+
+export const DEFAULT_CONFIG: SubagentConfig = {
+  timeoutMs: 300_000,
+  summary: { role: "utility", enabled: true },
+};
+
+/** A built-in subagent role definition. */
+export interface SubagentRole {
+  /** pi-model-roles role name to use for this subagent */
+  role: string;
+  /** System prompt for the subagent */
+  systemPrompt: string;
+  /** Tools available to this subagent */
+  tools: string[];
+}
+
+/** Usage statistics from a subagent execution. */
+export interface SubagentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+/** A message from the subagent's JSON event stream. */
+export interface SubagentMessage {
+  role: string;
+  content: Array<{
+    type: string;
+    text?: string;
+    name?: string;
+    arguments?: Record<string, any>;
+    id?: string;
+  }>;
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cost?: { total?: number };
+    totalTokens?: number;
+  };
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  toolCallId?: string;
+}
+
+/** Result from a single subagent execution. */
+export interface SubagentResult {
+  /** Which subagent role was used */
+  role: string;
+  /** The task that was assigned */
+  task: string;
+  /** Process exit code (-1 = still running for streaming) */
+  exitCode: number;
+  /** All messages from the event stream (assistant + tool results) */
+  messages: SubagentMessage[];
+  /** Last assistant text output */
+  output: string;
+  /** AI-generated one-line summary for TUI display */
+  summary?: string;
+  /** stderr output */
+  stderr: string;
+  /** Token usage stats */
+  usage: SubagentUsage;
+  /** Model identifier used */
+  model?: string;
+  /** Stop reason from last message */
+  stopReason?: string;
+  /** Error message if failed */
+  errorMessage?: string;
+}
+
+/** TUI details structure passed via tool result details. */
+export interface SubagentDetails {
+  mode: "single";
+  results: SubagentResult[];
+}