@pi-archimedes/subagent 1.1.0 → 1.2.1

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.1.0",
+  "version": "1.2.1",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.1.0"
+    "@pi-archimedes/core": "1.2.1"
   },
   "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/compact.ts

@@ -25,6 +25,17 @@ export function buildActivityLine(
     return theme.fg("error", "✗ " + truncLine(data.error, 80));
   }
 
+  // Finished subagents always show their final status — never a stale
+  // tool call from history. This keeps compact view consistent with
+  // expanded view ("✓ Done" / "✗ Failed" at the bottom).
+  if (data.status === "completed") {
+    return theme.fg("success", "✓ Done");
+  }
+  if (data.status === "failed") {
+    return theme.fg("error", "✗ Failed");
+  }
+
+  // Running: show the current tool with live duration
   if (data.currentTool) {
     const arrow = theme.fg("muted", "↳ ");
     const argsPreview = data.currentToolArgs
@@ -43,25 +54,24 @@ export function buildActivityLine(
     return arrow + line;
   }
 
-  // Show last completed tool call from history
+  // Running, no active tool: show the most recently completed tool call
   if (data.toolCalls && data.toolCalls.length > 0) {
     const lastCall = data.toolCalls[data.toolCalls.length - 1];
     if (lastCall) return theme.fg("muted", "↳ " + lastCall);
   }
 
+  // Running, no tool history: show first line of streamed output if any
   if (data.finalOutput) {
     const firstLine = data.finalOutput.split("\n")[0] ?? "";
     return theme.fg("muted", "↳ " + truncLine(firstLine, 80));
   }
 
-  // Running with no tool info yet
+  // Running, no info yet
   if (data.status === "running") {
     return theme.fg("muted", "↳ Starting...");
   }
 
-  return data.status === "completed"
-    ? theme.fg("success", "✓ Done")
-    : theme.fg("error", "✗ Failed");
+  return "";
 }
 
 // ── Status glyph ────────────────────────────────────────────────────────────
@@ -143,7 +153,13 @@ export function renderCompactParallel(
     const agentName = result.agent ?? "agent-" + i;
     const summary = result.progressSummary ?? { toolCount: 0, tokens: 0, durationMs: 0 };
     const isRunning = progress?.status === "running";
-    const status = progress?.status ?? (result.exitCode === 0 ? "completed" : "failed");
+    // Prefer result.exitCode as the source of truth for completion status
+    // (matches expanded view). Only fall back to progress.status when the
+    // subagent is still actively running. This prevents stale or misaligned
+    // progress from showing the wrong status for a finished subagent.
+    const status: "running" | "completed" | "failed" = isRunning
+      ? "running"
+      : result.exitCode === 0 ? "completed" : "failed";
 
     const glyph = statusGlyph(isRunning, status);
     const glyphColored = status === "completed"

package/src/execute.ts

@@ -9,6 +9,7 @@ export interface ExecuteOptions {
   agentConfig: AgentConfig | undefined;
   task: string;
   model: string | undefined;
+  activeModel: string | undefined;
   cwd: string | undefined;
   signal: AbortSignal | undefined;
   onUpdate: ((progress: SubagentProgress) => void) | undefined;
@@ -30,6 +31,7 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
     const child = spawnSubagent({
       task: options.task,
       model: options.model,
+      activeModel: options.activeModel,
       cwd: options.cwd,
       signal: options.signal,
       agent: options.agentConfig,
@@ -65,12 +67,34 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
       task: options.task,
       progress: result.progress
         ? { ...result.progress, agent: agentName, durationMs }
-        : undefined,
+        : // Defensive: streamEvents should always return a progress, but if not,
+          // synthesize one so the parallel renderer stays aligned with results.
+          {
+            agent: agentName,
+            status: result.exitCode === 0 ? "completed" : "failed",
+            task: options.task,
+            currentTool: undefined,
+            currentToolArgs: undefined,
+            currentToolStartedAt: undefined,
+            toolCount: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            tokens: 0,
+            cost: 0,
+            durationMs,
+            error: undefined,
+            output: undefined,
+            recentOutput: undefined,
+            toolCalls: undefined,
+            model: result.model,
+          },
       progressSummary: result.progressSummary
         ? { ...result.progressSummary, durationMs }
         : { toolCount: 0, tokens: 0, durationMs },
     };
   } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    const durationMs = Date.now() - startTime;
     return {
       agent: agentName,
       task: options.task,
@@ -85,9 +109,31 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
       } as SubagentUsage,
       model: undefined,
       finalOutput: undefined,
-      error: err instanceof Error ? err.message : String(err),
-      progress: undefined,
-      progressSummary: { toolCount: 0, tokens: 0, durationMs: Date.now() - startTime },
+      error: errorMessage,
+      // Always return a valid progress object so the parallel renderer's
+      // `details.progress[i]` stays aligned with `details.results[i]`.
+      // Returning undefined here would be filtered out and cause index
+      // misalignment between results and progress in the parallel view.
+      progress: {
+        agent: agentName,
+        status: "failed",
+        task: options.task,
+        currentTool: undefined,
+        currentToolArgs: undefined,
+        currentToolStartedAt: undefined,
+        toolCount: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        tokens: 0,
+        cost: 0,
+        durationMs,
+        error: errorMessage,
+        output: undefined,
+        recentOutput: undefined,
+        toolCalls: undefined,
+        model: undefined,
+      },
+      progressSummary: { toolCount: 0, tokens: 0, durationMs },
     };
   }
 }
