@fosterg4/pi-subagent 1.0.0

package/README.md

@@ -0,0 +1,170 @@
+# @fosterg4/pi-subagent
+
+[![npm version](https://img.shields.io/npm/v/@fosterg4/pi-subagent)](https://www.npmjs.com/package/@fosterg4/pi-subagent)
+
+Delegate complex tasks to specialized sub-agents with isolated context windows, structured JSON handoff, contract schemas, and live TUI streaming — all within [pi](https://pi.dev).
+
+## Features
+
+- **Isolated context** — Each subagent runs in a separate `pi` process with its own context window
+- **Three execution modes** — Single, parallel (max 8, concurrency 4), and chain (sequential with data handoff)
+- **Structured JSON handoff** — Agents pass typed data between each other, not freeform markdown
+- **Contract schemas** — `inputSchema`/`outputSchema` in agent frontmatter ensures valid handoffs
+- **Live TUI streaming** — Subagent tool calls (read, bash, grep, etc.) stream in real-time
+- **Bundled agents** — 4 built-in agents ready to use: scout, planner, reviewer, worker
+- **Workflow prompts** — `/implement`, `/scout-and-plan`, `/implement-and-review` commands
+
+## Installation
+
+```bash
+pi install npm:@fosterg4/pi-subagent
+```
+
+For a quick test without installing:
+
+```bash
+pi -e npm:@fosterg4/pi-subagent
+```
+
+## Usage
+
+### Single agent
+
+Ask the LLM to use a subagent:
+
+```
+Use scout to find all authentication code in the project
+```
+
+The LLM will call the `subagent` tool with `{ agent: "scout", task: "..." }`.
+
+### Parallel execution
+
+```
+Run 2 scouts in parallel: one to find models, one to find providers
+```
+
+### Chained workflow
+
+```
+Use a chain: first have scout find the read tool, then have planner suggest improvements
+```
+
+### Workflow prompts
+
+```
+/implement add Redis caching to the session store
+/scout-and-plan refactor auth to support OAuth
+/implement-and-review add input validation to API endpoints
+```
+
+## Bundled Agents
+
+| Agent | Purpose | Default Model |
+|-------|---------|---------------|
+| `scout` | Fast codebase recon — returns structured findings | claude-haiku-4-5 |
+| `planner` | Creates implementation plans from context & requirements | claude-sonnet-4-5 |
+| `reviewer` | Code review — quality, security, maintainability | claude-sonnet-4-5 |
+| `worker` | General-purpose implementation with full capabilities | claude-sonnet-4-5 |
+
+Each agent has a defined `inputSchema` and `outputSchema` in its frontmatter, ensuring structured data flows between chained agents.
+
+## Tool Parameters
+
+The `subagent` tool accepts three mutually exclusive modes:
+
+### Single mode
+
+```json
+{
+  "agent": "scout",
+  "task": "Find all authentication code",
+  "cwd": "/optional/working/directory"
+}
+```
+
+### Parallel mode
+
+```json
+{
+  "tasks": [
+    { "agent": "scout", "task": "Find models" },
+    { "agent": "scout", "task": "Find providers" }
+  ]
+}
+```
+
+### Chain mode
+
+```json
+{
+  "chain": [
+    { "agent": "scout", "task": "Investigate the codebase" },
+    { "agent": "planner", "task": "Create a plan from: {previous}" }
+  ]
+}
+```
+
+### Common options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agentScope` | `"user"`, `"project"`, `"both"` | `"user"` | Which agent directories to search |
+| `confirmProjectAgents` | `boolean` | `true` | Prompt before running project agents |
+| `cwd` | `string` | current dir | Working directory for subprocess |
+
+## Custom Agents
+
+Create your own agents as `.md` files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+inputSchema:
+  type: object
+  properties:
+    query:
+      type: string
+  required: [query]
+outputSchema:
+  type: object
+  properties:
+    result:
+      type: string
+  required: [result]
+---
+
+System prompt for the agent goes here.
+```
+
+**Agent locations** (priority: project > user > bundled):
+- `~/.pi/agent/agents/*.md` — User-level (always loaded)
+- `.pi/agents/*.md` — Project-level (requires `agentScope: "project"` or `"both"`)
+- Bundled with package — Lowest priority, always available
+
+## Security
+
+- **User agents** (`~/.pi/agent/agents/`): Always trusted
+- **Project agents** (`.pi/agents/`): Requires confirmation prompt before execution
+- **Bundled agents**: Trusted by virtue of package installation
+
+## Development
+
+```bash
+# Clone and test locally
+git clone https://github.com/fosterg4/pi-subagent.git
+cd pi-subagent
+
+# Test with pi
+pi -e ./index.ts
+
+# Publish
+npm publish --access public
+```
+
+## License
+
+MIT

package/agents/planner.md

@@ -0,0 +1,71 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: claude-sonnet-4-5
+inputSchema:
+  type: object
+  properties:
+    findings:
+      type: object
+      description: "Scout findings or context about the codebase"
+    requirements:
+      type: string
+      description: "What needs to be built or changed"
+  required: [requirements]
+outputSchema:
+  type: object
+  properties:
+    goal:
+      type: string
+    steps:
+      type: array
+      items:
+        type: object
+        properties:
+          step: { type: number }
+          action: { type: string }
+          file: { type: string }
+          details: { type: string }
+    filesToModify:
+      type: array
+      items:
+        type: object
+        properties:
+          path: { type: string }
+          changes: { type: string }
+    newFiles:
+      type: array
+      items:
+        type: object
+        properties:
+          path: { type: string }
+          purpose: { type: string }
+    risks:
+      type: string
+  required: [goal, steps, filesToModify]
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Return your plan as a JSON object matching the outputSchema.
+
+## Output format (JSON)
+
+```json
+{
+  "goal": "One sentence summary",
+  "steps": [
+    { "step": 1, "action": "Modify function X", "file": "src/file.ts", "details": "What to change" }
+  ],
+  "filesToModify": [
+    { "path": "src/file.ts", "changes": "What changes" }
+  ],
+  "newFiles": [
+    { "path": "src/new.ts", "purpose": "Purpose" }
+  ],
+  "risks": "Anything to watch out for"
+}
+```

package/agents/reviewer.md

@@ -0,0 +1,81 @@
+---
+name: reviewer
+description: Code review specialist for quality and security analysis
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+inputSchema:
+  type: object
+  properties:
+    changes:
+      type: string
+      description: "Description of what was changed"
+    files:
+      type: array
+      items:
+        type: object
+        properties:
+          path: { type: string }
+          description: { type: string }
+  required: [changes, files]
+outputSchema:
+  type: object
+  properties:
+    filesReviewed:
+      type: array
+      items:
+        type: string
+    critical:
+      type: array
+      items:
+        type: object
+        properties:
+          location: { type: string }
+          issue: { type: string }
+    warnings:
+      type: array
+      items:
+        type: object
+        properties:
+          location: { type: string }
+          issue: { type: string }
+    suggestions:
+      type: array
+      items:
+        type: object
+        properties:
+          location: { type: string }
+          idea: { type: string }
+    summary:
+      type: string
+  required: [filesReviewed, critical, warnings, summary]
+---
+
+You are a senior code reviewer. Analyze code for quality, security, and maintainability.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
+Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
+
+Strategy:
+1. Run `git diff` to see recent changes (if applicable)
+2. Read the modified files
+3. Check for bugs, security issues, code smells
+
+Return your review as a JSON object matching the outputSchema.
+
+## Output format (JSON)
+
+```json
+{
+  "filesReviewed": ["src/file.ts"],
+  "critical": [
+    { "location": "file.ts:42", "issue": "Issue description" }
+  ],
+  "warnings": [
+    { "location": "file.ts:100", "issue": "Issue description" }
+  ],
+  "suggestions": [
+    { "location": "file.ts:150", "idea": "Improvement idea" }
+  ],
+  "summary": "Overall assessment in 2-3 sentences."
+}
+```

package/agents/scout.md

@@ -0,0 +1,66 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff to other agents
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+inputSchema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: "What to investigate"
+    thoroughness:
+      type: string
+      enum: [quick, medium, thorough]
+      description: "Depth of investigation"
+      default: medium
+  required: [query]
+outputSchema:
+  type: object
+  properties:
+    filesRetrieved:
+      type: array
+      items:
+        type: object
+        properties:
+          path: { type: string }
+          lines: { type: string }
+          description: { type: string }
+    architecture:
+      type: string
+    keyCode:
+      type: string
+    startHere:
+      type: string
+  required: [filesRetrieved, architecture]
+---
+
+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
+
+Return your findings as a JSON object matching the outputSchema.
+
+## Output format (JSON)
+
+```json
+{
+  "filesRetrieved": [
+    { "path": "src/file.ts", "lines": "10-50", "description": "What's here" }
+  ],
+  "architecture": "Brief explanation of how the pieces connect.",
+  "keyCode": "Critical code snippet",
+  "startHere": "Which file to look at first and why"
+}
+```

package/agents/worker.md

@@ -0,0 +1,48 @@
+---
+name: worker
+description: General-purpose subagent with full capabilities, isolated context
+model: claude-sonnet-4-5
+inputSchema:
+  type: object
+  properties:
+    plan:
+      type: object
+      description: "Implementation plan with steps, files, and context"
+    context:
+      type: string
+      description: "Additional context about the codebase"
+  required: [plan]
+outputSchema:
+  type: object
+  properties:
+    completed:
+      type: string
+    filesChanged:
+      type: array
+      items:
+        type: object
+        properties:
+          path: { type: string }
+          change: { type: string }
+    notes:
+      type: string
+  required: [completed, filesChanged]
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task. Use all available tools as needed.
+
+Return your results as a JSON object matching the outputSchema.
+
+## Output format (JSON)
+
+```json
+{
+  "completed": "What was done.",
+  "filesChanged": [
+    { "path": "src/file.ts", "change": "What changed" }
+  ],
+  "notes": "Anything the main agent should know."
+}
+```

package/agents.ts

@@ -0,0 +1,196 @@
+/**
+ * Agent discovery and configuration
+ *
+ * Discovers agents from three sources (lowest to highest priority):
+ * 1. Bundled agents (shipped with the @fosterg4/pi-subagent package)
+ * 2. User agents (~/.pi/agent/agents/)
+ * 3. Project agents (.pi/agents/ - requires "project" or "both" scope)
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { 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;
+	inputSchema?: Record<string, unknown>;
+	outputSchema?: Record<string, unknown>;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+/**
+ * Resolve the directory where the package's bundled agents live.
+ * Uses import.meta.url to find the package directory at runtime.
+ */
+function getBundledAgentsDir(): string | null {
+	try {
+		const currentFile = fileURLToPath(import.meta.url);
+		const packageDir = path.dirname(currentFile);
+		const bundledDir = path.join(packageDir, "agents");
+		return fs.existsSync(bundledDir) ? bundledDir : null;
+	} catch {
+		return null;
+	}
+}
+
+function loadAgentsFromDir(
+	dir: string,
+	source: AgentConfig["source"],
+): 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, unknown>>(content);
+
+		if (!frontmatter.name || !frontmatter.description) continue;
+
+		const name = String(frontmatter.name);
+		const description = String(frontmatter.description);
+
+		const toolsStr = frontmatter.tools;
+		const tools =
+			typeof toolsStr === "string"
+				? toolsStr
+						.split(",")
+						.map((t: string) => t.trim())
+						.filter(Boolean)
+				: undefined;
+
+		const model = typeof frontmatter.model === "string" ? frontmatter.model : undefined;
+
+		// Parse contract schemas (optional)
+		const inputSchema =
+			frontmatter.inputSchema && typeof frontmatter.inputSchema === "object"
+				? (frontmatter.inputSchema as Record<string, unknown>)
+				: undefined;
+
+		const outputSchema =
+			frontmatter.outputSchema && typeof frontmatter.outputSchema === "object"
+				? (frontmatter.outputSchema as Record<string, unknown>)
+				: undefined;
+
+		agents.push({
+			name,
+			description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model,
+			systemPrompt: body,
+			source,
+			filePath,
+			inputSchema,
+			outputSchema,
+		});
+	}
+
+	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, ".pi", "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(
+	cwd: string,
+	scope: AgentScope,
+): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+	const bundledDir = getBundledAgentsDir();
+
+	// Load agents from each source
+	const bundledAgents = bundledDir ? loadAgentsFromDir(bundledDir, "bundled") : [];
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents =
+		scope === "user" || !projectAgentsDir
+			? []
+			: loadAgentsFromDir(projectAgentsDir, "project");
+
+	// Merge with override priority: project > user > bundled
+	const agentMap = new Map<string, AgentConfig>();
+
+	// Lowest priority: bundled
+	for (const agent of bundledAgents) {
+		agentMap.set(agent.name, agent);
+	}
+	// Middle priority: user (overrides bundled)
+	if (scope !== "project") {
+		for (const agent of userAgents) {
+			agentMap.set(agent.name, agent);
+		}
+	}
+	// Highest priority: project (overrides user and bundled)
+	if (scope !== "user" && projectAgentsDir) {
+		for (const agent of projectAgents) {
+			agentMap.set(agent.name, agent);
+		}
+	}
+
+	return {
+		agents: Array.from(agentMap.values()),
+		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,
+	};
+}