@pi-archimedes/subagent 0.3.1

package/src/render.ts

@@ -0,0 +1,123 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { SubagentDetails, SubagentProgress, SubagentToolResult } from "./types.js";
+import {
+  renderCompactSingle,
+  renderCompactParallel,
+  renderCompactProgress,
+  renderCompactParallelProgress,
+} from "./compact.js";
+import {
+  renderExpanded,
+  renderProgressExpanded,
+  buildProgressExpandedText,
+  buildExpandedText,
+} from "./expanded.js";
+
+type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
+type RenderContext = {
+  expanded: boolean;
+  isError: boolean;
+  lastComponent: Text | undefined;
+  state: Record<string, unknown>;
+  invalidate: () => void;
+};
+
+export function renderSubagentResult(
+  text: Text,
+  result: SubagentToolResult,
+  options: { expanded: boolean },
+  theme: Theme,
+  context: RenderContext,
+): Text {
+  const details: SubagentDetails | undefined = result.details;
+  const expanded = context.expanded ?? options.expanded;
+
+  if (!details) {
+    text.setText(theme.fg("dim", "  no results"));
+    return text;
+  }
+
+  // ── Streaming progress (results empty but progress has data) ──────────
+  if (details.results.length === 0 && details.progress && details.progress.length > 0) {
+    if (details.progress.length === 1) {
+      return renderProgressUpdate(text, details.progress[0], expanded, theme, context);
+    }
+    return renderProgressUpdatesParallel(text, details, expanded, theme, context);
+  }
+
+  if (details.results.length === 0) {
+    text.setText(theme.fg("dim", "  no results"));
+    return text;
+  }
+
+  // ── Single agent ────────────────────────────────────────────────────────
+  if (details.mode === "single" || details.results.length === 1) {
+    return renderSingleAgent(text, details.results[0], details.progress?.[0], expanded, theme, context);
+  }
+
+  // ── Parallel agents ─────────────────────────────────────────────────────
+  return renderParallelAgents(text, details, expanded, theme, context);
+}
+
+function renderSingleAgent(
+  text: Text,
+  result: SubagentDetails["results"][number],
+  progress: SubagentDetails["progress"] extends (infer U)[] | undefined ? U | undefined : undefined,
+  expanded: boolean,
+  theme: Theme,
+  context: RenderContext,
+): Text {
+  if (expanded) {
+    return renderExpanded(text, result, progress, theme);
+  }
+  return renderCompactSingle(text, result, progress, theme, context);
+}
+
+function renderParallelAgents(
+  text: Text,
+  details: SubagentDetails,
+  expanded: boolean,
+  theme: Theme,
+  context: RenderContext,
+): Text {
+  if (expanded) {
+    const progressArr: SubagentProgress[] = details.progress ?? [];
+    const lines = details.results.map((result, i) => {
+      return buildExpandedText(result, progressArr[i], theme);
+    });
+    text.setText(lines.join("\n\n"));
+    return text;
+  }
+  return renderCompactParallel(text, details, theme, context);
+}
+
+function renderProgressUpdate(
+  text: Text,
+  progress: SubagentProgress,
+  expanded: boolean,
+  theme: Theme,
+  context: RenderContext,
+): Text {
+  if (expanded) {
+    return renderProgressExpanded(text, progress, theme);
+  }
+  return renderCompactProgress(text, progress, theme, context);
+}
+
+function renderProgressUpdatesParallel(
+  text: Text,
+  details: SubagentDetails,
+  expanded: boolean,
+  theme: Theme,
+  context: RenderContext,
+): Text {
+  if (expanded) {
+    const progressArr: SubagentProgress[] = details.progress ?? [];
+    const lines = progressArr.map((progress) => {
+      return buildProgressExpandedText(progress, theme);
+    });
+    text.setText(lines.join("\n\n"));
+    return text;
+  }
+  return renderCompactParallelProgress(text, details, theme, context);
+}

package/src/spawn.ts

