@bacnh85/pi-subagent 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bacnh85/pi-subagent",
+  "version": "0.1.0",
+  "description": "Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context using the pi SDK in-process.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/bacnh85/skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bacnh85/skills.git",
+    "directory": "extensions/pi-subagent"
+  },
+  "bugs": {
+    "url": "https://github.com/bacnh85/skills/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "subagent",
+    "sub-agent",
+    "delegation",
+    "parallel"
+  ],
+  "files": [
+    "README.md",
+    "index.ts",
+    "agents.ts",
+    "runner.ts",
+    "render.ts",
+    "agents/"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/render.ts

@@ -0,0 +1,250 @@
+/**
+ * TUI rendering for pi-sugagents.
+ *
+ * Renders sub-agent results in collapsed and expanded views.
+ * Collapsed: status icon, agent name, last few items, usage stats.
+ * Expanded (Ctrl+O): full task text, all tool calls, final markdown output.
+ */
+
+import * as os from "node:os";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { Message } from "@earendil-works/pi-ai";
+import { type SubAgentResult, isFailedResult, getResultOutput } from "./runner.ts";
+
+// ---------------------------------------------------------------------------
+// Display 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`;
+}
+
+export function formatUsageStats(
+	usage: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; contextTokens?: number; turns?: number },
+	model?: string,
+): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${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 (usage.contextTokens && usage.contextTokens > 0) {
+		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+	}
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+function formatToolCall(
+	toolName: string,
+	args: Record<string, unknown>,
+	themeFg: (color: string, text: string) => string,
+): string {
+	const shortenPath = (p: string) => {
+		const home = os.homedir();
+		return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+	};
+
+	switch (toolName) {
+		case "bash": {
+			const command = (args.command as string) || "...";
+			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+			return themeFg("muted", "$ ") + themeFg("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 = themeFg("accent", filePath);
+			if (offset !== undefined || limit !== undefined) {
+				const startLine = offset ?? 1;
+				const endLine = limit !== undefined ? startLine + limit - 1 : "";
+				text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			}
+			return themeFg("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 = themeFg("muted", "write ") + themeFg("accent", shortenPath(rawPath));
+			if (lines > 1) text += themeFg("dim", ` (${lines} lines)`);
+			return text;
+		}
+		case "edit": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
+		}
+		case "ls": {
+			const rawPath = (args.path || ".") as string;
+			return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
+		}
+		case "find": {
+			const pattern = (args.pattern || "*") as string;
+			const rawPath = (args.path || ".") as string;
+			return (
+				themeFg("muted", "find ") +
+				themeFg("accent", pattern) +
+				themeFg("dim", ` in ${shortenPath(rawPath)}`)
+			);
+		}
+		case "grep": {
+			const pattern = (args.pattern || "") as string;
+			const rawPath = (args.path || ".") as string;
+			return (
+				themeFg("muted", "grep ") +
+				themeFg("accent", `/${pattern}/`) +
+				themeFg("dim", ` in ${shortenPath(rawPath)}`)
+			);
+		}
+		default: {
+			const argsStr = JSON.stringify(args);
+			const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
+			return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`);
+		}
+	}
+}
+
+type DisplayItem =
+	| { type: "text"; text: string }
+	| { type: "toolCall"; name: string; args: Record<string, unknown> };
+
+function getDisplayItems(messages: Message[]): DisplayItem[] {
+	const items: DisplayItem[] = [];
+	for (const msg of messages) {
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text") {
+					items.push({ type: "text", text: part.text });
+				} else if (part.type === "toolCall") {
+					items.push({
+						type: "toolCall",
+						name: part.name,
+						args: part.arguments as Record<string, unknown>,
+					});
+				}
+			}
+		}
+	}
+	return items;
+}
+
+// ---------------------------------------------------------------------------
+// Collapsed renderer
+// ---------------------------------------------------------------------------
+
+const COLLAPSED_ITEM_COUNT = 10;
+
+function renderDisplayItems(
+	items: DisplayItem[],
+	theme: { fg: (c: string, t: string) => string },
+	limit?: number,
+): string {
+	const toShow = limit ? items.slice(-limit) : items;
+	const skipped = limit && items.length > limit ? items.length - limit : 0;
+	let text = "";
+	if (skipped > 0) text += theme.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 += `${theme.fg("toolOutput", preview)}\n`;
+		} else {
+			text += `${theme.fg("muted", "→ ")}${formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
+		}
+	}
+	return text.trimEnd();
+}
+
+// ---------------------------------------------------------------------------
+// Single agent result
+// ---------------------------------------------------------------------------
+
+export function renderSingleResult(
+	result: SubAgentResult,
+	expanded: boolean,
+	theme: { fg: (c: string, t: string) => string; bold: (t: string) => string },
+): Container | Text {
+	const isError = isFailedResult(result);
+	const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+	const displayItems = getDisplayItems(result.messages);
+	const finalOutput = getResultOutput(result);
+
+	if (expanded) {
+		const mdTheme = getMarkdownTheme();
+		const container = new Container();
+		let header = `${icon} ${theme.fg("toolTitle", theme.bold(result.agent))}`;
+		if (isError && result.stopReason) header += ` ${theme.fg("error", `[${result.stopReason}]`)}`;
+		container.addChild(new Text(header, 0, 0));
+		if (isError && result.errorMessage) {
+			container.addChild(new Text(theme.fg("error", `Error: ${result.errorMessage}`), 0, 0));
+		}
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
+		container.addChild(new Text(theme.fg("dim", result.task), 0, 0));
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
+		if (displayItems.length === 0 && !finalOutput) {
+			container.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
+		} else {
+			for (const item of displayItems) {
+				if (item.type === "toolCall") {
+					container.addChild(
+						new Text(
+							theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)),
+							0, 0,
+						),
+					);
+				}
+			}
+			if (finalOutput) {
+				container.addChild(new Spacer(1));
+				container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+			}
+		}
+		const usageStr = formatUsageStats(result.usage, result.model);
+		if (usageStr) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+		}
+		return container;
+	}
+
+	// Collapsed
+	let text = `${icon} ${theme.fg("toolTitle", theme.bold(result.agent))}`;
+	if (isError && result.stopReason) text += ` ${theme.fg("error", `[${result.stopReason}]`)}`;
+	if (isError && result.errorMessage) text += `\n${theme.fg("error", `Error: ${result.errorMessage}`)}`;
+	else if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
+	else {
+		text += `\n${renderDisplayItems(displayItems, theme, COLLAPSED_ITEM_COUNT)}`;
+		if (displayItems.length > COLLAPSED_ITEM_COUNT) {
+			text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+		}
+	}
+	const usageStr = formatUsageStats(result.usage, result.model);
+	if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+	return new Text(text, 0, 0);
+}
+
+// ---------------------------------------------------------------------------
+// Aggregate helpers
+// ---------------------------------------------------------------------------
+
+export function aggregateUsage(results: SubAgentResult[]) {
+	const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	for (const r of results) {
+		total.input += r.usage.input;
+		total.output += r.usage.output;
+		total.cacheRead += r.usage.cacheRead;
+		total.cacheWrite += r.usage.cacheWrite;
+		total.cost += r.usage.cost;
+		total.turns += r.usage.turns;
+	}
+	return total;
+}

