@narumitw/pi-subagents 0.1.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @narumitw/pi-subagents
+
+Delegate work from Pi to specialized subagents running in isolated `pi --mode json -p --no-session` subprocesses.
+
+## Install
+
+```bash
+pi install npm:@narumitw/pi-subagents
+```
+
+Try locally from this repository:
+
+```bash
+pi -e ./extensions/pi-subagents
+```
+
+## What it adds
+
+A `subagent` tool with three execution modes:
+
+- **single**: run one `{ agent, task }`
+- **parallel**: run multiple `{ agent, task }` jobs with bounded concurrency
+- **parallel + aggregator**: run parallel jobs, then fan their complete outputs into one follow-up agent
+- **chain**: run sequential steps, passing prior output with `{previous}`
+
+The design borrows from Pi/Claude-style subagents: each worker has its own system prompt, tool boundary, optional model, subprocess context window, streaming progress, abort propagation, hard subprocess timeout, complete final output in tool details, and summarized sidechain result.
+
+## Built-in agents
+
+These are available without setup and can be overridden by user/project agents of the same name:
+
+| Agent | Purpose | Tools |
+| --- | --- | --- |
+| `scout` | Read-only codebase reconnaissance | `read`, `grep`, `find`, `ls`, `bash` |
+| `planner` | Grounded implementation plans | `read`, `grep`, `find`, `ls` |
+| `reviewer` | Independent review and verification | `read`, `grep`, `find`, `ls`, `bash` |
+| `worker` | General-purpose implementation | Pi default tools |
+| `general`, `general-purpose` | Aliases for `worker` | Pi default tools |
+
+Built-in agents intentionally inherit the active/default Pi model instead of forcing a model alias; this keeps subprocesses usable across provider setups.
+
+## Custom agents
+
+Create markdown files in:
+
+- `~/.pi/agent/agents/*.md` for user agents
+- `.pi/agents/*.md` for project agents
+
+```markdown
+---
+name: api-reviewer
+description: Review API changes for compatibility and tests
+tools: read, grep, find, ls, bash
+model: sonnet
+---
+
+You are an API review subagent. Do not edit files. Check compatibility,
+test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
+```
+
+Project agents are repo-controlled and disabled by default. To allow them, set `agentScope` to `"project"` or `"both"`; interactive sessions ask for confirmation.
+
+## Runtime limits
+
+Each subagent subprocess has a hard timeout to avoid runaway workers. Set `timeoutMs` on the top-level call or per task/chain step. The default is `PI_SUBAGENT_TIMEOUT_MS`, or 600000ms (10 minutes) when unset. On timeout, the extension sends SIGTERM, escalates to SIGKILL after a short grace period, and returns any partial messages/stderr collected so far.
+
+## Example tool calls
+
+Single:
+
+```json
+{ "agent": "scout", "task": "Find the statusline extension entry points" }
+```
+
+Parallel:
+
+```json
+{
+  "tasks": [
+    { "agent": "scout", "task": "Map package metadata files", "timeoutMs": 30000 },
+    { "agent": "reviewer", "task": "Review TypeScript config consistency" }
+  ],
+  "timeoutMs": 120000
+}
+```
+
+Parallel with fan-in aggregation:
+
+```json
+{
+  "tasks": [
+    { "agent": "scout", "task": "Find auth-related code" },
+    { "agent": "scout", "task": "Find auth-related tests" }
+  ],
+  "aggregator": {
+    "agent": "reviewer",
+    "task": "Merge, dedupe, and verify these findings. Use {previous}."
+  }
+}
+```
+
+Chain:
+
+```json
+{
+  "chain": [
+    { "agent": "scout", "task": "Find subagent-related code" },
+    { "agent": "planner", "task": "Using this context, plan the extension: {previous}" }
+  ]
+}
+```
+
+## Safety notes
+
+Subagents are separate Pi processes and may use the tools allowed by their agent definition. Treat project-local agent prompts as code: only enable them in trusted repositories.

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@narumitw/pi-subagents",
+	"version": "0.1.10",
+	"description": "Pi extension for delegating work to specialized isolated subagents.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"subagents",
+		"agents",
+		"automation"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/subagents.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@mariozechner/pi-agent-core": "0.73.0",
+		"@mariozechner/pi-ai": "0.73.0",
+		"@mariozechner/pi-coding-agent": "0.73.0",
+		"@mariozechner/pi-tui": "0.73.0",
+		"typebox": "^1.1.37"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"typescript": "6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-subagents"
+	}
+}