@@ -96,7 +142,7 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
  * Execute multiple subagents in parallel.
  */
 export async function executeParallel(options: {
-  tasks: Array<{ agent: string | undefined; agentConfig: AgentConfig | undefined; task: string; model: string | undefined; cwd: string | undefined }>;
+  tasks: Array<{ agent: string | undefined; agentConfig: AgentConfig | undefined; task: string; model: string | undefined; activeModel: string | undefined; cwd: string | undefined }>;
   signal: AbortSignal | undefined;
   onUpdate: ((progress: SubagentProgress[]) => void) | undefined;
 }): Promise<SubagentResult[]> {

package/src/index.ts

@@ -97,9 +97,8 @@ export function registerSubagent(pi: ExtensionAPI): void {
             agent: t.agent ?? undefined,
             agentConfig: t.agent ? findAgent(agents, t.agent) : undefined,
             task: t.task,
-            // Fall back to the parent's currently-selected model when the caller
-            // (and the agent frontmatter) didn't specify one.
-            model: t.model ?? ctx.model?.id,
+            model: t.model,
+            activeModel: ctx.model?.id,
             cwd: t.cwd ?? undefined,
           })),
           signal: signal ?? undefined,
@@ -120,7 +119,11 @@ export function registerSubagent(pi: ExtensionAPI): void {
           details: {
             mode: "parallel",
             results,
-            progress: results.map(r => r.progress).filter(Boolean) as SubagentProgress[] | undefined,
+            // progress is always defined for each result (executeSubagent synthesizes
+            // a failed-progress object in its catch block) so we keep alignment with
+            // results by index. Do NOT filter(Boolean) here — that would misalign
+            // details.progress[i] with details.results[i] in the renderer.
+            progress: results.map(r => r.progress) as SubagentProgress[],
           },
         };
       }
@@ -144,9 +147,8 @@ export function registerSubagent(pi: ExtensionAPI): void {
           agent: params.agent ?? undefined,
           agentConfig,
           task: params.task,
-          // Fall back to the parent's currently-selected model when the caller
-          // (and the agent frontmatter) didn't specify one.
-          model: params.model ?? ctx.model?.id,
+          model: params.model,
+          activeModel: ctx.model?.id,
           cwd: params.cwd ?? undefined,
           signal: signal ?? undefined,
           onUpdate: (progress: SubagentProgress) => {

package/src/spawn.ts

@@ -19,6 +19,7 @@ process.on("exit", () => {
 export interface SpawnOptions {
   task: string;
   model: string | undefined;
+  activeModel: string | undefined;
   cwd: string | undefined;
   signal: AbortSignal | undefined;
   agent: AgentConfig | undefined;
@@ -86,24 +87,25 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
     "--no-session",
   ];
 
-  // Use agent config from frontmatter if available
+  // Resolve model with correct priority:
+  // 1. frontmatter model (agent.model)
+  // 2. explicit tool-call model (options.model)
+  // 3. currently active model (options.activeModel)
+  // 4. no --model flag → pi default
+  const modelToUse = options.agent?.model ?? options.model ?? options.activeModel;
+  if (modelToUse) {
+    args.push("--model", modelToUse);
+  }
+
+  // Apply other agent config options
   if (options.agent) {
     const agent = options.agent;
-    // Agent's model takes precedence; tool-call model as fallback
-    const modelToUse = agent.model ?? options.model;
-    if (modelToUse) {
-      args.push("--model", modelToUse);
-    }
     if (agent.thinking) {
       args.push("--thinking", agent.thinking);
     }
     if (agent.tools && agent.tools.length > 0) {
       args.push("--tools", agent.tools.join(","));
     }
-  } else if (options.model) {
-    // Fallback: tool-call model (which itself falls back to the parent's
-    // currently-selected model via ctx.model?.id at the call site).
-    args.push("--model", options.model);
   }
 
   // Temp files for system prompt

package/src/stream.ts

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline";
 import type { ChildProcess } from "node:child_process";
 import type { StreamState, SubagentProgress, SubagentResult } from "./types.js";
+import { getBus, Events } from "@pi-archimedes/core/bus";
 import {
   type JsonEvent,
   handleToolStart,
@@ -124,6 +125,17 @@ export function streamEvents(
         case "tool_execution_start": {
           handleToolStart(state, event);
           emitProgress();
+          // Forward manage_todo_list writes to the bus for parent widget
+          if (event.toolName === "manage_todo_list") {
+            const args = event.args as Record<string, unknown> | undefined;
+            const todoList = args?.todoList as Array<unknown> | undefined;
+            if (Array.isArray(todoList)) {
+              getBus().emit(Events.TODOS_UPDATE, {
+                source: `subagent:${callbacks.agent ?? "general"}`,
+                todos: todoList,
+              });
+            }
+          }
           break;
         }
         case "tool_execution_end": {
@@ -193,6 +205,11 @@ export function streamEvents(
       // Final progress update
       callbacks.onProgress?.(result.progress!);
 
+      // Clear subagent todos from the bus on process exit
+      getBus().emit(Events.TODOS_CLEAR, {
+        source: `subagent:${callbacks.agent ?? "general"}`,
+      });
+
       resolve(result);
     });