@@ -0,0 +1,73 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+export interface SpawnOptions {
+  task: string;
+  model?: string;
+  cwd?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Resolve the `pi` command — finds it on PATH.
+ */
+export function resolvePiCommand(): { command: string; args: string[] } {
+  let piPath: string;
+  try {
+    piPath = execSync(process.platform === "win32" ? 'where pi' : 'which pi', {
+      encoding: "utf-8",
+    }).trim();
+  } catch {
+    throw new Error("pi command not found on PATH. Is pi installed?");
+  }
+
+  // On Windows, the CLI might be a .cmd script
+  if (process.platform === "win32" && !piPath.endsWith(".cmd") && !piPath.endsWith(".exe")) {
+    const cmdPath = piPath + ".cmd";
+    if (existsSync(cmdPath)) {
+      return { command: "cmd", args: ["/c", cmdPath] };
+    }
+  }
+  return { command: piPath, args: [] };
+}
+
+/**
+ * Spawn a child `pi` process in JSON mode.
+ */
+export function spawnSubagent(options: SpawnOptions): ChildProcess {
+  const { command, args: baseArgs } = resolvePiCommand();
+  const args: string[] = [
+    ...baseArgs,
+    "--mode", "json",
+    "-p", options.task,
+  ];
+
+  if (options.model) {
+    args.push("--model", options.model);
+  }
+
+  const child = spawn(command, args, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+  });
+
+  // Handle abort signal
+  if (options.signal) {
+    const cleanup = () => {
+      if (child.pid && !child.killed) {
+        child.kill("SIGTERM");
+        const forceKill = setTimeout(() => {
+          if (!child.killed) {
+            child.kill("SIGKILL");
+          }
+        }, 3000);
+        forceKill.unref();
+      }
+    };
+    options.signal.addEventListener("abort", cleanup, { once: true });
+  }
+
+  return child;
+}

package/src/stream.ts