package/runner.ts

@@ -0,0 +1,258 @@
+/**
+ * SDK-based sub-agent runner for pi-sugagents.
+ *
+ * Creates an in-process AgentSession via the pi SDK instead of spawning a
+ * separate `pi` process. This eliminates cold-start overhead and allows
+ * fine-grained control over token budget:
+ *
+ *   - Only the agent's system prompt is used (no pi defaults).
+ *   - No AGENTS.md, no extensions, no skills, no prompt templates loaded.
+ *   - Thinking disabled, compaction disabled, retry disabled.
+ *   - In-memory session (no disk I/O).
+ *   - Shared auth/model infrastructure (no re-connection).
+ *
+ * Estimated token savings vs process-spawn: ~4-11K tokens per invocation.
+ */
+
+import type { Message, Model } from "@earendil-works/pi-ai";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import {
+	AuthStorage,
+	createAgentSession,
+	createExtensionRuntime,
+	ModelRegistry,
+	type ResourceLoader,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export interface SubAgentResult {
+	agent: string;
+	task: string;
+	exitCode: number;
+	messages: Message[];
+	stderr: string;
+	usage: UsageStats;
+	model?: string;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function runSubAgent(options: {
+	cwd: string;
+	systemPrompt: string;
+	task: string;
+	tools: string[];
+	model: Model;
+	authStorage: AuthStorage;
+	modelRegistry: ModelRegistry;
+	signal?: AbortSignal;
+	agentName?: string;
+}): Promise<SubAgentResult> {
+	const {
+		cwd,
+		systemPrompt,
+		task,
+		tools,
+		model,
+		authStorage,
+		modelRegistry,
+		signal,
+		agentName = "subagent",
+	} = options;
+
+	const result: SubAgentResult = {
+		agent: agentName,
+		task,
+		exitCode: 0,
+		messages: [],
+		stderr: "",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+		model: `${model.provider}/${model.id}`,
+	};
+
+	// Build a minimal resource loader. The sub-agent sees ONLY the agent's
+	// system prompt — no pi defaults, no AGENTS.md, no extensions, no skills.
+	const resourceLoader: ResourceLoader = {
+		getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
+		getSkills: () => ({ skills: [], diagnostics: [] }),
+		getPrompts: () => ({ prompts: [], diagnostics: [] }),
+		getThemes: () => ({ themes: [], diagnostics: [] }),
+		getAgentsFiles: () => ({ agentsFiles: [] }),
+		getSystemPrompt: () => systemPrompt,
+		getAppendSystemPrompt: () => [],
+		extendResources: () => {},
+		reload: async () => {},
+	};
+
+	const settingsManager = SettingsManager.inMemory({
+		compaction: { enabled: false },
+		retry: { enabled: false },
+	});
+
+	try {
+		const { session } = await createAgentSession({
+			cwd,
+			model,
+			thinkingLevel: "off", // no reasoning token overhead
+			authStorage,
+			modelRegistry,
+			resourceLoader,
+			tools,
+			sessionManager: SessionManager.inMemory(cwd),
+			settingsManager,
+		});
+
+		try {
+			// Wire abort signal
+			if (signal) {
+				const onAbort = () => session.abort();
+				if (signal.aborted) {
+					// Already aborted — shortcut
+					result.exitCode = 1;
+					result.stopReason = "aborted";
+					result.errorMessage = "Sub-agent aborted before start";
+					onAbort();
+					return result;
+				}
+				signal.addEventListener("abort", onAbort, { once: true });
+
+				// Cleanup listener on completion
+				const cleanup = () => signal.removeEventListener("abort", onAbort);
+				// We'll clean up in finally via a flag
+			}
+
+			// Collect all messages and usage stats from events
+			const eventPromise = new Promise<void>((resolve, reject) => {
+				const unsubscribe = session.subscribe((event) => {
+					try {
+						switch (event.type) {
+							case "message_end": {
+								const msg = event.message as AgentMessage;
+								if (msg.role === "assistant") {
+									result.usage.turns++;
+									if (msg.usage) {
+										result.usage.input += msg.usage.input || 0;
+										result.usage.output += msg.usage.output || 0;
+										result.usage.cacheRead += msg.usage.cacheRead || 0;
+										result.usage.cacheWrite += msg.usage.cacheWrite || 0;
+										result.usage.cost += msg.usage.cost?.total || 0;
+										result.usage.contextTokens = msg.usage.totalTokens || 0;
+									}
+									if (!result.model && msg.model) {
+										result.model = `${msg.provider || "?"}/${msg.model}`;
+									}
+									if (msg.stopReason) result.stopReason = msg.stopReason;
+									if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+								}
+								// Collect all messages for extraction
+								result.messages.push(msg as unknown as Message);
+								break;
+							}
+							case "agent_end": {
+								// agent_end carries all messages; use them if we haven't collected
+								if (result.messages.length === 0 && event.messages) {
+									result.messages = event.messages as unknown as Message[];
+								}
+								unsubscribe();
+								resolve();
+								break;
+							}
+						}
+					} catch (err) {
+						unsubscribe();
+						reject(err);
+					}
+				});
+			});
+
+			await session.prompt(task);
+			await eventPromise;
+
+			result.exitCode = 0;
+			return result;
+		} finally {
+			try {
+				session.dispose();
+			} catch {
+				// Best-effort cleanup
+			}
+		}
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		result.exitCode = 1;
+		result.errorMessage = message;
+		if (!result.stopReason) result.stopReason = "error";
+		return result;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function getFinalOutput(messages: Message[]): 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") return part.text;
+			}
+		}
+	}
+	return "";
+}
+
+export function isFailedResult(result: SubAgentResult): boolean {
+	return (
+		result.exitCode !== 0 ||
+		result.stopReason === "error" ||
+		result.stopReason === "aborted"
+	);
+}
+
+export function getResultOutput(result: SubAgentResult): string {
+	if (isFailedResult(result)) {
+		return result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+	}
+	return getFinalOutput(result.messages) || "(no output)";
+}
+
+/** Concurrency-limited map. Runs up to `concurrency` async operations at a time. */
+export async function mapWithConcurrencyLimit<TIn, TOut>(
+	items: TIn[],
+	concurrency: number,
+	fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+	if (items.length === 0) return [];
+	const limit = Math.max(1, Math.min(concurrency, items.length));
+	const results: TOut[] = new Array(items.length);
+	let nextIndex = 0;
+	const workers = new Array(limit).fill(null).map(async () => {
+		while (true) {
+			const current = nextIndex++;
+			if (current >= items.length) return;
+			results[current] = await fn(items[current], current);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}