@bacnh85/pi-subagent 0.1.2 → 0.2.0

package/agent-format.md

@@ -0,0 +1,59 @@
+# Agent Definition Format
+
+Sub-agents are defined as Markdown files with YAML frontmatter.
+
+## File Location
+
+| Location | Scope |
+|----------|-------|
+| `~/.pi/agent/agents/*.md` | User-level (all projects) |
+| `.pi/agents/*.md` | Project-level |
+| `<skill>/agents/*.md` | Bundled with pi-sugagents |
+
+Project agents override user agents with the same name when `agentScope: "both"`.
+
+## Frontmatter Fields
+
+```yaml
+---
+name: my-agent          # Required. Unique identifier (kebab-case).
+description: ...        # Required. When to use this agent.
+tools: read, grep, ...  # Optional. Comma-separated tool names. Defaults to all.
+model: claude-haiku-4-5 # Optional. Model ID. Defaults to parent's model.
+---
+```
+
+Only `name` and `description` are required.
+
+## Body
+
+The body after frontmatter becomes the agent's **entire system prompt**. No pi defaults, no AGENTS.md files, no skills — only what you write here. Keep it focused.
+
+## Available Tools
+
+Built-in pi tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
+
+The `subagent` tool is never available to sub-agents (prevents accidental recursion). Sub-agents run at one level of delegation only; they cannot spawn further sub-agents.
+
+Custom/extension tools are NOT available to sub-agents by default (each runs in an isolated in-memory session with no extensions).
+
+## Model Resolution
+
+Model IDs are resolved via `getModel("provider", "id")`. Common values:
+- `claude-haiku-4-5` (Anthropic Haiku — fast, cheap)
+- `claude-sonnet-4-20250514` (Anthropic Sonnet — balanced)
+- `gpt-4o` (OpenAI)
+- Any model available in your pi configuration.
+
+If not specified, defaults to the parent session's model.
+
+## Token Budget
+
+Each sub-agent runs with:
+- **System prompt**: agent body only (~200-1K tokens typical)
+- **No AGENTS.md**: saves 500-5K tokens
+- **No extensions/skills loaded**: saves 200-1K tokens
+- **Thinking off**: saves reasoning overhead
+- **No compaction**: avoids compaction token cost
+
+This is ~10x leaner than spawning a full `pi` process.

package/agents.ts

@@ -34,6 +34,8 @@ interface AgentCache {
 	bundledDir: string;
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	/** File-level signature per directory (name:mtime:size for each .md file) */
+	dirSignatures: Map<string, string>;
 }
 
 let _cache: AgentCache | null = null;
@@ -98,6 +100,26 @@ function isDirectory(p: string): boolean {
 	}
 }
 
+/** Build a stable signature for agent .md files in a directory.
+ *  Returns "missing" if the directory doesn't exist, or a sorted
+ *  list of `name:mtimeMs:size` entries that catches both content
+ *  edits and add/remove/rename operations. */
+function dirSignature(dir: string): string {
+	try {
+		const entries = fs.readdirSync(dir, { withFileTypes: true })
+			.filter((e) => e.name.endsWith(".md") && (e.isFile() || e.isSymbolicLink()))
+			.map((e) => {
+				const file = path.join(dir, e.name);
+				const st = fs.statSync(file);
+				return `${e.name}:${st.mtimeMs}:${st.size}`;
+			})
+			.sort();
+		return `exists:${entries.join("|")}`;
+	} catch {
+		return "missing";
+	}
+}
+
 function findNearestProjectAgentsDir(cwd: string): string | null {
 	let currentDir = cwd;
 	while (true) {
@@ -124,14 +146,25 @@ export function discoverAgents(
 	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
-	// Check cache
+	// Check cache (with file-signature invalidation so editing agent .md files auto-detects changes)
 	if (
 		_cache &&
 		_cache.userDir === userDir &&
 		_cache.projectDir === projectAgentsDir &&
 		_cache.bundledDir === bundledAgentsDir
 	) {
-		return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir };
+		let stale = false;
+		for (const [dir, cachedSig] of _cache.dirSignatures) {
+			if (dirSignature(dir) !== cachedSig) {
+				stale = true;
+				break;
+			}
+		}
+		if (!stale) {
+			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir };
+		}
+		// Cache is stale — rebuild below
+		_cache = null;
 	}
 
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
@@ -152,12 +185,19 @@ export function discoverAgents(
 
 	const agents = Array.from(agentMap.values());
 
+	const dirSignatures = new Map<string, string>();
+	for (const dir of [userDir, projectAgentsDir, bundledAgentsDir]) {
+		if (!dir) continue;
+		dirSignatures.set(dir, dirSignature(dir));
+	}
+
 	_cache = {
 		userDir,
 		projectDir: projectAgentsDir,
 		bundledDir: bundledAgentsDir,
 		agents,
 		projectAgentsDir,
+		dirSignatures,
 	};
 
 	return { agents, projectAgentsDir };

package/index.ts

@@ -66,20 +66,34 @@ function truncateParallelOutput(output: string): string {
 	return `${truncated}\n\n[Output truncated: ${byteLength - Buffer.byteLength(truncated, "utf8")} bytes omitted.]`;
 }
 
+interface ResolvedModel {
+	model: Model | null;
+	attempted: string[];
+}
+
 function resolveModel(
 	modelName: string | undefined,
 	parentModel: Model | undefined,
-): Model | null {
+): ResolvedModel {
+	const attempted: string[] = [];
 	if (modelName) {
 		// Try as provider/id first, then fall back to anthropic/id
 		const parts = modelName.split("/");
 		if (parts.length === 2) {
-			return getModel(parts[0], parts[1]) ?? null;
+			attempted.push(modelName);
+			const found = getModel(parts[0], parts[1]) ?? null;
+			if (found) return { model: found, attempted };
+		} else {
+			// Assume Anthropic shorthand
+			attempted.push(`anthropic/${modelName}`);
+			const found = getModel("anthropic", modelName) ?? null;
+			if (found) return { model: found, attempted };
 		}
-		// Assume Anthropic shorthand
-		return getModel("anthropic", modelName) ?? null;
+	} else if (parentModel) {
+		attempted.push(`${parentModel.provider}/${parentModel.id}`);
+		return { model: parentModel, attempted };
 	}
-	return parentModel ?? null;
+	return { model: null, attempted };
 }
 
 // ---------------------------------------------------------------------------
@@ -90,12 +104,14 @@ const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds for this task" })),
 });
 
 const ChainItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds for this step" })),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -123,6 +139,8 @@ const SubagentParams = Type.Object({
 		}),
 	),
 	cwd: Type.Optional(Type.String({ description: "Working directory (single mode)" })),
