@pi-archimedes/subagent 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "0.4.0"
+    "@pi-archimedes/core": "0.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",

package/src/agents.ts

@@ -0,0 +1,113 @@
+/**
+ * Agent discovery and configuration loading.
+ * Reads agent definitions from ~/.pi/agent/agents/*.md and .pi/agents/*.md
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  model?: string;
+  thinking?: string;
+  tools?: string[];
+  systemPrompt: string;
+  source: "user" | "project";
+  filePath: string;
+}
+
+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, unknown>>(content);
+
+    if (!frontmatter.name || !frontmatter.description) continue;
+
+    const tools = typeof frontmatter.tools === "string"
+      ? frontmatter.tools.split(",").map((t: string) => t.trim()).filter(Boolean)
+      : undefined;
+
+    const config: AgentConfig = {
+      name: frontmatter.name as string,
+      description: frontmatter.description as string,
+      systemPrompt: body,
+      source,
+      filePath,
+    };
+    if (frontmatter.model) config.model = frontmatter.model as string;
+    if (frontmatter.thinking) config.thinking = frontmatter.thinking as string;
+    if (tools && tools.length > 0) config.tools = tools;
+
+    agents.push(config);
+  }
+
+  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;
+  }
+}
+
+/**
+ * Discover all available agents from user and/or project directories.
+ */
+export function discoverAgents(cwd: string): AgentConfig[] {
+  const userDir = path.join(getAgentDir(), "agents");
+  const projectDir = findNearestProjectAgentsDir(cwd);
+
+  const userAgents = loadAgentsFromDir(userDir, "user");
+  const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
+
+  // Project agents override user agents with the same name
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
+
+  return Array.from(agentMap.values());
+}
+
+/**
+ * Look up an agent config by name.
+ */
+export function findAgent(agents: AgentConfig[], name: string): AgentConfig | undefined {
+  return agents.find((a) => a.name === name);
+}

package/src/compact.ts

@@ -1,6 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolResult } from "./types.js";
-import { SPINNER_FRAMES, formatTokens, formatDuration, formatCost, truncLine, buildStatsLine } from "./format.js";
+import { formatTokens, formatDuration, formatCost, truncLine, buildStatsLine } from "./format.js";
 
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
 type RenderContext = { state: Record<string, unknown>; invalidate: () => void };
@@ -49,46 +49,13 @@ export function buildActivityLine(
   return "";
 }
 
-// ── Spinner helper ──────────────────────────────────────────────────────────
+// ── Status glyph ────────────────────────────────────────────────────────────
 
