@leo-alvarenga/pi-mini-subagents 0.2.1 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leo-alvarenga/pi-mini-subagents",
-  "version": "0.2.1",
+  "version": "0.2.5",
   "description": "Transient subagents for Pi: mini_subagent tool (single + parallel), /subagents command, and a live TUI panel",
   "license": "MIT",
   "repository": "github.com/leo-alvarenga/pi-mono",
@@ -15,10 +15,10 @@
   ],
   "files": [
     "src",
+    "!src/test",
     "skills",
     "README.md",
-    "LICENSE",
-    "!src/*.test.ts"
+    "LICENSE"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -26,6 +26,9 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "@leo-alvarenga/pi-ext-core": "^0.3.4"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"
@@ -36,11 +39,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/constants.ts

@@ -1,13 +1,5 @@
 import type { KeyId } from "@earendil-works/pi-tui";
-import type { ThemeColor } from "@earendil-works/pi-coding-agent";
-
-import type { SubagentStatus } from "./types";
-
-export type SubagentStatusUi = {
-  icon: string;
-  fg: ThemeColor;
-  bold?: boolean;
-};
+import type { StatusUi, SubagentStatus } from "@leo-alvarenga/pi-ext-core";
 
 export const STATUSES = [
   "running",
@@ -16,7 +8,7 @@ export const STATUSES = [
   "needs_input",
 ] as const;
 
-export const STATUS_STYLES: Record<SubagentStatus, SubagentStatusUi> = {
+export const STATUS_STYLES: Record<SubagentStatus, StatusUi> = {
   running: { icon: "󱥸 ", fg: "accent", bold: true },
   completed: { icon: "✓ ", fg: "success" },
   failed: { icon: "✗ ", fg: "error", bold: true },
@@ -41,6 +33,14 @@ export const WRITE_TOOLS = [
 /** Marker the subagent emits when it cannot proceed without outside input. */
 export const NEEDS_INPUT_MARKER = "NEEDS_INPUT:";
 
+/** Prompt suffix block that instructs the subagent to use the marker. */
+export const NEEDS_INPUT_SUFFIX = `If the task cannot be completed without information you cannot obtain yourself, end your final message with the exact block below and stop — do not guess:
+
+${NEEDS_INPUT_MARKER}
+- <question>
+
+Report your findings clearly and concisely.`;
+
 /** Max parallel tasks per call. */
 export const MAX_PARALLEL_TASKS = 8;
 /** Max concurrent subagent processes. */
@@ -64,8 +64,3 @@ export const REPORT_ENTRY = "subagents.report";
 
 /** Chord that toggles the panel. */
 export const PANEL_TOGGLE_CHORD: KeyId = "alt+s";
-
-export const PANEL_STATE_ICON = {
-  collapsed: "󰅂",
-  expanded: "󰅀",
-};

package/src/index.ts

@@ -1,31 +1,116 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  capitalize,
+  createSubagentRuntime,
+  formatTokens,
+  type SubagentRecord,
+} from "@leo-alvarenga/pi-ext-core";
 
-import { registerSubagentsCommand } from "./command";
-import { STATE_ENTRY, WIDGET_KEY } from "./constants";
-import { killAllRunning } from "./spawn";
-import { SubagentStore } from "./state";
-import { registerMiniSubagentTool } from "./tool";
-import { registerSubagentWidget, refreshWidget } from "./widget";
+import {
+  MAX_CONCURRENCY,
+  MAX_PANEL_ROWS,
+  MAX_PARALLEL_TASKS,
+  MAX_STORED_OUTPUT,
+  NEEDS_INPUT_MARKER,
+  NEEDS_INPUT_SUFFIX,
+  PANEL_TOGGLE_CHORD,
+  PER_TASK_OUTPUT_CAP,
+  READ_ONLY_TOOLS,
+  REPORT_ENTRY,
+  STATE_ENTRY,
+  STATUS_STYLES,
+  WIDGET_KEY,
+  WRITE_TOOLS,
+} from "./constants";
+
+function getStyledSubagent(r: SubagentRecord, th: Theme): string {
+  const task = r.task.replace(/\s*[\r\n]+\s*/g, " ");
+  const style = STATUS_STYLES[r.status] ?? STATUS_STYLES.completed;
+  let line = `${th.fg(style.fg, style.icon)} ${th.fg("accent", `#${r.id}`)} ${th.fg(style.fg, task)}`;
+  if (r.status === "completed" && r.tokens) {
+    line += th.fg("dim", ` · ${formatTokens(r.tokens)}`);
+  }
+  if (r.status === "failed") line += th.fg("dim", " · failed");
+  if (r.status === "needs_input") line += th.fg("dim", " · needs input");
+  if (r.allowWrite) line += th.fg("warning", " ✎");
+  return line;
+}
 
 export default function (pi: ExtensionAPI): void {
   // Child subagent processes inherit PI_SUBAGENT=1; they must not be able to
   // spawn sub-subagents, so the tool/widget/command never register there.
   if (process.env.PI_SUBAGENT) return;
 
-  const store = new SubagentStore(
-    (snapshot) => pi.appendEntry(STATE_ENTRY, snapshot),
-    (ctx) => refreshWidget(ctx, store),
-  );
-
-  registerMiniSubagentTool(pi, store);
-  registerSubagentsCommand(pi, store);
-  registerSubagentWidget(pi, store);
-
-  pi.on("session_start", (_event, ctx) => store.replay(ctx));
-  pi.on("session_tree", (_event, ctx) => store.replay(ctx));
-  pi.on("session_before_compact", (_event, ctx) => store.persistSnapshot(ctx));
-  pi.on("session_shutdown", (_event, ctx) => {
-    killAllRunning();
-    if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
+  createSubagentRuntime(pi, {
+    toolName: "mini_subagent",
+    toolLabel: "Mini Subagent",
+    spawnFlagEnv: "PI_SUBAGENT",
+    toolDescription:
+      "Delegate a task to a transient headless subagent (a separate pi process) and get its findings back. " +
+      "Modes: single (task) or parallel (tasks array, max 8). Subagents are read-only by default; set allowWrite to let one edit files. " +
+      "If a subagent reports it needs input (NEEDS_INPUT), answer the questions and call again with `answers`.",
+    promptSnippet:
+      "Delegate a task to a transient read-only subagent (single or parallel)",
+    promptGuidelines: [
+      "Subagents are read-only unless you set allowWrite: true.",
+      "If a result asks for input, answer the questions (ask the user if needed) and re-call with `answers` — do not guess.",
+    ],
+    promptInstructions: {
+      always: "You are a transient subagent. Complete the task, then stop",
+      readOnly:
+        "You may only READ and EXPLORE. Do not modify files or run mutating commands.",
+      writeAllowed:
+        "You may edit files ONLY if strictly necessary, preferring hash-anchored operations (replace/insert) over rewriting.",
+    },
+    needsInput: {
+      marker: NEEDS_INPUT_MARKER,
+      suffix: NEEDS_INPUT_SUFFIX,
+    },
+    allowlists: {
+      readOnly: READ_ONLY_TOOLS,
+      writeable: WRITE_TOOLS,
+    },
+
+    limits: {
+      maxPanelRows: MAX_PANEL_ROWS,
+      maxConcurrency: MAX_CONCURRENCY,
+      maxStoredOutput: MAX_STORED_OUTPUT,
+      maxParallelTasks: MAX_PARALLEL_TASKS,
+      perTaskOutputCap: PER_TASK_OUTPUT_CAP,
+    },
+
+    state: { entryType: STATE_ENTRY },
+    report: { entryType: REPORT_ENTRY },
+
+    panel: {
+      widgetKey: WIDGET_KEY,
+      toggleChord: PANEL_TOGGLE_CHORD,
+      title: "Subagents",
+      emptyText: "No subagents yet. Ask the agent to delegate a task!",
+    },
+
+    rowLine: (r, theme) => getStyledSubagent(r, theme),
+    reportSections: (s) => {
+      const byStatus = s.records.reduce<Record<string, SubagentRecord[]>>(
+        (acc, curr) => {
+          const label = capitalize(curr.status.toLowerCase()).replaceAll(
+            "_",
+            " ",
+          );
+
+          if (!acc[label]?.length) acc[label] = [];
+
+          acc[label].push(curr);
+
+          return acc;
+        },
+        {},
+      );
+
+      return Object.entries(byStatus).map(([label, records]) => ({
+        label,
+        records,
+      }));
+    },
   });
 }

package/src/command.ts

@@ -1,71 +0,0 @@
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-
-import { REPORT_ENTRY } from "./constants";
-import type { SubagentStore } from "./state";
-import type { SubagentRecord } from "./types";
-import { getStyledSubagent } from "./utils";
-
-function renderReport(records: SubagentRecord[], theme: Theme): string {
-  if (records.length === 0) return `  ${theme.fg("dim", "No subagents.")}`;
-
-  const lines: string[] = [];
-  const section = (label: string, items: SubagentRecord[]): void => {
-    if (items.length === 0) return;
-
-    lines.push(`  ${theme.fg("muted", `${label} (${items.length})`)}`);
-
-    for (const r of items) {
-      lines.push(getStyledSubagent(r, theme));
-    }
-
-    lines.push("");
-  };
-
-  section(
-    "Running",
-    records.filter((r) => r.status === "running"),
-  );
-
-  section(
-    "Needs input",
-    records.filter((r) => r.status === "needs_input"),
-  );
-
-  section(
-    "Completed",
-    records.filter((r) => r.status === "completed"),
-  );
-
-  section(
-    "Failed",
-    records.filter((r) => r.status === "failed"),
-  );
-
-  return lines.join("\n");
-}
-
-export function registerSubagentsCommand(
-  pi: ExtensionAPI,
-  store: SubagentStore,
-): void {
-  pi.registerCommand("subagents", {
-    description: "Show all subagents grouped by status",
-    handler: async (_args, ctx) => {
-      if (!ctx.hasUI) {
-        ctx.ui.notify("/subagents requires interactive mode", "error");
-        return;
-      }
-
-      pi.appendEntry(REPORT_ENTRY, {
-        records: [...store.getState(ctx).records],
-      });
-    },
-  });
-
-  pi.registerEntryRenderer<{ records: SubagentRecord[] }>(
-    REPORT_ENTRY,
-    (entry, _options, theme) =>
-      new Text(renderReport(entry.data?.records ?? [], theme), 0, 0),
-  );
-}

package/src/core.ts

@@ -1,104 +0,0 @@
-import {
-  MAX_STORED_OUTPUT,
-  NEEDS_INPUT_MARKER,
-  READ_ONLY_TOOLS,
-  WRITE_TOOLS,
-} from "./constants";
-import type { SubagentStatus } from "./types";
-
-const ALWAYS = "You are a transient subagent. Complete the task, then stop";
-const READ_ONLY = `You may only READ and EXPLORE. Do not modify files or run mutating commands.`;
-const WRITE_OK = `You may edit files ONLY if strictly necessary, preferring hash-anchored operations (replace/insert) over rewriting.`;
-
-const QUESTIONS_SUFFIX = `If the task cannot be completed without information you cannot obtain yourself, end your final message with the exact block below and stop — do not guess:
-
-${NEEDS_INPUT_MARKER}
-- <question>
-
-Report your findings clearly and concisely.`;
-
-/** Dynamic minimal prompt: read-only always; write permission added only when allowed. */
-export function buildSystemPrompt(allowWrite: boolean): string {
-  let prompt = ALWAYS;
-
-  if (!allowWrite) prompt += `\n\n${READ_ONLY}`;
-  else prompt += `\n\n${WRITE_OK}`;
-
-  return `${prompt}\n\n${QUESTIONS_SUFFIX}`;
-}
-
-/** Tool allowlist for the spawned child process. */
-export function buildAllowlist(allowWrite: boolean): string[] {
-  return allowWrite ? WRITE_TOOLS : READ_ONLY_TOOLS;
-}
-
-/**
- * Extract the questions the subagent needs answered, if it emitted the
- * NEEDS_INPUT block. Returns `[]` when the marker is present but no bullet
- * lines follow, and `undefined` when the marker is absent.
- */
-export function parseNeedsInput(text: string): string[] | undefined {
-  const lines = text.split("\n");
-  const idx = lines.findIndex((l) => l.trim() === NEEDS_INPUT_MARKER);
-  if (idx === -1) return undefined;
-
-  const questions: string[] = [];
-
-  for (const line of lines.slice(idx + 1)) {
-    const trimmed = line.trim();
-
-    if (trimmed.startsWith("- ")) {
-      const q = trimmed.slice(2).trim();
-      if (q) questions.push(q);
-    } else if (trimmed === "") {
-      continue;
-    } else {
-      break;
-    }
-  }
-
-  return questions;
-}
-
-/** Classify a finished subagent run into a record status. */
-export function classifyResult(opts: {
-  exitCode: number;
-  stopReason?: string;
-  needsInput: boolean;
-}): SubagentStatus {
-  if (opts.needsInput) return "needs_input";
-
-  if (
-    opts.exitCode !== 0 ||
-    opts.stopReason === "error" ||
-    opts.stopReason === "aborted"
-  ) {
-    return "failed";
-  }
-
-  return "completed";
-}
-
-/** Truncate a string to a char budget, appending an ellipsis marker. */
-export function truncateChars(text: string, max: number): string {
-  if (text.length <= max) return text;
-
-  return `${text.slice(0, max)}…`;
-}
-
-/** Truncate to a UTF-8 byte budget (for parallel per-task caps). */
-export function truncateBytes(text: string, maxBytes: number): string {
-  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-
-  let out = text.slice(0, maxBytes);
-  while (Buffer.byteLength(out, "utf8") > maxBytes) {
-    out = out.slice(0, -1);
-  }
-
-  return `${out}\n\n[Output truncated: ${Buffer.byteLength(text, "utf8") - Buffer.byteLength(out, "utf8")} bytes omitted.]`;
-}
-
-/** Final output kept in the stored record (TUI summary only). */
-export function summarizeOutput(text: string): string {
-  return truncateChars(text, MAX_STORED_OUTPUT);
-}

package/src/spawn.ts

@@ -1,223 +0,0 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { buildAllowlist, buildSystemPrompt } from "./core";
-
-export interface SubagentUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  cost: number;
-  contextTokens: number;
-  turns: number;
-}
-
-export interface SubagentRunResult {
-  /** Final assistant text from the subagent. */
-  output: string;
-  usage: SubagentUsage;
-  model?: string;
-  stopReason?: string;
-  errorMessage?: string;
-  exitCode: number;
-  stderr: string;
-  aborted: boolean;
-}
-
-const activeProcesses = new Set<ChildProcess>();
-
-/** Signal every still-running subagent process (session shutdown cleanup). */
-export function killAllRunning(): void {
-  for (const proc of activeProcesses) {
-    try {
-      proc.kill("SIGTERM");
-    } catch {
-      /* already gone */
-    }
-  }
-}
-
-/** Resolve the command that re-invokes pi (handles bun virtual scripts). */
-function getPiInvocation(args: string[]): { command: string; args: string[] } {
-  const currentScript = process.argv[1];
-  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
-  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
-    return { command: process.execPath, args: [currentScript, ...args] };
-  }
-  const execName = path.basename(process.execPath).toLowerCase();
-  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-  if (!isGenericRuntime) return { command: process.execPath, args };
-  return { command: "pi", args };
-}
-
-async function writePromptTempFile(
-  prompt: string,
-): Promise<{ dir: string; filePath: string }> {
-  const dir = await fs.promises.mkdtemp(
-    path.join(os.tmpdir(), "pi-mini-subagent-"),
-  );
-  const filePath = path.join(dir, "prompt.md");
-  await fs.promises.writeFile(filePath, prompt, {
-    encoding: "utf-8",
-    mode: 0o600,
-  });
-  return { dir, filePath };
-}
-
-/** Extract the last text part of an assistant message. */
-function extractText(msg: any): string {
-  const content = Array.isArray(msg?.content) ? msg.content : [];
-  for (let i = content.length - 1; i >= 0; i--) {
-    const part = content[i];
-    if (part?.type === "text" && typeof part.text === "string")
-      return part.text;
-  }
-  return "";
-}
-
-export interface RunSubagentOptions {
-  cwd: string;
-  task: string;
-  allowWrite: boolean;
-  answers?: string;
-  signal?: AbortSignal;
-}
-
-/**
- * Spawn a transient headless pi subprocess, stream its JSON events, and
- * resolve with the final output once it exits.
- */
-export async function runSubagent(
-  opts: RunSubagentOptions,
-): Promise<SubagentRunResult> {
-  const prompt = buildSystemPrompt(opts.allowWrite);
-  const { dir: tmpDir, filePath: tmpPath } = await writePromptTempFile(prompt);
-
-  const taskText = opts.answers
-    ? `Task: ${opts.task}\n\nAnswers from the user:\n${opts.answers}`
-    : `Task: ${opts.task}`;
-
-  const args = [
-    "--mode",
-    "json",
-    "-p",
-    "--no-session",
-    "--tools",
-    buildAllowlist(opts.allowWrite).join(","),
-    "--append-system-prompt",
-    tmpPath,
-    taskText,
-  ];
-
-  const result: SubagentRunResult = {
-    output: "",
-    usage: {
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 0,
-      turns: 0,
-    },
-    exitCode: 0,
-    stderr: "",
-    aborted: false,
-  };
-
-  try {
-    const exitCode = await new Promise<number>((resolve) => {
-      const invocation = getPiInvocation(args);
-      const proc = spawn(invocation.command, invocation.args, {
-        cwd: opts.cwd,
-        shell: false,
-        stdio: ["ignore", "pipe", "pipe"],
-        env: { ...process.env, PI_SUBAGENT: "1" },
-      });
-      activeProcesses.add(proc);
-
-      let buffer = "";
-      const processLine = (line: string) => {
-        if (!line.trim()) return;
-        let event: any;
-        try {
-          event = JSON.parse(line);
-        } catch {
-          return;
-        }
-
-        if (event.type === "message_end" && event.message) {
-          const msg = event.message;
-          if (msg.role === "assistant") {
-            result.usage.turns++;
-            const usage = msg.usage;
-            if (usage) {
-              result.usage.input += usage.input || 0;
-              result.usage.output += usage.output || 0;
-              result.usage.cacheRead += usage.cacheRead || 0;
-              result.usage.cacheWrite += usage.cacheWrite || 0;
-              result.usage.cost += usage.cost?.total || 0;
-              result.usage.contextTokens = usage.totalTokens || 0;
-            }
-            if (!result.model && msg.model) result.model = msg.model;
-            if (msg.stopReason) result.stopReason = msg.stopReason;
-            if (msg.errorMessage) result.errorMessage = msg.errorMessage;
-            result.output = extractText(msg);
-          }
-        }
-      };
-
-      proc.stdout.on("data", (data) => {
-        buffer += data.toString();
-        const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
-        for (const line of lines) processLine(line);
-      });
-
-      proc.stderr.on("data", (data) => {
-        result.stderr += data.toString();
-      });
-
-      proc.on("close", (code) => {
-        activeProcesses.delete(proc);
-        if (buffer.trim()) processLine(buffer);
-        resolve(code ?? 0);
-      });
-
-      proc.on("error", () => {
-        activeProcesses.delete(proc);
-        resolve(1);
-      });
-
-      if (opts.signal) {
-        const kill = () => {
-          result.aborted = true;
-          proc.kill("SIGTERM");
-          setTimeout(() => {
-            try {
-              proc.kill("SIGKILL");
-            } catch {
-              /* already dead */
-            }
-          }, 5000);
-        };
-        if (opts.signal.aborted) kill();
-        else opts.signal.addEventListener("abort", kill, { once: true });
-      }
-    });
-
-    result.exitCode = exitCode;
-    if (result.aborted) result.stopReason = "aborted";
-    return result;
-  } finally {
-    try {
-      fs.unlinkSync(tmpPath);
-      fs.rmdirSync(tmpDir);
-    } catch {
-      /* ignore */
-    }
-  }
-}

package/src/state.ts

@@ -1,97 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-import { STATE_ENTRY } from "./constants";
-import type { SubagentRecord, SubagentState } from "./types";
-
-/**
- * Session-scoped subagent state.
- *
- * Keyed by session id so forked/parallel sessions never overwrite each other,
- * and replayed from the session branch on session events so it survives
- * /reload and compaction without the extension writing its own files.
- * Running records are dropped on replay — their processes do not survive a reload.
- */
-export class SubagentStore {
-  private readonly stateBySession = new Map<string, SubagentState>();
-
-  constructor(
-    private readonly persist: (snapshot: SubagentState) => void,
-    private readonly emitChange: (ctx: ExtensionContext) => void,
-  ) {}
-
-  private sid(ctx: ExtensionContext): string {
-    return ctx.sessionManager.getSessionId();
-  }
-
-  getState(ctx: ExtensionContext): SubagentState {
-    const sid = this.sid(ctx);
-    let s = this.stateBySession.get(sid);
-    if (!s) this.stateBySession.set(sid, (s = { records: [], nextId: 1 }));
-    return s;
-  }
-
-  /** Commit a snapshot: update memory, persist, refresh the panel. */
-  commit(ctx: ExtensionContext, next: SubagentState): void {
-    this.stateBySession.set(this.sid(ctx), next);
-    this.persist(next);
-    this.emitChange(ctx);
-  }
-
-  /** Create a `running` record and commit it. */
-  start(
-    ctx: ExtensionContext,
-    task: string,
-    allowWrite: boolean,
-    cwd?: string,
-  ): SubagentRecord {
-    const s = this.getState(ctx);
-    const record: SubagentRecord = {
-      id: s.nextId,
-      task,
-      status: "running",
-      allowWrite,
-      cwd,
-      startedAt: Date.now(),
-    };
-    this.commit(ctx, { records: [...s.records, record], nextId: s.nextId + 1 });
-    return record;
-  }
-
-  /** Patch an existing record in place and commit. */
-  finish(
-    ctx: ExtensionContext,
-    id: number,
-    patch: Partial<SubagentRecord>,
-  ): void {
-    const s = this.getState(ctx);
-    this.commit(ctx, {
-      records: s.records.map((r) => (r.id === id ? { ...r, ...patch } : r)),
-      nextId: s.nextId,
-    });
-  }
-
-  /** Rebuild the current session's state from the branch (no disk writes). */
-  replay(ctx: ExtensionContext): void {
-    const s = this.getState(ctx);
-    s.records = [];
-    s.nextId = 1;
-
-    for (const entry of ctx.sessionManager.getBranch()) {
-      if (entry.type === "custom" && entry.customType === STATE_ENTRY) {
-        const d = entry.data as SubagentState | undefined;
-        if (d) {
-          s.records = d.records.filter((r) => r.status !== "running");
-          s.nextId = d.nextId;
-        }
-      }
-    }
-
-    this.emitChange(ctx);
-  }
-
-  /** Persist the latest snapshot right before compaction so it lands after the cut point. */
-  persistSnapshot(ctx: ExtensionContext): void {
-    const s = this.getState(ctx);
-    if (s.records.length > 0) this.persist(s);
-  }
-}

package/src/tool.ts

@@ -1,321 +0,0 @@
-import { Type } from "typebox";
-import type {
-  AgentToolResult,
-  ExtensionAPI,
-} from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-
-import {
-  MAX_CONCURRENCY,
-  MAX_PARALLEL_TASKS,
-  PER_TASK_OUTPUT_CAP,
-} from "./constants";
-import {
-  classifyResult,
-  parseNeedsInput,
-  summarizeOutput,
-  truncateBytes,
-} from "./core";
-import { runSubagent } from "./spawn";
-import type { SubagentStore } from "./state";
-import type { SubagentDetails, SubagentRecord } from "./types";
-
-const TaskItem = Type.Object({
-  task: Type.String({ description: "Task to delegate to a subagent" }),
-  allowWrite: Type.Optional(
-    Type.Boolean({
-      description: "Allow the subagent to edit files. Default: false.",
-    }),
-  ),
-  answers: Type.Optional(
-    Type.String({
-      description: "Answers to a prior NEEDS_INPUT, for re-spawn of this task",
-    }),
-  ),
-  cwd: Type.Optional(
-    Type.String({ description: "Working directory for this subagent" }),
-  ),
-});
-
-const MiniSubagentParams = Type.Object({
-  task: Type.Optional(
-    Type.String({ description: "Task to delegate (single mode)" }),
-  ),
-  tasks: Type.Optional(
-    Type.Array(TaskItem, {
-      description: "Tasks to delegate in parallel (max 8)",
-    }),
-  ),
-  allowWrite: Type.Optional(
-    Type.Boolean({
-      description: "Allow write for single mode. Default: false.",
-    }),
-  ),
-  answers: Type.Optional(
-    Type.String({
-      description: "Answers to a prior NEEDS_INPUT (single mode re-spawn)",
-    }),
-  ),
-  cwd: Type.Optional(
-    Type.String({ description: "Working directory (single mode)" }),
-  ),
-});
-
-async function mapWithConcurrencyLimit<TIn, TOut>(
-  items: TIn[],
-  concurrency: number,
-  fn: (item: TIn, index: number) => Promise<TOut>,
-): Promise<TOut[]> {
-  if (items.length === 0) return [];
-
-  const limit = Math.max(1, Math.min(concurrency, items.length));
-  const results = new Array<TOut>(items.length);
-
-  let next = 0;
-  const workers = new Array(limit).fill(null).map(async () => {
-    while (true) {
-      const i = next++;
-      if (i >= items.length) return;
-      results[i] = await fn(items[i], i);
-    }
-  });
-
-  await Promise.all(workers);
-  return results;
-}
-
-function needsInputContent(r: SubagentRecord): string {
-  const qs = (r.questions ?? []).map((q) => `- ${q}`).join("\n");
-
-  return `The subagent needs input to complete this task.\n\nQuestions:\n${qs || "- (unparsed)"}\n\nAsk the user (or answer from context), then call mini_subagent again with the same \`task\` and your answers in \`answers\`.`;
-}
-
-function singleContent(r: SubagentRecord): string {
-  if (r.status === "needs_input") return needsInputContent(r);
-
-  if (r.status === "failed") {
-    return `Subagent failed: ${r.error ?? r.output ?? "(no output)"}`;
-  }
-
-  return r.output ?? "(no output)";
-}
-
-export function registerMiniSubagentTool(
-  pi: ExtensionAPI,
-  store: SubagentStore,
-): void {
-  pi.registerTool({
-    name: "mini_subagent",
-    label: "Mini Subagent",
-    parameters: MiniSubagentParams,
-    description:
-      "Delegate a task to a transient headless subagent (a separate pi process) and get its findings back. " +
-      "Modes: single (task) or parallel (tasks array, max 8). Subagents are read-only by default; set allowWrite to let one edit files. " +
-      "If a subagent reports it needs input (NEEDS_INPUT), answer the questions and call again with `answers`.",
-    promptSnippet:
-      "Delegate a task to a transient read-only subagent (single or parallel)",
-    promptGuidelines: [
-      "Subagents are read-only unless you set allowWrite: true.",
-      "If a result asks for input, answer the questions (ask the user if needed) and re-call with `answers` — do not guess.",
-    ],
-
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      const hasTasks = (params.tasks?.length ?? 0) > 0;
-      const hasSingle = Boolean(params.task);
-      const modeCount = Number(hasTasks) + Number(hasSingle);
-
-      const errorResult = (text: string): AgentToolResult<SubagentDetails> => ({
-        content: [{ type: "text", text }],
-        details: { mode: hasTasks ? "parallel" : "single", records: [] },
-      });
-
-      if (modeCount !== 1) {
-        return errorResult(
-          "Provide exactly one of `task` (single) or `tasks` (parallel).",
-        );
-      }
-
-      // single mode
-      if (hasSingle) {
-        const record = store.start(
-          ctx,
-          params.task!,
-          params.allowWrite ?? false,
-          params.cwd,
-        );
-
-        const run = await runSubagent({
-          cwd: params.cwd ?? ctx.cwd,
-          task: params.task!,
-          allowWrite: params.allowWrite ?? false,
-          answers: params.answers,
-          signal,
-        });
-
-        const needsInput = parseNeedsInput(run.output);
-
-        const status = classifyResult({
-          exitCode: run.exitCode,
-          stopReason: run.stopReason,
-          needsInput: needsInput !== undefined,
-        });
-
-        const patch: Partial<SubagentRecord> = {
-          status,
-          output: summarizeOutput(run.output),
-          tokens: run.usage.contextTokens,
-          questions: needsInput,
-          error:
-            status === "failed"
-              ? run.errorMessage || run.stderr.slice(0, 500) || undefined
-              : undefined,
-          finishedAt: Date.now(),
-        };
-
-        store.finish(ctx, record.id, patch);
-        const final = { ...record, ...patch };
-
-        return {
-          content: [{ type: "text", text: singleContent(final) }],
-          details: {
-            mode: "single",
-            records: [final],
-          } satisfies SubagentDetails,
-        };
-      }
-
-      // parallel mode
-      const tasks = params.tasks!;
-      if (tasks.length > MAX_PARALLEL_TASKS) {
-        return errorResult(
-          `Too many parallel tasks (${tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
-        );
-      }
-
-      const results: SubagentRecord[] = tasks.map((t) =>
-        store.start(ctx, t.task, t.allowWrite ?? false, t.cwd),
-      );
-      const makeDetails = (): SubagentDetails => ({
-        mode: "parallel",
-        records: [...results],
-      });
-      const emit = () => {
-        const running = results.filter((r) => r.status === "running").length;
-        const done = results.length - running;
-        onUpdate?.({
-          content: [
-            {
-              type: "text",
-              text: `Parallel: ${done}/${results.length} done, ${running} running…`,
-            },
-          ],
-          details: makeDetails(),
-        });
-      };
-
-      await mapWithConcurrencyLimit(
-        tasks,
-        MAX_CONCURRENCY,
-        async (t, index) => {
-          const run = await runSubagent({
-            cwd: t.cwd ?? ctx.cwd,
-            task: t.task,
-            allowWrite: t.allowWrite ?? false,
-            answers: t.answers,
-            signal,
-          });
-          const needsInput = parseNeedsInput(run.output);
-          const status = classifyResult({
-            exitCode: run.exitCode,
-            stopReason: run.stopReason,
-            needsInput: needsInput !== undefined,
-          });
-          const patch: Partial<SubagentRecord> = {
-            status,
-            output: summarizeOutput(run.output),
-            tokens: run.usage.contextTokens,
-            questions: needsInput,
-            error:
-              status === "failed"
-                ? run.errorMessage || run.stderr.slice(0, 500) || undefined
-                : undefined,
-            finishedAt: Date.now(),
-          };
-          results[index] = { ...results[index], ...patch };
-          store.finish(ctx, results[index].id, patch);
-          emit();
-        },
-      );
-
-      const successCount = results.filter(
-        (r) => r.status === "completed",
-      ).length;
-      const sections = results.map((r) => {
-        let body: string;
-        if (r.status === "completed")
-          body = truncateBytes(r.output ?? "", PER_TASK_OUTPUT_CAP);
-        else if (r.status === "needs_input")
-          body = `Needs input:\n${(r.questions ?? []).map((q) => `- ${q}`).join("\n")}`;
-        else body = r.error ?? "(no output)";
-        return `### #${r.id} ${r.status}\n${body}`;
-      });
-
-      let content = `Parallel: ${successCount}/${results.length} succeeded\n\n${sections.join("\n\n---\n\n")}`;
-      const blocked = results.filter((r) => r.status === "needs_input");
-      if (blocked.length > 0) {
-        content += `\n\nSome subagents need input. Answer their questions, then call mini_subagent again with \`tasks\` for just those tasks (each with its own \`answers\`):\n`;
-        content += blocked
-          .map(
-            (r) =>
-              `- #${r.id}: ${(r.questions ?? []).join(" / ") || "(unparsed)"}`,
-          )
-          .join("\n");
-      }
-
-      return {
-        content: [{ type: "text", text: content }],
-        details: makeDetails(),
-      };
-    },
-
-    renderCall(args, theme) {
-      if (args.tasks && args.tasks.length > 0) {
-        let text =
-          theme.fg("toolTitle", theme.bold("mini_subagent ")) +
-          theme.fg("accent", `parallel (${args.tasks.length} tasks)`);
-        for (const t of args.tasks.slice(0, 3)) {
-          const preview =
-            t.task.length > 40 ? `${t.task.slice(0, 40)}…` : t.task;
-          text += `\n  ${theme.fg("dim", preview)}${t.allowWrite ? theme.fg("warning", " ✎") : ""}`;
-        }
-        if (args.tasks.length > 3)
-          text += `\n  ${theme.fg("muted", `… +${args.tasks.length - 3} more`)}`;
-        return new Text(text, 0, 0);
-      }
-
-      const preview = args.task
-        ? args.task.length > 60
-          ? `${args.task.slice(0, 60)}…`
-          : args.task
-        : "...";
-      let text =
-        theme.fg("toolTitle", theme.bold("mini_subagent ")) +
-        theme.fg("dim", preview);
-      if (args.allowWrite) text += theme.fg("warning", " ✎");
-      return new Text(text, 0, 0);
-    },
-
-    renderResult(result, _options, theme) {
-      const details = result.details as SubagentDetails | undefined;
-      const text =
-        result.content[0]?.type === "text" ? result.content[0].text : "";
-      const statuses = details?.records.map((r) => r.status) ?? [];
-      const color = statuses.includes("failed")
-        ? "error"
-        : statuses.includes("needs_input")
-          ? "warning"
-          : "muted";
-      return new Text(theme.fg(color, text), 0, 0);
-    },
-  });
-}

package/src/types.ts

@@ -1,28 +0,0 @@
-export type SubagentStatus = "running" | "completed" | "failed" | "needs_input";
-
-export interface SubagentRecord {
-  id: number;
-  task: string;
-  cwd?: string;
-  startedAt: number;
-  allowWrite: boolean;
-  finishedAt?: number;
-  status: SubagentStatus;
-
-  /** Final output summary (truncated for storage). */
-  output?: string;
-  tokens?: number;
-  error?: string;
-  questions?: string[];
-}
-
-export interface SubagentState {
-  records: SubagentRecord[];
-  nextId: number;
-}
-
-/** Shape stored in the tool result `details` for rendering. */
-export interface SubagentDetails {
-  mode: "single" | "parallel";
-  records: SubagentRecord[];
-}

package/src/utils.ts

@@ -1,101 +0,0 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
-
-import { MAX_PANEL_ROWS, PANEL_STATE_ICON, STATUS_STYLES } from "./constants";
-import type { SubagentRecord } from "./types";
-
-function formatTokens(n: number): string {
-  if (n < 1000) return `${n} tokens`;
-  if (n < 10000) return `${(n / 1000).toFixed(1)}k tokens`;
-
-  return `${Math.round(n / 1000)}k tokens`;
-}
-
-export function getStyledSubagent(r: SubagentRecord, th: Theme): string {
-  const task = r.task.replace(/\s*[\r\n]+\s*/g, " ");
-  const style = STATUS_STYLES[r.status] ?? STATUS_STYLES.completed;
-
-  let line = `${th.fg(style.fg, style.icon)} ${th.fg("accent", `#${r.id}`)} ${th.fg(style.fg, task)}`;
-
-  if (r.status === "completed" && r.tokens) {
-    line += th.fg("dim", ` · ${formatTokens(r.tokens)}`);
-  }
-
-  if (r.status === "failed") line += th.fg("dim", " · failed");
-  if (r.status === "needs_input") line += th.fg("dim", " · needs input");
-  if (r.allowWrite) line += th.fg("warning", " ✎");
-
-  return line;
-}
-
-export function getStyledSubagentHeader(
-  records: SubagentRecord[],
-  th: Theme,
-  isCollapsed?: boolean,
-): string {
-  const running = records.filter((r) => r.status === "running").length;
-
-  const done = records.length - running;
-  const collapseState = isCollapsed ? "collapsed" : "expanded";
-
-  return th.fg(
-    "accent",
-    `${PANEL_STATE_ICON[collapseState]}   Subagents | ${running} running / ${done} done`,
-  );
-}
-
-export function getStyledSubagentList(
-  records: SubagentRecord[],
-  th: Theme,
-  width: number,
-  isCollapsed?: boolean,
-): string[] {
-  const indent = (str: string, level = 1) => "  ".repeat(Math.abs(level)) + str;
-
-  const lines: string[] = [
-    truncateToWidth(
-      indent(getStyledSubagentHeader(records, th, isCollapsed)),
-      width,
-    ),
-  ];
-
-  if (!isCollapsed) {
-    lines.push("");
-
-    if (records.length === 0) {
-      lines.push(
-        truncateToWidth(
-          indent(
-            th.fg("dim", "No subagents yet. Ask the agent to delegate a task!"),
-            2,
-          ),
-          width,
-        ),
-      );
-    } else {
-      const running = records.filter((r) => r.status === "running");
-      const finished = records.filter((r) => r.status !== "running");
-
-      const visible = [...running, ...finished].slice(0, MAX_PANEL_ROWS);
-
-      for (const r of visible) {
-        lines.push(truncateToWidth(indent(getStyledSubagent(r, th), 2), width));
-      }
-
-      if (records.length > visible.length) {
-        lines.push(
-          truncateToWidth(
-            indent(
-              th.fg("dim", `… +${records.length - visible.length} more`),
-              3,
-            ),
-            width,
-          ),
-        );
-      }
-    }
-  }
-
-  lines.push("");
-  return lines;
-}

package/src/widget.ts

@@ -1,77 +0,0 @@
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-  Theme,
-} from "@earendil-works/pi-coding-agent";
-
-import { PANEL_TOGGLE_CHORD, WIDGET_KEY } from "./constants";
-import type { SubagentStore } from "./state";
-import type { SubagentState } from "./types";
-import { getStyledSubagentList } from "./utils";
-
-let collapsed = true;
-
-class SubagentWidget {
-  private cachedWidth: number | undefined;
-  private cachedLines: string[] | undefined;
-
-  constructor(
-    private readonly theme: Theme,
-    private readonly snapshot: () => SubagentState,
-    private readonly isCollapsed: () => boolean,
-  ) {}
-
-  render(width: number): string[] {
-    if (this.snapshot().records.length === 0) return [];
-
-    if (this.cachedLines !== undefined && this.cachedWidth === width) {
-      return this.cachedLines;
-    }
-
-    const lines = getStyledSubagentList(
-      this.snapshot().records,
-      this.theme,
-      width,
-      this.isCollapsed(),
-    );
-
-    this.cachedWidth = width;
-    this.cachedLines = lines;
-    return lines;
-  }
-
-  invalidate(): void {
-    this.cachedWidth = undefined;
-    this.cachedLines = undefined;
-  }
-}
-
-export function refreshWidget(
-  ctx: ExtensionContext,
-  store: SubagentStore,
-): void {
-  if (!ctx.hasUI) return;
-
-  ctx.ui.setWidget(
-    WIDGET_KEY,
-    (_tui, theme) =>
-      new SubagentWidget(
-        theme,
-        () => store.getState(ctx),
-        () => collapsed,
-      ),
-  );
-}
-
-export function registerSubagentWidget(
-  pi: ExtensionAPI,
-  store: SubagentStore,
-): void {
-  pi.registerShortcut(PANEL_TOGGLE_CHORD, {
-    description: "Toggle subagents panel",
-    handler: (ctx) => {
-      collapsed = !collapsed;
-      refreshWidget(ctx, store);
-    },
-  });
-}