@@ -0,0 +1,177 @@
+import { createInterface } from "node:readline";
+import type { ChildProcess } from "node:child_process";
+import type { StreamState, SubagentProgress, SubagentResult } from "./types.js";
+import {
+  type JsonEvent,
+  handleToolStart,
+  handleToolEnd,
+  handleToolResult,
+  handleMessageEnd,
+  handleAgentEnd,
+} from "./handlers.js";
+
+export interface StreamCallbacks {
+  agent?: string;
+  task?: string;
+  onProgress?: (progress: SubagentProgress) => void;
+}
+
+/**
+ * Stream JSON events from a child pi process and build progress/result.
+ */
+export function streamEvents(
+  child: ChildProcess,
+  callbacks: StreamCallbacks = {},
+): Promise<SubagentResult> {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("subagent timed out after 5 minutes"));
+    }, 5 * 60 * 1000);
+
+    const state: StreamState = {
+      toolCount: 0,
+      turnCount: 0,
+      totalInput: 0,
+      totalOutput: 0,
+      totalCacheRead: 0,
+      totalCacheWrite: 0,
+      totalCost: 0,
+      currentTool: undefined,
+      currentToolArgs: undefined,
+      currentToolStartedAt: undefined,
+      model: undefined,
+      accumulatedOutput: [],
+      recentOutput: [],
+      toolCalls: [],
+      finalOutput: undefined,
+    };
+    let error: string | undefined;
+
+    // Build progress from state
+    const buildProgress = (): SubagentProgress => ({
+      agent: callbacks.agent ?? "subagent",
+      status: "running",
+      task: callbacks.task ?? "",
+      currentTool: state.currentTool,
+      currentToolArgs: state.currentToolArgs,
+      currentToolStartedAt: state.currentToolStartedAt,
+      toolCount: state.toolCount,
+      inputTokens: state.totalInput,
+      outputTokens: state.totalOutput,
+      tokens: state.totalInput + state.totalOutput,
+      cost: state.totalCost,
+      durationMs: Date.now() - startTime,
+      error,
+      output: state.accumulatedOutput.length > 0 ? state.accumulatedOutput.join("\n\n") : undefined,
+      recentOutput: state.recentOutput.length > 0 ? state.recentOutput : undefined,
+      toolCalls: state.toolCalls.length > 0 ? state.toolCalls : undefined,
+      model: state.model,
+    });
+
+    const emitProgress = () => {
+      callbacks.onProgress?.(buildProgress());
+    };
+
+    // Collect stderr
+    const stderrParts: string[] = [];
+    child.stderr?.on("data", (data: Buffer) => {
+      stderrParts.push(data.toString());
+    });
+
+    // Parse JSON lines from stdout
+    const rl = createInterface({
+      input: child.stdout!,
+      crlfDelay: Infinity,
+    });
+
+    rl.on("line", (line: string) => {
+      let event: JsonEvent;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        return; // Skip non-JSON lines
+      }
+
+      switch (event.type) {
+        case "tool_execution_start": {
+          handleToolStart(state, event);
+          emitProgress();
+          break;
+        }
+        case "tool_execution_end": {
+          handleToolEnd(state);
+          emitProgress();
+          break;
+        }
+        case "turn_start": {
+          state.turnCount++;
+          break;
+        }
+        case "tool_result_end": {
+          handleToolResult(state, event);
+          emitProgress();
+          break;
+        }
+        case "message_end": {
+          handleMessageEnd(state, event);
+          emitProgress();
+          break;
+        }
+        case "agent_end": {
+          handleAgentEnd(state, event);
+          break;
+        }
+      }
+    });
+
+    // Handle process exit
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      const durationMs = Date.now() - startTime;
+      const exitCode = code ?? 1;
+
+      if (stderrParts.length > 0 && exitCode !== 0) {
+        error = stderrParts.join("").trim();
+      }
+
+      const result: SubagentResult = {
+        agent: callbacks.agent ?? "subagent",
+        task: callbacks.task ?? "",
+        exitCode,
+        model: state.model,
+        usage: {
+          input: state.totalInput,
+          output: state.totalOutput,
+          cacheRead: state.totalCacheRead,
+          cacheWrite: state.totalCacheWrite,
+          cost: state.totalCost,
+          turns: state.turnCount,
+        },
+        finalOutput: state.finalOutput,
+        error,
+        progress: {
+          ...buildProgress(),
+          status: exitCode === 0 ? "completed" : "failed",
+          durationMs,
+        },
+        progressSummary: {
+          toolCount: state.toolCount,
+          tokens: state.totalInput + state.totalOutput,
+          durationMs,
+        },
+      };
+
+      // Final progress update
+      callbacks.onProgress?.(result.progress!);
+
+      resolve(result);
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+export interface SubagentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  turns: number;
+}
+
+export interface SubagentProgress {
+  agent: string;
+  status: "running" | "completed" | "failed";
+  task: string;
+  currentTool?: string;
+  currentToolArgs?: string;
+  currentToolStartedAt?: number;
+  toolCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  tokens: number;
+  cost: number;
+  durationMs: number;
+  error?: string;
+  /** Model used by the subagent */
+  model?: string;
+  /** Accumulated assistant text output during streaming */
+  output?: string;
+  /** Last N lines of assistant text for live display */
+  recentOutput?: string[];
+  /** History of tool calls: "toolName: args_preview" */
+  toolCalls?: string[];
+}
+
+export interface SubagentResult {
+  agent: string;
+  task: string;
+  exitCode: number;
+  usage: SubagentUsage;
+  model?: string;
+  finalOutput?: string;
+  error?: string;
+  progress?: SubagentProgress;
+  progressSummary?: { toolCount: number; tokens: number; durationMs: number };
+}
+
+export interface SubagentToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: SubagentDetails;
+  isError?: boolean;
+}
+
+export interface SubagentDetails {
+  mode: "single" | "parallel";
+  results: SubagentResult[];
+  progress?: SubagentProgress[];
+}
+
+/** Mutable state during streaming — shared between stream.ts and handlers.ts */
+export interface StreamState {
+  toolCount: number;
+  turnCount: number;
+  totalInput: number;
+  totalOutput: number;
+  totalCacheRead: number;
+  totalCacheWrite: number;
+  totalCost: number;
+  currentTool: string | undefined;
+  currentToolArgs: string | undefined;
+  currentToolStartedAt: number | undefined;
+  model: string | undefined;
+  accumulatedOutput: string[];
+  recentOutput: string[];
+  toolCalls: string[];
+  finalOutput: string | undefined;
+}
+