@rohaquinlop/pi-subagents 0.2.0

package/README.md

@@ -0,0 +1,171 @@
+# @rohaquinlop/pi-subagents
+
+A [pi](https://github.com/earendil-works/pi) extension that registers a single `subagent` tool with three agents:
+
+## Installation
+
+```bash
+pi install @rohaquinlop/pi-subagents
+```
+
+| Agent | Tools | Model | Purpose |
+|-------|-------|-------|---------|
+| **scout** | read, grep, find, ls | deepseek-v4-flash | Fast codebase recon |
+| **researcher** | web_search, web_fetch | deepseek-v4-flash | Web research |
+| **worker** | read, write, edit, safe_bash, web_search, web_fetch, subagent | deepseek-v4-flash | Code changes (can dispatch scout/researcher to protect its own context) |
+
+`worker` is allowlisted to spawn only `scout` and `researcher` (via `subagent_agents` in its frontmatter), so the chain stops at depth 2 — a worker cannot recurse into another worker.
+
+## Dependencies
+
+`safe_bash` ships in this repo (`tools/safe-bash.ts`). `web_search` and `web_fetch` do not — `researcher` and `worker` depend on them. Grab those two extensions from [amosblomqvist/pi-config](https://github.com/amosblomqvist/pi-config) (`extensions/web-search/`, `extensions/web-fetch/`) and drop them into `~/.pi/agent/extensions/`. Without them the affected agents will launch with an empty tool allowlist and silently do nothing useful.
+
+## Usage
+
+One tool call = one subagent:
+```json
+{ "agent": "scout", "task": "Find all auth-related files in src/" }
+```
+
+To fan out, emit multiple `subagent` tool calls in the same assistant turn — pi runs them in parallel automatically. A per-process semaphore caps simultaneous subagents at `maxConcurrency` (default 4); calls past the cap wait their turn.
+
+Each subagent runs as an isolated `pi` process with no inherited context — all context must be in the task description.
+
+## Config
+
+Optional `config.json` next to `index.ts`:
+
+```json
+{ "maxConcurrency": 4 }
+```
+
+## Output
+
+Subagents return text only — there's no file handoff. If the parent needs artifacts, instruct the subagent to `write` them and return the path.
+
+Large outputs (>`DEFAULT_MAX_BYTES`) are head-truncated before being returned to the parent.
+
+## UI
+
+Two levels, toggled with `ctrl+o`:
+
+- **Collapsed (default):** the tool call shows one line — `subagent <agent> <60-char task preview>`. The result block shows the agent header (status, tool count, duration), the chronological tool log (one line per call, running calls marked with `▸`), the latest prose "thinking" line, and a usage line (tokens in/out, cache, cost, context-window gauge).
+- **Expanded:** the call header streams the full task body live as the parent writes it (like `write`/`edit`). The result block additionally renders the subagent's full final output as markdown. Nested children (when a worker spawns scout/researcher) render inline, indented under the row that dispatched them, with their own per-row context gauge.
+
+## Registering Agents from Other Extensions
+
+Other extensions can dynamically register and unregister agents at runtime. This is useful for domain-specific agents that should only be available when a particular extension is active.
+
+### 1. Define agent `.md` files
+
+Create markdown files with YAML frontmatter in your extension's directory (e.g. `my-extension/agents/my-agent.md`):
+
+```markdown
+---
+name: my-agent
+description: Does a specific thing
+tools: web_search, video_extract
+model: claude-sonnet-4-20250514
+---
+
+You are an agent that does a specific thing...
+```
+
+Frontmatter fields:
+- **name** (required) — unique agent name, used in `{ agent: "my-agent" }` calls
+- **description** — short description
+- **tools** — comma-separated list of tools the agent needs (builtin or extension). Include `subagent` here to let this agent spawn other agents.
+- **model** — provider-agnostic model identifier (e.g. `deepseek-v4-flash`). Pi resolves it from any registered provider that serves it.
+- **thinking** — reasoning level: `off`, `low`, `medium`, `high` (defaults to `medium`)
+- **subagent_agents** — if `subagent` is in `tools`, restrict which agents this one may spawn. Comma-separated list of agent names. Omit for no restriction. Enforced by passing `PI_SUBAGENT_ALLOWED` env to the child `pi` process — the child's subagents extension filters its registry before any tool description sees it, so the child LLM literally can't reference an agent outside the allowlist.
+
+The markdown body becomes the agent's system prompt.
+
+### 2. Register agents via `globalThis.__pi_subagents`
+
+Pi loads extensions via jiti, which creates separate module instances. Direct imports from the subagents extension will reference a different `agents` array than the one the `subagent` tool uses. Use the `globalThis` bridge instead:
+
+```typescript
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface AgentConfig {
+  name: string;
+  description: string;
+  tools: string[];
+  model: string;
+  thinking: string;        // "off" | "low" | "medium" | "high"
+  systemPrompt: string;
+  filePath: string;
+  subagentAgents?: string[]; // optional spawn-allowlist when `subagent` is in tools
+}
+
+const AGENTS_DIR = path.join(path.dirname(new URL(import.meta.url).pathname), "agents");
+
+function registerMyAgents(): void {
+  const subagents = (globalThis as any).__pi_subagents as
+    | { registerAgent: (config: AgentConfig) => void; unregisterAgent: (name: string) => void }
+    | undefined;
+  if (!subagents) return; // subagents extension not loaded
+
+  for (const entry of fs.readdirSync(AGENTS_DIR)) {
+    if (!entry.endsWith(".md")) continue;
+    const filePath = path.join(AGENTS_DIR, entry);
+    const content = fs.readFileSync(filePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+    if (!frontmatter.name) continue;
+
+    const tools = (frontmatter.tools || "").split(",").map(t => t.trim()).filter(Boolean);
+    const subagentAgents = frontmatter.subagent_agents
+      ? frontmatter.subagent_agents.split(",").map(t => t.trim()).filter(Boolean)
+      : undefined;
+    try {
+      subagents.registerAgent({
+        name: frontmatter.name,
+        description: frontmatter.description || "",
+        tools,
+        model: frontmatter.model || "anthropic/claude-sonnet-4-6",
+        thinking: frontmatter.thinking || "medium",
+        systemPrompt: body,
+        filePath,
+        ...(subagentAgents ? { subagentAgents } : {}),
+      });
+    } catch {
+      // Already registered — skip
+    }
+  }
+}
+```
+
+Call `registerMyAgents()` when your extension activates (e.g. in a command handler). The agents become available to the `subagent` tool immediately.
+
+### 3. Adding custom tool support
+
+If your agents need tools beyond the built-in set, those tools must be mapped in the `CUSTOM_TOOL_EXTENSIONS` record in `subagents/index.ts`:
+
+```typescript
+const CUSTOM_TOOL_EXTENSIONS: Record<string, string> = {
+  web_search: path.join(EXT_BASE, "web-search", "index.ts"),
+  web_fetch: path.join(EXT_BASE, "web-fetch", "index.ts"),
+  safe_bash: path.join(TOOLS_DIR, "safe-bash.ts"),
+  video_extract: path.join(EXT_BASE, "video-extract", "index.ts"),
+  youtube_search: path.join(EXT_BASE, "youtube-search", "index.ts"),
+  google_image_search: path.join(EXT_BASE, "google-image-search", "index.ts"),
+};
+```
+
+Built-in tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`) work automatically. Any other tool the agent lists in its frontmatter must have a corresponding entry here pointing to the extension's `index.ts`.
+
+The `subagent` tool itself is listed in `CUSTOM_TOOL_EXTENSIONS` pointing back to this extension's own `index.ts` — that's how an agent like `worker` can recursively spawn other agents. Recursion is bounded only by each agent's `subagent_agents` allowlist (e.g. worker can spawn scout/researcher, neither of which declares the `subagent` tool, so the chain stops at depth 2).
+
+## Structure
+
+```
+@rohaquinlop/pi-subagents/
+├── index.ts           # Extension entry point
+├── agents/            # Built-in agent configs (frontmatter + system prompt)
+├── lib/               # Pure helper functions (agent discovery, frontmatter parsing)
+└── tools/             # Extensions loaded into subagent processes
+    └── safe-bash.ts   # bash with dangerous command blocking
+```

package/agents/researcher.md

@@ -0,0 +1,47 @@
+---
+name: researcher
+description: Web researcher — searches the web and synthesizes findings
+tools: web_search, web_fetch
+model: deepseek-v4-flash
+thinking: medium
+---
+
+You are a research specialist. Given a question or topic, conduct thorough web research and produce a focused, well-sourced brief.
+
+Process:
+1. Break the question into 2-4 searchable facets
+2. Search with `web_search` using varied angles
+3. Read the answers. Identify what's well-covered, what has gaps.
+4. For the 2-3 most promising source URLs, use `web_fetch` to get full page content
+5. Synthesize everything into a brief that directly answers the question
+
+Search strategy — always vary your angles:
+- Direct answer query (the obvious one)
+- Authoritative source query (official docs, specs, primary sources)
+- Practical experience query (case studies, benchmarks, real-world usage)
+- Recent developments query (only if the topic is time-sensitive)
+
+Evaluation — what to keep vs drop:
+- Official docs and primary sources outweigh blog posts and forum threads
+- Recent sources outweigh stale ones
+- Sources that directly address the question outweigh tangentially related ones
+- Drop: SEO filler, outdated info, beginner tutorials (unless that's the audience)
+
+If the first round of searches doesn't fully answer the question, search again with refined queries targeting the gaps.
+
+Output format:
+
+## Summary
+2-3 sentence direct answer.
+
+## Findings
+Numbered findings with inline source citations:
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
+
+## Sources
+- Kept: Source Title (url) — why relevant
+- Dropped: Source Title — why excluded
+
+## Gaps
+What couldn't be answered. Suggested next steps.

package/agents/scout.md

@@ -0,0 +1,36 @@
+---
+name: scout
+description: Fast codebase recon — explores files, finds patterns, maps architecture
+tools: read, grep, find, ls
+model: deepseek-v4-flash
+thinking: medium
+---
+
+You are a scout agent. Quickly investigate a codebase and return structured findings.
+
+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 Found
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) — Description
+2. `path/to/other.ts` (lines 100-150) — Description
+
+## Key Code
+Critical types, interfaces, or functions with actual code snippets.
+
+## 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,71 @@
+---
+name: worker
+description: General-purpose worker — reads, writes, and edits code
+tools: read, write, edit, safe_bash, web_search, web_fetch, subagent
+subagent_agents: scout, researcher
+model: deepseek-v4-flash
+thinking: medium
+---
+
+You are a worker agent. You operate in an isolated context — you have no knowledge of any prior conversation.
+
+Work autonomously to complete the assigned task. All necessary context will be provided in the task description.
+
+Guidelines:
+- Read files before editing to understand existing code
+- Make targeted edits, not wholesale rewrites
+- Use safe_bash for running commands (tests, builds, installs, etc.)
+- If something fails, diagnose and fix it
+- Report what you did and what changed when done
+
+## Delegation — protecting your context window
+
+Your context is finite. Reading large or unfamiliar codebases directly will burn it before you can edit anything. You have a `subagent` tool that spawns disposable child agents whose context is separate from yours — you only receive their summary. Use it.
+
+You can dispatch:
+- **scout** — read-only recon (read, grep, find, ls). Returns a structured map of files, line ranges, and key snippets. Cheap (haiku). Use for *exploring unfamiliar territory*.
+- **researcher** — web research (web_search, web_fetch). Returns a sourced brief. Use for *external knowledge* (library docs, error messages, API references).
+
+### When to dispatch a scout vs. read directly
+
+Dispatch a scout when:
+- The task brief names a feature/area but not specific files ("fix the auth flow", "add a field to user settings")
+- You'd need to grep + read 5+ files just to orient
+- You only need to know *where* something lives or *what shape* it has, not its full source
+
+Read directly when:
+- The brief gives you explicit file paths
+- You already know the file you need to edit
+- You need the exact bytes for an `edit` call (scouts return summaries, not verbatim source — re-read the 1–3 files you actually edit)
+
+A good rhythm: **scout to find, read to edit.** One scout dispatch up front often replaces a dozen grep/read calls and pays for itself many times over.
+
+### When to dispatch a researcher vs. web_fetch directly
+
+Dispatch a researcher when:
+- The question is open-ended ("what's the idiomatic way to X in library Y")
+- You'd need to search + read 3+ pages to triangulate
+- You want sources synthesized, not raw HTML in your context
+
+Fetch directly when:
+- You already have the exact URL (a known docs page, a GitHub issue)
+- You need a single specific piece of information from one page
+
+### Parallelism
+
+If you need two independent investigations (e.g. "map the auth code" AND "look up the library's session API"), emit multiple `subagent` tool calls in the same turn — pi runs them in parallel automatically. Don't serialize independent work.
+
+### What a subagent doesn't replace
+
+Subagents can't edit files for you. You still do the `edit`/`write` calls yourself, with the focused context the scouts gave you. Treat them as a context-protecting prefetch, not a substitute for thinking.
+
+## Output format when done
+
+## Changes Made
+- `path/to/file.ts` — what changed and why
+
+## Verification
+How you verified the changes work (tests run, build succeeded, etc.)
+
+## Notes
+Any caveats, follow-up items, or decisions made.