+	timeout: Type.Optional(Type.Number({ description: "Global timeout in milliseconds for all sub-agents (overridden by per-task/step timeouts)" })),
+	abortOnFailure: Type.Optional(Type.Boolean({ description: "In parallel mode, cancel remaining tasks when one fails. Default: false.", default: false })),
 });
 
 // ---------------------------------------------------------------------------
@@ -321,6 +339,8 @@ export default function (pi: ExtensionAPI) {
 				agentName: string,
 				task: string,
 				cwd: string | undefined,
+				parentSignal?: AbortSignal,
+				timeoutMs?: number,
 			): Promise<SubAgentResult> {
 				const agent = agents.find((a) => a.name === agentName);
 
@@ -337,35 +357,76 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const model = resolveModel(agent.model, ctx.model);
-				if (!model) {
+				const resolved = resolveModel(agent.model, ctx.model);
+				if (!resolved.model) {
+					const tried = resolved.attempted.join(", ") || "none";
+					const parentInfo = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none";
 					return {
 						agent: agentName,
 						task,
 						exitCode: 1,
 						messages: [],
-						stderr: `No model resolved for agent "${agentName}". Configure a model in the agent definition or select one in the parent session.`,
+						stderr: `Model not found for agent "${agentName}". Tried: ${tried}. Parent model: ${parentInfo}. Check agent definition and pi model configuration.`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-						errorMessage: "No model resolved",
+						errorMessage: `No model resolved (tried: ${tried})`,
 					};
 				}
 
 				// Inject parent's API key so --api-key and other runtime overrides work
-				await injectApiKey(model);
-
-				const tools = agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
+				await injectApiKey(resolved.model);
+
+				// Resolve tools; strip "subagent" to prevent accidental recursion.
+				// Sub-agents cannot spawn further sub-agents (one level of delegation only).
+				const defaultTools = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+				let tools = agent.tools ?? defaultTools;
+				tools = tools.filter((t) => t !== "subagent");
+
+				// Build timeout + parent signal into a combined AbortSignal
+				let combinedSignal = parentSignal;
+				let timeoutId: ReturnType<typeof setTimeout> | undefined;
+				let timeoutController: AbortController | undefined;
+				if (timeoutMs && timeoutMs > 0) {
+					timeoutController = new AbortController();
+					timeoutId = setTimeout(() => {
+						timeoutController!.abort();
+					}, timeoutMs);
+					// Combine with parent signal if present (Node 20+ AbortSignal.any)
+					if (parentSignal && typeof (AbortSignal as any).any === "function") {
+						combinedSignal = (AbortSignal as any).any([parentSignal, timeoutController.signal]);
+					} else if (parentSignal) {
+						combinedSignal = timeoutController.signal;
+						// Link parent to timeout: if parent aborts, also abort our timeout controller
+						if (parentSignal.aborted) timeoutController.abort();
+						else parentSignal.addEventListener("abort", () => timeoutController!.abort(), { once: true });
+					} else {
+						combinedSignal = timeoutController.signal;
+					}
+				}
 
-				return runSubAgent({
+				const result = await runSubAgent({
 					cwd: cwd ?? ctx.cwd,
 					systemPrompt: agent.systemPrompt,
 					task,
 					tools,
-					model,
+					model: resolved.model,
 					authStorage,
 					modelRegistry,
-					signal,
+					signal: combinedSignal,
 					agentName,
 				});
+
+				// Clean up timeout
+				if (timeoutId) clearTimeout(timeoutId);
+
+				// Detect timeout: our timeout controller fired, not the parent
+				const timedOut = timeoutController?.signal.aborted && !parentSignal?.aborted;
+				if (timedOut) {
+					result.exitCode = 1;
+					result.stopReason = "timeout";
+					if (!result.errorMessage) result.errorMessage = `Timeout after ${timeoutMs}ms`;
+				}
+
+				return result;
 			}
 
 			// --- Chain mode ---
@@ -377,7 +438,10 @@ export default function (pi: ExtensionAPI) {
 					const step = params.chain[i];
 					const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
 
-					const result = await runOne(step.agent, taskWithContext, step.cwd);
+					const result = await runOne(
+						step.agent, taskWithContext, step.cwd,
+						signal, step.timeout ?? params.timeout,
+					);
 					results.push(result);
 
 					const isError = isFailedResult(result);
@@ -389,13 +453,21 @@ export default function (pi: ExtensionAPI) {
 								details: makeDetails("chain")(results),
 							});
 						}
+						// Include successful previous step outputs in the error content
+						const prevCount = i;
+						let contentText = `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}`;
+						if (prevCount > 0) {
+							const prevSummaries = results
+								.slice(0, prevCount)
+								.map((r, j) => {
+									const out = getResultOutput(r).slice(0, 500);
+									return `Step ${j + 1} (${r.agent}): ${out}`;
+								})
+								.join("\n");
+							contentText = `Chain stopped at step ${i + 1}/${params.chain.length}. ${prevCount} previous step(s) succeeded:\n\n${prevSummaries}\n\nError at step ${i + 1} (${step.agent}): ${errorMsg}`;
+						}
 						return {
-							content: [
-								{
-									type: "text",
-									text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}`,
-								},
-							],
+							content: [{ type: "text", text: contentText }],
 							details: makeDetails("chain")(results),
 							isError: true,
 						};
@@ -434,6 +506,22 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
+				const abortOnFailure = params.abortOnFailure ?? false;
+				const parallelController = new AbortController();
+
+				// Combine parent signal with parallel abort controller
+				let parallelSignal: AbortSignal = parallelController.signal;
+				if (signal) {
+					// Always link parent abort into parallelController so queued tasks see aborted state
+					if (signal.aborted) parallelController.abort();
+					else signal.addEventListener("abort", () => parallelController.abort(), { once: true });
+					if (typeof (AbortSignal as any).any === "function") {
+						parallelSignal = (AbortSignal as any).any([signal, parallelController.signal]);
+					} else {
+						parallelSignal = parallelController.signal;
+					}
+				}
+
 				const allResults: SubAgentResult[] = new Array(params.tasks.length);
 				// Initialize placeholder results for streaming
 				for (let i = 0; i < params.tasks.length; i++) {
@@ -467,14 +555,40 @@ export default function (pi: ExtensionAPI) {
 					params.tasks,
 					MAX_CONCURRENCY,
 					async (t, index) => {
-						const result = await runOne(t.agent, t.task, t.cwd);
+						// Skip if already aborted by sibling failure or parent abort
+						if (parallelSignal.aborted || parallelController.signal.aborted) {
+							const skippedResult: SubAgentResult = {
+								agent: t.agent,
+								task: t.task,
+								exitCode: 1,
+								messages: [],
+								stderr: "",
+								usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+								stopReason: "aborted",
+								errorMessage: parallelController.signal.aborted
+								? "Cancelled: sibling task failed"
+								: "Cancelled: parent operation aborted",
+							};
+							allResults[index] = skippedResult;
+							emitParallelUpdate();
+							return skippedResult;
+						}
+						const result = await runOne(
+							t.agent, t.task, t.cwd,
+							parallelSignal, t.timeout ?? params.timeout,
+						);
 						allResults[index] = result;
+						// Early-abort: if this task failed and abortOnFailure is set
+						if (abortOnFailure && isFailedResult(result)) {
+							parallelController.abort();
+						}
 						emitParallelUpdate();
 						return result;
 					},
 				);
 
 				const successCount = results.filter((r) => !isFailedResult(r)).length;
+				const cancelCount = results.filter((r) => r.stopReason === "aborted" && r.errorMessage?.includes("Cancelled")).length;
 				const summaries = results.map((r) => {
 					const output = truncateParallelOutput(getResultOutput(r));
 					const status = isFailedResult(r)
@@ -483,11 +597,13 @@ export default function (pi: ExtensionAPI) {
 					return `### [${r.agent}] ${status}\n\n${output}`;
 				});
 
+				let headerText = `Parallel: ${successCount}/${results.length} succeeded`;
+				if (cancelCount > 0) headerText += ` (${cancelCount} cancelled)`;
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`,
+							text: `${headerText}\n\n${summaries.join("\n\n---\n\n")}`,
 						},
 					],
 					details: makeDetails("parallel")(results),
@@ -496,7 +612,10 @@ export default function (pi: ExtensionAPI) {
 
 			// --- Single mode ---
 			if (params.agent && params.task) {
-				const result = await runOne(params.agent, params.task, params.cwd);
+				const result = await runOne(
+					params.agent, params.task, params.cwd,
+					signal, params.timeout,
+				);
 				const isError = isFailedResult(result);
 
 				if (onUpdate) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.1.2",
+  "version": "0.2.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",
@@ -30,7 +30,8 @@
     "agents.ts",
     "runner.ts",
     "render.ts",
-    "agents/"
+    "agents/",
+    "agent-format.md"
   ],
   "pi": {
     "extensions": [

package/render.ts

@@ -180,10 +180,14 @@ export function renderSingleResult(
 		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}]`)}`;
+		if (isError && result.stopReason) {
+			const reasonColor = result.stopReason === "timeout" ? "warning" : "error";
+			header += ` ${theme.fg(reasonColor, `[${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));
+			const messageColor = result.stopReason === "timeout" ? "warning" : "error";
+			container.addChild(new Text(theme.fg(messageColor, `Error: ${result.errorMessage}`), 0, 0));
 		}
 		container.addChild(new Spacer(1));
 		container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
@@ -218,8 +222,14 @@ export function renderSingleResult(
 
 	// 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}`)}`;
+	if (isError && result.stopReason) {
+		const reasonColor = result.stopReason === "timeout" ? "warning" : "error";
+		text += ` ${theme.fg(reasonColor, `[${result.stopReason}]`)}`;
+	}
+	if (isError && result.errorMessage) {
+		const messageColor = result.stopReason === "timeout" ? "warning" : "error";
+		text += `\n${theme.fg(messageColor, `Error: ${result.errorMessage}`)}`;
+	}
 	else if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
 	else {
 		text += `\n${renderDisplayItems(displayItems, theme, COLLAPSED_ITEM_COUNT)}`;

package/runner.ts

@@ -123,6 +123,7 @@ export async function runSubAgent(options: {
 
 		try {
 			// Wire abort signal
+			let cleanupAbort: (() => void) | undefined;
 			if (signal) {
 				const onAbort = () => session.abort();
 				if (signal.aborted) {
@@ -134,10 +135,7 @@ export async function runSubAgent(options: {
 					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
+				cleanupAbort = () => signal.removeEventListener("abort", onAbort);
 			}
 
 			// Collect all messages and usage stats from events
@@ -190,6 +188,7 @@ export async function runSubAgent(options: {
 			result.exitCode = 0;
 			return result;
 		} finally {
+			cleanupAbort?.();
 			try {
 				session.dispose();
 			} catch {
@@ -210,13 +209,26 @@ export async function runSubAgent(options: {
 // ---------------------------------------------------------------------------
 
 export function getFinalOutput(messages: Message[]): string {
+	// Prefer the last assistant message with non-empty text and NO tool calls (pure final answer).
 	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;
-			}
+		if (msg.role !== "assistant") continue;
+		const texts: string[] = [];
+		let hasToolCalls = false;
+		for (const part of msg.content) {
+			if (part.type === "text" && part.text.trim()) texts.push(part.text);
+			else if (part.type === "toolCall") hasToolCalls = true;
 		}
+		if (texts.length > 0 && !hasToolCalls) return texts.join("");
+	}
+	// Fallback: last assistant message with any non-empty text (even if it also has tool calls).
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role !== "assistant") continue;
+		const texts = msg.content
+			.filter((p): p is { type: "text"; text: string } => p.type === "text" && p.text.trim().length > 0)
+			.map((p) => p.text);
+		if (texts.length > 0) return texts.join("");
 	}
 	return "";
 }
@@ -225,7 +237,8 @@ export function isFailedResult(result: SubAgentResult): boolean {
 	return (
 		result.exitCode !== 0 ||
 		result.stopReason === "error" ||
-		result.stopReason === "aborted"
+		result.stopReason === "aborted" ||
+		result.stopReason === "timeout"
 	);
 }