-const SPINNER_INTERVAL_MS = 80;
-
-function getSpinnerGlyph(agentName: string, isRunning: boolean, status: string, context: RenderContext): string {
-  if (isRunning) {
-    const timerKey = "_subagentTimer_" + agentName;
-    const frameKey = "_subagentFrame_" + agentName;
-    if (!context.state[timerKey]) {
-      context.state[frameKey] = 0;
-      const timer = setInterval(() => {
-        context.state[frameKey] = ((context.state[frameKey] as number) + 1) % SPINNER_FRAMES.length;
-        context.invalidate();
-      }, SPINNER_INTERVAL_MS);
-      context.state[timerKey] = timer;
-    }
-    return SPINNER_FRAMES[context.state[frameKey] as number]!;
-  }
+function statusGlyph(isRunning: boolean, status: string): string {
+  if (isRunning) return "↳";
   return status === "completed" ? "✓" : "✗";
 }
 
-function cleanupTimer(agentName: string, context: RenderContext): void {
-  const timerKey = "_subagentTimer_" + agentName;
-  const frameKey = "_subagentFrame_" + agentName;
-  const timer = context.state[timerKey] as ReturnType<typeof setInterval> | undefined;
-  if (timer) {
-    clearInterval(timer);
-    delete context.state[timerKey];
-  }
-  delete context.state[frameKey];
-}
-
-/** Cleanup ALL timers for a given agent — idempotent. */
-function cleanupAllTimers(agentName: string, context: RenderContext): void {
-  cleanupTimer(agentName, context);
-  // Also clean up start time tracker
-  const timeKey = "_subagentStartTime_" + agentName;
-  delete context.state[timeKey];
-}
-
 // ── Compact single agent ────────────────────────────────────────────────────
 
 export function renderCompactSingle(
@@ -103,13 +70,6 @@ export function renderCompactSingle(
   const isRunning = progress?.status === "running";
   const status = isRunning ? "running" : (result.exitCode === 0 ? "completed" : "failed");
 
-  // Manage timer for spinner
-  if (isRunning) {
-    getSpinnerGlyph(agentName, true, "running", context);
-  } else {
-    cleanupAllTimers(agentName, context);
-  }
-
   // Track start time for live duration
   const timeKey = "_subagentStartTime_" + agentName;
   if (isRunning && context.state[timeKey] === undefined) {
@@ -132,11 +92,10 @@ export function renderCompactSingle(
 
   const statsPart = statsLine ?? "";
 
-  // Activity: spinner + current tool if running, status if finished
+  // Activity: arrow + current tool if running, status if finished
   let activityLine: string;
   if (isRunning) {
-    const spinner = SPINNER_FRAMES[(context.state["_subagentFrame_" + agentName] as number) ?? 0];
-    const spinnerColored = theme.fg("muted", spinner ?? "");
+    const arrow = theme.fg("muted", "↳ ");
     if (progress?.currentTool) {
       const argsPreview = progress.currentToolArgs
         ? truncLine(progress.currentToolArgs ?? "", 60)
@@ -151,7 +110,7 @@ export function renderCompactSingle(
       if (durationPart) {
         line += theme.fg("dim", durationPart);
       }
-      activityLine = spinnerColored + " " + line;
+      activityLine = arrow + line;
     } else if (progress?.toolCalls && progress.toolCalls.length > 0) {
       const lastCall = progress.toolCalls[progress.toolCalls.length - 1];
       activityLine = theme.fg("dim", "  ⎿  ") + theme.fg("muted", lastCall ?? "");
@@ -193,14 +152,7 @@ export function renderCompactParallel(
     const isRunning = progress?.status === "running";
     const status = progress?.status ?? (result.exitCode === 0 ? "completed" : "failed");
 
-    // Use animated spinner for running agents
-    let glyph: string;
-    if (isRunning) {
-      glyph = getSpinnerGlyph(agentName, true, "running", context);
-    } else {
-      cleanupTimer(agentName, context);
-      glyph = status === "completed" ? "✓" : "✗";
-    }
+    const glyph = statusGlyph(isRunning, status);
     const glyphColored = status === "completed"
       ? theme.fg("success", glyph)
       : status === "failed"
@@ -250,7 +202,7 @@ export function renderCompactProgress(
   const status = progress.status;
   const isRunning = status === "running";
 
-  let glyph = getSpinnerGlyph(agentName, isRunning, status, context);
+  const glyph = statusGlyph(isRunning, status);
   const glyphColored = status === "completed"
     ? theme.fg("success", glyph)
     : status === "failed"
@@ -262,9 +214,6 @@ export function renderCompactProgress(
   if (isRunning && context.state[timeKey] === undefined) {
     context.state[timeKey] = Date.now() - (progress.durationMs ?? 0);
   }
-  if (!isRunning) {
-    cleanupAllTimers(agentName, context);
-  }
   const liveDuration = isRunning && context.state[timeKey] !== undefined
     ? Date.now() - (context.state[timeKey] as number)
     : progress.durationMs;
@@ -278,11 +227,10 @@ export function renderCompactProgress(
   };
   const statsLine = buildStatsLine(statsData, theme);
 
-  // Activity: current tool if running, status if finished
+  // Activity: arrow + current tool if running, status if finished
   let activityLine: string;
   if (isRunning) {
-    const spinner = SPINNER_FRAMES[(context.state["_subagentFrame_" + agentName] as number) ?? 0];
-    const spinnerColored = theme.fg("muted", spinner ?? "");
+    const arrow = theme.fg("muted", "↳ ");
     if (progress.currentTool) {
       const argsPreview = progress.currentToolArgs
         ? truncLine(progress.currentToolArgs ?? "", 60)
@@ -297,12 +245,12 @@ export function renderCompactProgress(
       if (durationPart) {
         line += theme.fg("dim", durationPart);
       }
-      activityLine = spinnerColored + " " + line;
+      activityLine = arrow + line;
     } else if (progress.toolCalls && progress.toolCalls.length > 0) {
       const lastCall = progress.toolCalls[progress.toolCalls.length - 1];
-      activityLine = spinnerColored + " " + theme.fg("muted", lastCall ?? "");
+      activityLine = arrow + theme.fg("muted", lastCall ?? "");
     } else {
-      activityLine = spinnerColored + " " + theme.fg("muted", "Working...");
+      activityLine = arrow + theme.fg("muted", "Working...");
     }
   } else if (progress.error) {
     activityLine = theme.fg("error", "✗ " + truncLine(progress.error, 80));
@@ -337,7 +285,7 @@ export function renderCompactParallelProgress(
     const status = progress.status;
     const isRunning = status === "running";
 
-    let glyph = getSpinnerGlyph(agentName, isRunning, status, context);
+    const glyph = statusGlyph(isRunning, status);
     const glyphColored = status === "completed"
       ? theme.fg("success", glyph)
       : status === "failed"

package/src/execute.ts

@@ -1,10 +1,12 @@
 import { spawnSubagent } from "./spawn.js";
 import { streamEvents } from "./stream.js";
 import { emitCostUpdate } from "./cost.js";
+import type { AgentConfig } from "./agents.js";
 import type { SubagentProgress, SubagentResult, SubagentUsage } from "./types.js";
 
 export interface ExecuteOptions {
   agent: string | undefined;
+  agentConfig: AgentConfig | undefined;
   task: string;
   model: string | undefined;
   cwd: string | undefined;
@@ -24,6 +26,7 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
     model: options.model,
     cwd: options.cwd,
     signal: options.signal,
+    agent: options.agentConfig,
   });
 
   // Track previously emitted values to only emit deltas
@@ -93,7 +96,7 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
  * Execute multiple subagents in parallel.
  */
 export async function executeParallel(options: {
-  tasks: Array<{ agent: string | undefined; task: string; model: string | undefined; cwd: string | undefined }>;
+  tasks: Array<{ agent: string | undefined; agentConfig: AgentConfig | undefined; task: string; model: string | undefined; cwd: string | undefined }>;
   signal: AbortSignal | undefined;
   onUpdate: ((progress: SubagentProgress[]) => void) | undefined;
 }): Promise<SubagentResult[]> {

package/src/expanded.ts

@@ -40,7 +40,7 @@ export function buildExpandedText(
   if (toolCalls && toolCalls.length > 0) {
     lines.push("");
     for (const call of toolCalls) {
-      lines.push(theme.fg("dim", "- " + call));
+      lines.push(theme.fg("dim", "↳ " + call));
     }
   }
 
@@ -110,7 +110,7 @@ export function renderProgressExpanded(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "- " + call));
+      lines.push(theme.fg("dim", "↳ " + call));
     }
   }
 
@@ -183,7 +183,7 @@ export function buildProgressExpandedText(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "- " + call));
+      lines.push(theme.fg("dim", "↳ " + call));
     }
   }
 

package/src/format.ts

@@ -1,7 +1,5 @@
 import { clampLine } from "@pi-archimedes/core/text";
 
-export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
 export function formatTokens(n: number): string {
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
   if (n >= 1_000) return Math.round(n / 1_000) + "k";

package/src/index.ts

@@ -3,6 +3,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { executeSubagent, executeParallel } from "./execute.js";
 import { renderSubagentResult } from "./render.js";
+import { discoverAgents, findAgent } from "./agents.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -24,13 +25,13 @@ const SUBAGENT_PARAMS_SCHEMA = Type.Object({
     description: "Agent name/identifier (optional, defaults to 'general')",
   })),
   task: Type.Optional(Type.String({
-    description: "Task description for the subagent",
+    description: "Task description for the subagent. Required when not using 'tasks' array.",
   })),
   tasks: Type.Optional(Type.Array(TaskItem, {
-    description: "Multiple tasks for parallel execution",
+    description: "Multiple tasks for parallel execution. Required when not using 'task'.",
   })),
   model: Type.Optional(Type.String({
-    description: "Model override (e.g. 'anthropic/claude-sonnet-4')",
+    description: "Model override for the subagent",
   })),
   async: Type.Optional(Type.Boolean({
     description: "Run asynchronously (fire-and-forget)",
@@ -54,7 +55,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
     name: "subagent",
     label: "Subagent",
     description:
-      "Delegate tasks to subagents. Single: { agent, task }. Parallel: { tasks: [{ agent, task }] }. Options: model, cwd.",
+      "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Never omit both. Options: agent, model, cwd.",
     parameters: SUBAGENT_PARAMS_SCHEMA,
 
     async execute(
@@ -69,13 +70,31 @@ export function registerSubagent(pi: ExtensionAPI): void {
       },
       signal: AbortSignal | undefined,
       onUpdate: ((update: SubagentToolResult) => void) | undefined,
-      _ctx: ExtensionContext,
+      ctx: ExtensionContext,
     ): Promise<SubagentToolResult> {
+      // Discover available agents
+      const agents = discoverAgents(ctx.cwd);
+
       // Parallel mode
       if (params.tasks && params.tasks.length > 0) {
+        const missingAgents = params.tasks.filter((t) => t.agent && !findAgent(agents, t.agent));
+        if (missingAgents.length > 0) {
+          const available = agents.map((a) => a.name).join(", ") || "none";
+          const unknown = missingAgents.map((t) => `"${t.agent}"`).join(", ");
+          return {
+            content: [{ type: "text", text: `Unknown agent(s): ${unknown}. Available: ${available}` }],
+            details: {
+              mode: "parallel",
+              results: [],
+              progress: undefined,
+            },
+            isError: true,
+          };
+        }
         const results: SubagentResult[] = await executeParallel({
           tasks: params.tasks.map((t) => ({
             agent: t.agent ?? undefined,
+            agentConfig: t.agent ? findAgent(agents, t.agent) : undefined,
             task: t.task,
             model: t.model ?? undefined,
             cwd: t.cwd ?? undefined,
@@ -105,8 +124,22 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
       // Single mode
       if (params.task) {
+        let agentConfig = params.agent ? findAgent(agents, params.agent) : undefined;
+        if (params.agent && !agentConfig) {
+          const available = agents.map((a) => a.name).join(", ") || "none";
+          return {
+            content: [{ type: "text", text: `Unknown agent: "${params.agent}". Available: ${available}` }],
+            details: {
+              mode: "single",
+              results: [],
+              progress: undefined,
+            },
+            isError: true,
+          };
+        }
         const result: SubagentResult = await executeSubagent({
           agent: params.agent ?? undefined,
+          agentConfig,
           task: params.task,
           model: params.model ?? undefined,
           cwd: params.cwd ?? undefined,

package/src/spawn.ts

@@ -1,12 +1,16 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, writeFileSync, unlinkSync, mkdtempSync, rmdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentConfig } from "./agents.js";
 
 export interface SpawnOptions {
   task: string;
   model: string | undefined;
   cwd: string | undefined;
   signal: AbortSignal | undefined;
+  agent: AgentConfig | undefined;
 }
 
 /**
@@ -32,6 +36,29 @@ export function resolvePiCommand(): { command: string; args: string[] } {
   return { command: piPath, args: [] };
 }
 
+/**
+ * Write system prompt to a temp file for --append-system-prompt.
+ */
+function writePromptToFile(agentName: string, prompt: string): { dir: string; filePath: string } {
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const tmpDir = mkdtempSync(join(tmpdir(), "pi-subagent-"));
+  const filePath = join(tmpDir, `prompt-${safeName}.md`);
+  writeFileSync(filePath, prompt, { encoding: "utf-8" });
+  return { dir: tmpDir, filePath };
+}
+
+/**
+ * Clean up temp prompt file and directory.
+ */
+function cleanupTempFiles(dir: string | null, filePath: string | null): void {
+  if (filePath) {
+    try { unlinkSync(filePath); } catch { /* ignore */ }
+  }
+  if (dir) {
+    try { rmdirSync(dir); } catch { /* ignore */ }
+  }
+}
+
 /**
  * Spawn a child `pi` process in JSON mode.
  */
@@ -40,13 +67,42 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
   const args: string[] = [
     ...baseArgs,
     "--mode", "json",
-    "-p", options.task,
+    "-p",
+    "--no-session",
   ];
 
-  if (options.model) {
+  // Use agent config from frontmatter if available
+  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: use model from tool call params (legacy)
     args.push("--model", options.model);
   }
 
+  // Temp files for system prompt
+  let tmpDir: string | null = null;
+  let tmpPath: string | null = null;
+
+  if (options.agent && options.agent.systemPrompt.trim()) {
+    const tmp = writePromptToFile(options.agent.name, options.agent.systemPrompt);
+    tmpDir = tmp.dir;
+    tmpPath = tmp.filePath;
+    args.push("--append-system-prompt", tmpPath);
+  }
+
+  args.push(options.task);
+
   const child = spawn(command, args, {
     cwd: options.cwd || process.cwd(),
     stdio: ["ignore", "pipe", "pipe"],
@@ -54,8 +110,9 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
   });
 
   // Handle abort signal
+  let abortHandler: (() => void) | undefined;
   if (options.signal) {
-    const cleanup = () => {
+    abortHandler = () => {
       if (child.pid && !child.killed) {
         child.kill("SIGTERM");
         const forceKill = setTimeout(() => {
@@ -66,13 +123,17 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
         forceKill.unref();
       }
     };
-    options.signal.addEventListener("abort", cleanup, { once: true });
+    options.signal.addEventListener("abort", abortHandler, { once: true });
   }
 
-  // Clean up on normal exit to prevent forceKill firing after process ends
+  // Clean up temp files and listeners on exit
   const exitCleanup = (): void => {
     child.removeListener("exit", exitCleanup);
     child.removeListener("error", exitCleanup);
+    if (abortHandler && options.signal) {
+      options.signal.removeEventListener("abort", abortHandler);
+    }
+    cleanupTempFiles(tmpDir, tmpPath);
   };
   child.on("exit", exitCleanup);
   child.on("error", exitCleanup);

package/src/stream.ts

@@ -74,6 +74,9 @@ export function streamEvents(
       callbacks.onProgress?.(buildProgress());
     };
 
+    // Periodic progress updates for live duration display
+    const heartbeat = setInterval(emitProgress, 1000);
+
     // Collect stderr
     const stderrParts: string[] = [];
     child.stderr?.on("data", (data: Buffer) => {
@@ -129,6 +132,7 @@ export function streamEvents(
     // Handle process exit
     child.on("close", (code) => {
       clearTimeout(timeout);
+      clearInterval(heartbeat);
       const durationMs = Date.now() - startTime;
       const exitCode = code ?? 1;
 
@@ -171,6 +175,7 @@ export function streamEvents(
 
     child.on("error", (err) => {
       clearTimeout(timeout);
+      clearInterval(heartbeat);
       reject(err);
     });
   });