@pi-archimedes/subagent 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,96 @@
+# @pi-archimedes/subagent
+
+Subagent dispatch with live TUI streaming and cost tracking for the [Pi coding agent](https://github.com/earendil-works/pi).
+
+## Features
+
+- **Single & parallel execution** — dispatch one task or fan out multiple tasks across different agents simultaneously
+- **Live TUI streaming** — watch subagent progress in real-time with tool calls, token counts, and cost updates
+- **Agent discovery** — auto-discovers agents from `.pi/agents/*.md` files at project, user, and global scope
+- **Per-agent model override** — each subagent can use its own model, falling back to the parent's selection
+- **Cost tracking** — detailed token usage (input, output, cache read/write) and cost per subagent, emitted through the core bus for the footer to consume
+- **`/agents` command** — full CRUD TUI for managing agent definitions with model picker, tool picker, and cross-scope collision warnings (available via the meta package)
+
+## Screenshots
+
+### Main view — parallel execution
+
+Live progress panel showing two parallel subagents with token stats, cost, and recent output:
+
+![subagents main view](../../docs/images/subagents-main-view.png)
+
+### Agent details view
+
+Browse and inspect agent configurations — name, model, tools, system prompt, and more:
+
+![subagents agent view](../../docs/images/subagents-agent-view.png)
+
+### Model selection
+
+Pick from all available models registered in Pi's model registry:
+
+![subagents model selection](../../docs/images/subagents-model-selection.png)
+
+### Tool selection
+
+Toggle which tools are available to an agent from Pi's full toolset:
+
+![subagents tool selection](../../docs/images/subagents-tool-selection.png)
+
+## Installation
+
+```bash
+pi install @pi-archimedes/subagent
+```
+
+Or install the full [pi-archimedes](../..) meta package for the integrated experience (cost tracking in footer, shared chrome, etc.):
+
+```bash
+pi install pi-archimedes
+```
+
+## Usage
+
+### As a tool
+
+The `subagent` tool accepts either a single `task` or an array of `tasks` for parallel execution:
+
+```jsonc
+{
+  "agent": "reviewer",     // optional, defaults to "general"
+  "task": "review the PR", // single task
+  "model": "openrouter/anthropic/claude-4", // optional override
+  "cwd": "/path/to/dir"    // optional working directory
+}
+```
+
+Parallel mode:
+
+```jsonc
+{
+  "tasks": [
+    { "agent": "researcher", "task": "find all usages of foo" },
+    { "agent": "reviewer", "task": "review the implementation plan" }
+  ]
+}
+```
+
+### As a command
+
+Run `/agents` to open the interactive Agents Manager for creating, editing, and deleting agent definitions.
+
+## Agent files
+
+Agents are defined as `.md` files with YAML frontmatter, placed in one of:
+
+- **Project scope:** `<cwd>/.pi/agents/` — available only in this project
+- **User scope:** `~/.pi/agents/` — available across all projects
+- **Global scope:** installed via packages or extensions
+
+Frontmatter supports: `name`, `model`, `tools`, `thinking`, `inheritProjectContext`, `inheritSkills`, `systemPromptMode`, and `systemPrompt`.
+
+## Integration
+
+When installed via `pi-archimedes` (the meta package), subagent cost events flow through `@pi-archimedes/core/bus` and are consumed by `@pi-archimedes/footer`'s `CostAccumulator`. This merges subagent tokens and cost into the main status bar for a unified view.
+
+The `/agents` command is also only registered by the meta package (not by standalone `@pi-archimedes/subagent`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.0.0"
+    "@pi-archimedes/core": "1.2.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",
@@ -26,6 +26,7 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/subagents-main-view.png"
   }
 }

package/src/agent-manager.ts