package/src/agents.ts

@@ -0,0 +1,201 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+
+export type AgentSource = "built-in" | "user" | "project";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: AgentSource;
+	filePath: string;
+}
+
+const BUILT_IN_AGENTS: AgentConfig[] = [
+	{
+		name: "scout",
+		description: "Read-only codebase reconnaissance; returns concise findings with paths and evidence.",
+		tools: ["read", "grep", "find", "ls", "bash"],
+		source: "built-in",
+		filePath: "built-in:scout",
+		systemPrompt: [
+			"You are a scout subagent. Explore the codebase quickly and report grounded findings.",
+			"Do not edit files. Prefer read, grep, find, ls, and safe bash inspection commands.",
+			"Return concise bullets with exact file paths, symbols, and open questions.",
+		].join("\n"),
+	},
+	{
+		name: "planner",
+		description: "Turns reconnaissance into a lean implementation or migration plan.",
+		tools: ["read", "grep", "find", "ls"],
+		source: "built-in",
+		filePath: "built-in:planner",
+		systemPrompt: [
+			"You are a planner subagent. Produce executable, verifiable plans only.",
+			"Do not modify files. Ground the plan in the repository's actual structure.",
+			"Call out assumptions, risks, sequencing, and verification commands.",
+		].join("\n"),
+	},
+	{
+		name: "reviewer",
+		description: "Independent code review and verification agent for completed changes.",
+		tools: ["read", "grep", "find", "ls", "bash"],
+		source: "built-in",
+		filePath: "built-in:reviewer",
+		systemPrompt: [
+			"You are a reviewer subagent. Review changes adversarially and verify claims.",
+			"Do not edit files. Run safe inspection or test commands when useful.",
+			"Report PASS, FAIL, or PARTIAL with evidence, commands run, and specific follow-ups.",
+		].join("\n"),
+	},
+	{
+		name: "worker",
+		description: "General-purpose implementation worker with the default Pi tool set.",
+		source: "built-in",
+		filePath: "built-in:worker",
+		systemPrompt: workerSystemPrompt(),
+	},
+	{
+		name: "general",
+		description: "Alias for worker; kept for model-generated subagent names.",
+		source: "built-in",
+		filePath: "built-in:general",
+		systemPrompt: workerSystemPrompt(),
+	},
+	{
+		name: "general-purpose",
+		description: "Alias for worker; compatible with common subagent naming conventions.",
+		source: "built-in",
+		filePath: "built-in:general-purpose",
+		systemPrompt: workerSystemPrompt(),
+	},
+];
+
+function workerSystemPrompt(): string {
+	return [
+		"You are a focused worker subagent running in an isolated Pi process.",
+		"Complete the delegated task directly. Keep scope tight and avoid unrelated changes.",
+		"When done, summarize files changed, commands run, and any remaining risks.",
+	].join("\n");
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): 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,
+			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, ".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 userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	const agentMap = new Map<string, AgentConfig>();
+
+	// Lowest priority: built-ins are always available, then user agents, then
+	// trusted project agents if requested. This mirrors the subagent boundary
+	// pattern in ./src: stable built-ins plus overridable local definitions.
+	for (const agent of BUILT_IN_AGENTS) agentMap.set(agent.name, agent);
+
+	if (scope === "both") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	} else if (scope === "user") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+	} else {
+		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,
+	};
+}