@bacnh85/pi-subagent 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# pi-subagent
+
+Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context — running in-process via the pi SDK for zero spawn overhead and ~10x fewer tokens than process-spawning.
+
+## Features
+
+- **In-process execution**: Uses `createAgentSession()` directly — no `spawn("pi")` overhead
+- **Minimal token budget**: Only the agent's system prompt (no AGENTS.md, no extensions, no thinking)
+- **Streaming progress**: Real-time tool-call and text updates during execution
+- **Three modes**: single, parallel (max 8 tasks, 4 concurrent), chain (sequential with `{previous}`)
+- **Abort support**: Esc propagates to all sub-agents
+- **TUI rendering**: Collapsed/expanded views with tool-call formatting and usage stats
+- **Bundled agents**: scout, reviewer, worker — overridable with your own
+
+## Install
+
+```bash
+cd extensions/pi-subagent
+npm install
+cd ../..
+pi install ./extensions/pi-subagent
+```
+
+Or test directly:
+
+```bash
+pi -e ./extensions/pi-subagent
+```
+
+## Usage
+
+### Single agent
+
+```
+Use scout to find authentication code in this project
+```
+
+### Parallel execution
+
+```
+Run 2 scouts in parallel: one for models, one for providers
+```
+
+### Chain workflow
+
+```
+Chain: scout finds auth code, then reviewer checks it for security issues
+```
+
+## Included Agents
+
+| Agent | Model | Tools | Purpose |
+|-------|-------|-------|---------|
+| `scout` | Haiku | read, grep, find, ls | Fast codebase recon |
+| `reviewer` | Sonnet | read, grep, find, ls, bash | Code review |
+| `worker` | Sonnet | all | General implementation |
+
+## Custom Agents
+
+Create Markdown files with YAML frontmatter in `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level):
+
+```markdown
+---
+name: my-agent
+description: When to use this agent
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+---
+
+Your system prompt here. This is the ONLY prompt the sub-agent sees.
+```
+
+See `agent-format.md` for the full format specification.
+
+## Architecture
+
+Sub-agents run in-process via the pi SDK. Compared to the process-spawn approach (spawning `pi --mode json`), this saves ~4-11K tokens per sub-agent invocation by:
+
+- Using only the agent's system prompt (no pi defaults)
+- Skipping AGENTS.md, extensions, skills, prompt templates
+- Disabling thinking, compaction, retry
+- Using in-memory sessions (no disk I/O)
+- Sharing the parent's auth/model infrastructure
+
+## Requirements
+
+- pi coding agent with configured API keys
+- Peer dependencies satisfied by the pi runtime (no extra npm install needed)

package/agents/reviewer.md

@@ -0,0 +1,30 @@
+---
+name: reviewer
+description: Code review specialist. Use for reviewing changes, finding bugs, suggesting improvements.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-20250514
+---
+
+You are a senior code reviewer. Review code changes and provide specific, actionable feedback.
+
+Focus on:
+1. **Correctness**: Logic errors, edge cases, off-by-one
+2. **Security**: Injection risks, auth bypasses, data leaks
+3. **Performance**: N+1 queries, unnecessary allocations, blocking calls
+4. **Maintainability**: Unclear naming, missing error handling, tight coupling
+5. **Best practices**: Idiomatic patterns, testability, documentation
+
+Output format:
+
+## Summary
+Brief assessment (1-2 sentences)
+
+## Issues Found
+For each issue:
+- **Severity**: critical | high | medium | low
+- **File**: path with line numbers
+- **Problem**: What's wrong
+- **Fix**: Suggested change (code block)
+
+## Overall Assessment
+Green/yellow/red with reasoning.

package/agents/scout.md

@@ -0,0 +1,44 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Thoroughness (infer from task, default medium):
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Output format:
+
+## Files Retrieved
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Code
+Critical types, interfaces, or functions:
+
+```typescript
+interface Example {
+  // actual code from the files
+}
+```
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.

package/agents/worker.md

@@ -0,0 +1,15 @@
+---
+name: worker
+description: General-purpose coding agent with full tool access. Use for implementation, refactoring, debugging, and complex multi-step tasks.
+model: claude-sonnet-4-20250514
+---
+
+You are a skilled software engineer. Implement the requested task with care and precision.
+
+Guidelines:
+- Read before you edit. Understand existing code first.
+- Make minimal, focused changes. Do not refactor unrelated code.
+- Follow existing patterns, naming, and formatting.
+- Write clear, idiomatic code with appropriate error handling.
+- Test your changes when practical (run tests, lint, type-check).
+- Explain your approach briefly before making changes.

package/agents.ts

@@ -0,0 +1,174 @@
+/**
+ * Agent discovery and configuration for pi-sugagents.
+ *
+ * Loads agent definitions from Markdown files with YAML frontmatter.
+ * Discovers from user-level (~/.pi/agent/agents/), project-level
+ * (.pi/agents/), and bundled skill agents. Results are cached and
+ * invalidated on /reload.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: "user" | "project" | "bundled";
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+interface AgentCache {
+	userDir: string;
+	projectDir: string | null;
+	bundledDir: string;
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+let _cache: AgentCache | null = null;
+
+/** Clear the agent cache (call on /reload). */
+export function invalidateAgentCache(): void {
+	_cache = null;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+
+	if (!fs.existsSync(dir)) return agents;
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = path.join(dir, entry.name);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+
+		if (!frontmatter.name || !frontmatter.description) continue;
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t: string) => t.trim())
+			.filter(Boolean);
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model || undefined,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+/**
+ * Discover agents from standard locations plus bundled skill agents.
+ * @param cwd - Working directory for project-level discovery.
+ * @param scope - Which agent directories to use.
+ * @param bundledAgentsDir - Path to skill-bundled agents directory.
+ */
+export function discoverAgents(
+	cwd: string,
+	scope: AgentScope,
+	bundledAgentsDir: string,
+): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	// Check cache
+	if (
+		_cache &&
+		_cache.userDir === userDir &&
+		_cache.projectDir === projectAgentsDir &&
+		_cache.bundledDir === bundledAgentsDir
+	) {
+		return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir };
+	}
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents =
+		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+	const bundledAgents = loadAgentsFromDir(bundledAgentsDir, "bundled");
+
+	const agentMap = new Map<string, AgentConfig>();
+
+	// Priority: bundled < user < project (higher index = higher priority)
+	for (const agent of bundledAgents) agentMap.set(agent.name, agent);
+	if (scope === "both" || scope === "user") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+	}
+	if (scope === "both" || scope === "project") {
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	}
+
+	const agents = Array.from(agentMap.values());
+
+	_cache = {
+		userDir,
+		projectDir: projectAgentsDir,
+		bundledDir: bundledAgentsDir,
+		agents,
+		projectAgentsDir,
+	};
+
+	return { agents, projectAgentsDir };
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}