@@ -54,8 +54,10 @@ interface ToolInfo {
 interface ManagerState {
   screen: "list" | "detail" | "edit" | "name-input" | "confirm-delete";
   agents: AgentConfig[];
+  globalAgents: AgentConfig[];
   userAgents: AgentConfig[];
   projectAgents: AgentConfig[];
+  globalDir: string | null;
   userDir: string;
   projectDir: string | null;
 
@@ -86,7 +88,7 @@ interface ManagerState {
   // Name input state
   nameInputBuffer: string;
   nameInputCursor: number;
-  nameInputScope: "user" | "project";
+  nameInputScope: "global" | "user" | "project";
   nameInputMode: "new" | "clone";
   nameInputSource: AgentConfig | null;
   nameInputError: string | null;
@@ -188,7 +190,8 @@ function renderFooter(text: string, width: number, theme: Theme): string {
   return theme.fg("dim", padEnd(text, width));
 }
 
-function scopeLabel(source: "user" | "project"): string {
+function scopeLabel(source: "global" | "user" | "project"): string {
+  if (source === "global") return "home";
   return source === "user" ? "user" : "proj";
 }
 
@@ -1225,7 +1228,9 @@ function saveAgent(state: ManagerState, requestRender: () => void): void {
   }
 
   // Determine target directory
-  const dir = agent.source === "user" ? state.userDir : state.projectDir;
+  const dir = agent.source === "global" ? state.globalDir
+    : agent.source === "user" ? state.userDir
+    : state.projectDir;
   if (!dir) {
     state.editError = "Target directory not available";
     requestRender();
@@ -1259,9 +1264,11 @@ function saveAgent(state: ManagerState, requestRender: () => void): void {
     // Refresh agents list
     const cwd = process.cwd();
     const discovery = discoverAgentsAll(cwd);
+    state.globalAgents = discovery.global;
     state.userAgents = discovery.user;
     state.projectAgents = discovery.project;
-    state.agents = [...discovery.user, ...discovery.project];
+    state.globalDir = discovery.globalDir;
+    state.agents = [...discovery.global, ...discovery.user, ...discovery.project];
 
     // Find the saved agent and switch to detail
     const savedAgent = state.agents.find((a) => a.name === agent.name && a.source === agent.source);
@@ -1305,12 +1312,22 @@ function renderNameInput(state: ManagerState, width: number, theme: Theme): stri
   const scopeText = `Scope: [${state.nameInputScope}]  [tab] toggle`;
   lines.push(padEnd(theme.fg("dim", scopeText), width));
 
-  // Cross-scope collision warning
-  const otherScope = state.nameInputScope === "user" ? "project" : "user";
-  const otherScopeAgents = otherScope === "user" ? state.userAgents : state.projectAgents;
-  const collisionAgent = otherScopeAgents.find((a) => a.name === state.nameInputBuffer.trim());
+  // Cross-scope collision warning — check higher-precedence scopes
+  const scopeOrder = ["global", "user", "project"];
+  const currentIdx = scopeOrder.indexOf(state.nameInputScope);
+  let collisionAgent: AgentConfig | undefined;
+  let collisionScope: string | undefined;
+  for (const scope of scopeOrder.slice(currentIdx + 1)) {
+    const scopeAgents = scope === "global" ? state.globalAgents : scope === "user" ? state.userAgents : state.projectAgents;
+    const found = scopeAgents.find((a) => a.name === state.nameInputBuffer.trim());
+    if (found) {
+      collisionAgent = found;
+      collisionScope = scope;
+      break;
+    }
+  }
   if (collisionAgent) {
-    lines.push(padEnd(theme.fg("warning", `Warning: a ${otherScope} agent "${collisionAgent.name}" exists and will take precedence`), width));
+    lines.push(padEnd(theme.fg("warning", `Warning: a ${collisionScope} agent "${collisionAgent.name}" exists and will take precedence`), width));
   } else if (state.nameInputError) {
     lines.push(padEnd(theme.fg("error", `  ${state.nameInputError}`), width));
   } else {
@@ -1329,8 +1346,13 @@ function handleNameInput(
   requestRender: () => void,
 ): void {
   if (matchesKey(data, Key.tab)) {
-    state.nameInputScope = state.nameInputScope === "user" ? "project" : "user";
-    if (state.nameInputScope === "project" && !state.projectDir) {
+    const scopes = ["global", "user", "project"];
+    const currentIdx = scopes.indexOf(state.nameInputScope);
+    const nextIdx = (currentIdx + 1) % scopes.length;
+    state.nameInputScope = scopes[nextIdx] as "global" | "user" | "project";
+    if (state.nameInputScope === "global" && !state.globalDir) {
+      state.nameInputError = "No global agents directory found";
+    } else if (state.nameInputScope === "project" && !state.projectDir) {
       state.nameInputError = "No project agents directory found";
     } else {
       state.nameInputError = null;
@@ -1363,6 +1385,11 @@ function handleNameInput(
       requestRender();
       return;
     }
+    if (state.nameInputScope === "global" && !state.globalDir) {
+      state.nameInputError = "No global agents directory found";
+      requestRender();
+      return;
+    }
     if (state.nameInputScope === "project" && !state.projectDir) {
       state.nameInputError = "No project agents directory found";
       requestRender();
@@ -1379,7 +1406,9 @@ function handleNameInput(
       return;
     }
 
-    const dir = state.nameInputScope === "user" ? state.userDir : state.projectDir;
+    const dir = state.nameInputScope === "global" ? state.globalDir
+      : state.nameInputScope === "user" ? state.userDir
+      : state.projectDir;
     if (!dir) {
       state.nameInputError = "Target directory not available";
       requestRender();
@@ -1486,9 +1515,11 @@ function handleConfirmDelete(
       // Refresh agents list
       const cwd = process.cwd();
       const discovery = discoverAgentsAll(cwd);
+      state.globalAgents = discovery.global;
       state.userAgents = discovery.user;
       state.projectAgents = discovery.project;
-      state.agents = [...discovery.user, ...discovery.project];
+      state.globalDir = discovery.globalDir;
+      state.agents = [...discovery.global, ...discovery.user, ...discovery.project];
 
       state.listCursor = 0;
       state.listScroll = 0;
@@ -1506,8 +1537,10 @@ function handleConfirmDelete(
 // ── Main factory ────────────────────────────────────────────────────────────
 
 export function createAgentManager(
+  globalAgents: AgentConfig[],
   userAgents: AgentConfig[],
   projectAgents: AgentConfig[],
+  globalDir: string | null,
   userDir: string,
   projectDir: string | null,
   tui: TUIContext,
@@ -1518,9 +1551,11 @@ export function createAgentManager(
 ): Component {
   const state: ManagerState = {
     screen: "list",
-    agents: [...userAgents, ...projectAgents],
+    agents: [...globalAgents, ...userAgents, ...projectAgents],
+    globalAgents,
     userAgents,
     projectAgents,
+    globalDir,
     userDir,
     projectDir,
 

package/src/agents.ts

@@ -4,6 +4,7 @@
  */
 
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
@@ -14,13 +15,13 @@ export interface AgentConfig {
   model?: string;
   thinking?: string;
   systemPrompt: string;
-  source: "user" | "project";
+  source: "global" | "user" | "project";
   filePath: string;
   // Extra fields preserved from frontmatter but not editable in TUI
   extraFields?: Record<string, unknown>;
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: "global" | "user" | "project"): AgentConfig[] {
   const agents: AgentConfig[] = [];
 
   if (!fs.existsSync(dir)) return agents;
@@ -102,28 +103,55 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
   }
 }
 
+function findNearestAgentsDir(cwd: string): string | null {
+  // Walk up looking for .agents/agents inside a git repo
+  let currentDir = cwd;
+  while (true) {
+    const gitPath = path.join(currentDir, ".git");
+    if (fs.existsSync(gitPath)) {
+      const projectAgentsDir = path.join(currentDir, ".agents", "agents");
+      if (fs.existsSync(projectAgentsDir)) return projectAgentsDir;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+
+  // Fallback: ~/.agents/agents
+  const homeAgentsDir = path.join(os.homedir(), ".agents", "agents");
+  if (fs.existsSync(homeAgentsDir)) return homeAgentsDir;
+  return null;
+}
+
 /**
  * Result of discovering agents — separated by source with directory paths.
  */
 export interface AgentsDiscoveryResult {
+  global: AgentConfig[];
   user: AgentConfig[];
   project: AgentConfig[];
-  userDir: string;        // e.g., ~/.pi/agent/agents
-  projectDir: string | null;  // e.g., .pi/agents or null if not found
+  globalDir: string | null;  // e.g., .agents/agents or null if not found
+  userDir: string;           // e.g., ~/.pi/agent/agents
+  projectDir: string | null; // e.g., .pi/agents or null if not found
 }
 
 /**
- * Discover all available agents from user and/or project directories.
+ * Discover all available agents from global, user and/or project directories.
+ * Precedence (highest last): global < user < project
  */
 export function discoverAgents(cwd: string): AgentConfig[] {
+  const globalDir = findNearestAgentsDir(cwd);
   const userDir = path.join(getAgentDir(), "agents");
   const projectDir = findNearestProjectAgentsDir(cwd);
 
+  const globalAgents = globalDir ? loadAgentsFromDir(globalDir, "global") : [];
   const userAgents = loadAgentsFromDir(userDir, "user");
   const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
 
-  // Project agents override user agents with the same name
+  // Later sources override earlier: global < user < project
   const agentMap = new Map<string, AgentConfig>();
+  for (const agent of globalAgents) agentMap.set(agent.name, agent);
   for (const agent of userAgents) agentMap.set(agent.name, agent);
   for (const agent of projectAgents) agentMap.set(agent.name, agent);
 
@@ -134,15 +162,19 @@ export function discoverAgents(cwd: string): AgentConfig[] {
  * Discover agents and return them separated by source with directory paths.
  */
 export function discoverAgentsAll(cwd: string): AgentsDiscoveryResult {
+  const globalDir = findNearestAgentsDir(cwd);
   const userDir = path.join(getAgentDir(), "agents");
   const projectDir = findNearestProjectAgentsDir(cwd);
 
+  const globalAgents = globalDir ? loadAgentsFromDir(globalDir, "global") : [];
   const userAgents = loadAgentsFromDir(userDir, "user");
   const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
 
   return {
+    global: globalAgents,
     user: userAgents,
     project: projectAgents,
+    globalDir,
     userDir,
     projectDir,
   };

package/src/index.ts

@@ -266,7 +266,7 @@ export function registerAgentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("agents", {
     description: "Open the Agents Manager",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
-      const { user, project, userDir, projectDir } = discoverAgentsAll(ctx.cwd);
+      const { global: globalAgents, user, project, globalDir, userDir, projectDir } = discoverAgentsAll(ctx.cwd);
 
       const availableModels = ctx.modelRegistry.getAvailable().map((m) => ({
         id: m.id,
@@ -281,7 +281,7 @@ export function registerAgentsCommand(pi: ExtensionAPI): void {
 
       await ctx.ui.custom<void>(
         (tui: TUI, theme: Theme, _keybindings, done: () => void) => {
-          return createAgentManager(user, project, userDir, projectDir, tui, theme, done, availableModels, availableTools);
+          return createAgentManager(globalAgents, user, project, globalDir, userDir, projectDir, tui, theme, done, availableModels, availableTools);
         },
         { overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } },
       );