@bacnh85/pi-subagent 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.15.0 (2026-08-09)
+
+### Packaging
+
+- Added `extensions/background.ts`, `history.ts`, `result.ts`, `widget.ts`
+  to `files[]` — they were imported by `index.ts` but missing from the
+  manifest, so the published package would have failed to load.
+
+### Compact collapsed result (no tool-call trace in conversation)
+
+Completed single subagent results no longer dump the tool-call trace
+(`→ ls`, `→ grep`, `→ read …`) into the conversation block. The collapsed
+view now shows the answer preview + usage, matching Claude Code's
+`⎿ Done (N tool uses · tokens)` and pi-task's `⎿ <summary> (Ctrl+O to expand)`
+UX. The full trace remains available via Ctrl+O (expanded) and `/agent`
+(thread viewer); the hint text now points to both.
+
+- `renderSingleResult` collapsed branch: `✓ agent` + `⎿ <first ~200 chars of
+  final output>` + usage + `(Ctrl+O to expand · /agent for full thread)`.
+- Removed the dead `renderDisplayItems` / `COLLAPSED_ITEM_COUNT` — the
+  collapsed path no longer lists tool calls (was the noise source).
+- Parallel and chain collapsed views were already compact (per-task/step
+  one-liners) — unchanged.
+- New tests: `render.test.ts` (5 cases) asserting collapsed shows the answer
+  preview and NOT the tool-call trace, plus error/no-output/hint paths.
+
+### Live progress widget (Phase 1)
+
+A persistent above-editor widget now shows what each running subagent is doing
+right now — spinner, agent name, elapsed time, tool-call count, and the latest
+tool call with ✓/✗/⟳ status. Fed by live `threadStore` subscriptions (per SDK
+session event), not JSONL polling. Replaces the old 30s plain-text
+"still running…" heartbeat.
+
+- One block per running thread (single, parallel, chain), capped at 8 +
+  `+N more running`.
+- Latest tool-call line with `done`/`error`/`in_progress` status derived by
+  pairing assistant `toolCall` parts against later `toolResult` messages.
+- Clears automatically when no threads are running.
+- Inspired by [pi-task](https://github.com/heyhuynhgiabuu/pi-task)'s widget UX,
+  but cheaper: in-process SDK gives per-event live data without polling.
+
+### Background mode + task control (Phase 2)
+
+- `background: true` (single mode only) runs the subagent detached: `execute`
+  returns immediately with a receipt, and completion arrives as a follow-up
+  turn via `sendMessage({ triggerTurn: true, deliverAs: "followUp" })`.
+- `operation: "status"` / `operation: "cancel"` with `taskId` inspects or
+  cancels a running background task without relaunching.
+- A `pi-subagent-complete` message renderer renders the follow-up turn
+  compactly (status icon, agent, output, usage).
+- Background tasks are aborted and the widget is disposed on `session_shutdown`.
+
+### Structured result + history registry (Phase 3)
+
+- New `result.ts`: parent-side structured extraction of the child's final
+  message (summary, findings, files, caveats, next steps) by detecting
+  markdown headers. No child XML contract — we structure the output ourselves.
+- New `history.ts`: durable metadata under `.pi/subagent-history.json`. Every
+  completed task (foreground and background) is recorded.
+- `/subagent history` lists recent delegations with status and timestamp.
+- On restart, prior-session `running` entries are marked `interrupted` (honest
+  about the in-process ceiling: we cannot resume a live SDK session).
+
+## 0.14.1 (2026-08-07)
+
+### Improvements
+
+- Widen peer dependency range to support Pi 0.84.0 (`>=0.80.0 <0.85.0`).
+  No code changes — verified compatible against the 0.84.0 SDK types.
+
 ## 0.14.0 (2026-08-05)
 
 ### Git worktree isolation (`sandbox: worktree`)

package/README.md

@@ -1,6 +1,39 @@
 # @bacnh85/pi-subagent
 
-Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads.
+Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads. A live progress widget shows running tasks above the editor; `background: true` runs detached with follow-up-turn completion.
+
+## Live progress widget
+
+When subagents run, a persistent widget appears above the editor showing each
+running task: spinner, agent name, elapsed time, tool count, and the latest tool
+call with ✓/✗/⟳ status. The widget clears when no tasks are running. Fed by live
+SDK session events — no polling.
+
+## Background mode
+
+Single-mode tasks can run detached with `background: true`:
+
+```ts
+subagent({ agent: "planner", task: "Design the cache layer", background: true })
+```
+
+The tool returns immediately with a receipt (including a `taskId`), and when
+the subagent finishes, the result arrives as a follow-up turn that the parent
+agent reads and acts on. Use task control to inspect or cancel:
+
+```ts
+subagent({ operation: "status", taskId: "bg-..." })   // read-only snapshot
+subagent({ operation: "cancel", taskId: "bg-..." })   // abort a running task
+```
+
+You will be notified on completion — do not poll or sleep.
+
+## History
+
+Every completed task (foreground and background) is recorded to
+`.pi/subagent-history.json`. Use `/subagent history` to list recent
+delegations with status and timestamp. Prior-session running tasks are marked
+`interrupted` on restart (in-process SDK sessions cannot be resumed).
 
 ## Install
 

package/extensions/background.ts

@@ -0,0 +1,351 @@
+/**
+ * Background task execution for pi-subagent.
+ *
+ * A background task runs detached from the parent tool call: `execute` returns
+ * immediately with a receipt, and when the child finishes, a follow-up turn is
+ * delivered via sendMessage({ triggerTurn: true, deliverAs: "followUp" }).
+ *
+ * The in-memory registry supports task control (status/cancel) by taskId.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import type { SubAgentResult, SubAgentProgress } from "./runner.ts";
+import { isFailedResult, getResultOutput, getFinalOutput } from "./runner.ts";
+import type { threadStore as ThreadStoreType } from "./threads.ts";
+import type { AgentScope } from "./agents.ts";
+import { parseStructuredResult } from "./result.ts";
+import { appendHistory } from "./history.ts";
+
+/** Mirrors SubagentDetails from index.ts without a circular import. */
+interface BackgroundDetails {
+  mode: "single" | "parallel" | "chain";
+  agentScope: AgentScope;
+  projectAgentsDir: string | null;
+  results: SubAgentResult[];
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type BackgroundStatus = "running" | "completed" | "failed" | "aborted" | "timeout";
+
+export interface BackgroundTask {
+  id: string;
+  threadId: string;
+  agent: string;
+  task: string;
+  startedAt: number;
+  status: BackgroundStatus;
+  controller: AbortController;
+  result?: SubAgentResult;
+  completedAt?: number;
+}
+
+export interface BackgroundDeps {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  /** Run a single agent (the existing runOne closure). */
+  runOne: (
+    agent: string,
+    task: string,
+    cwd: string | undefined,
+    signal: AbortSignal,
+    timeoutMs: number | undefined,
+    onProgress: (partial: SubAgentResult) => void,
+    onActivity: (progress: SubAgentProgress) => void,
+    onHeartbeatDetails: () => BackgroundDetails,
+    onHeartbeat: () => void,
+    isReadOnly?: boolean,
+  ) => Promise<SubAgentResult>;
+  threadStore: typeof ThreadStoreType;
+}
+
+// ---------------------------------------------------------------------------
+// Registry (in-memory, per-session)
+// ---------------------------------------------------------------------------
+
+const backgroundTasks = new Map<string, BackgroundTask>();
+
+export function getBackgroundTask(id: string): BackgroundTask | undefined {
+  return backgroundTasks.get(id);
+}
+
+export function getAllBackgroundTasks(): BackgroundTask[] {
+  return Array.from(backgroundTasks.values());
+}
+
+export function clearBackgroundTasks(): void {
+  for (const task of backgroundTasks.values()) {
+    task.controller.abort();
+  }
+  backgroundTasks.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Status snapshot (for operation: "status")
+// ---------------------------------------------------------------------------
+
+export interface TaskSnapshot {
+  id: string;
+  agent: string;
+  task: string;
+  status: BackgroundStatus;
+  startedAt: number;
+  completedAt?: number;
+  elapsedMs: number;
+  threadId: string;
+  result?: { output: string; model?: string; usage?: unknown };
+}
+
+export function snapshotTask(task: BackgroundTask, now = Date.now()): TaskSnapshot {
+  const result = task.result;
+  return {
+    id: task.id,
+    agent: task.agent,
+    task: task.task,
+    status: task.status,
+    startedAt: task.startedAt,
+    completedAt: task.completedAt,
+    elapsedMs: now - task.startedAt,
+    threadId: task.threadId,
+    result: result
+      ? { output: getResultOutput(result), model: result.model, usage: result.usage }
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Start a background task
+// ---------------------------------------------------------------------------
+
+export interface StartBackgroundInput {
+  agent: string;
+  task: string;
+  cwd?: string;
+  timeout?: number;
+  agentColor?: string;
+  toolCallId?: string;
+  deps: BackgroundDeps;
+}
+
+export interface StartBackgroundResult {
+  taskId: string;
+  receipt: string;
+}
+
+/**
+ * Start a detached background task. Returns immediately with a receipt.
+ * On completion, delivers a follow-up turn to the parent session.
+ */
+export function startBackgroundTask(input: StartBackgroundInput): StartBackgroundResult {
+  const { agent, task, cwd, timeout, agentColor, toolCallId, deps } = input;
+  const taskId = `bg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+  const controller = new AbortController();
+  const startedAt = Date.now();
+
+  // Create a thread so the task shows in the widget + /agent viewer.
+  const thread = deps.threadStore.createThread({
+    agentName: agent,
+    task,
+    mode: "single",
+    toolCallId,
+    color: agentColor,
+  });
+
+  const bgTask: BackgroundTask = {
+    id: taskId,
+    threadId: thread.id,
+    agent,
+    task,
+    startedAt,
+    status: "running",
+    controller,
+  };
+  backgroundTasks.set(taskId, bgTask);
+
+  // Run detached — the parent does NOT await this.
+  void deps
+    .runOne(
+      agent,
+      task,
+      cwd,
+      controller.signal,
+      timeout,
+      (partial) => deps.threadStore.updateThread(thread.id, { result: partial }),
+      (progress) => deps.threadStore.updateProgress(thread.id, progress),
+      () => ({ mode: "single" as const, agentScope: "user" as const, projectAgentsDir: null, results: [] }),
+      () => deps.threadStore.refreshHeartbeat(thread.id),
+    )
+    .then((result) => {
+      bgTask.result = result;
+      bgTask.completedAt = Date.now();
+      const failed = isFailedResult(result);
+      bgTask.status = failed
+        ? result.stopReason === "timeout"
+          ? "timeout"
+          : result.stopReason === "aborted"
+            ? "aborted"
+            : "failed"
+        : "completed";
+      try {
+        deps.threadStore.updateThread(thread.id, {
+          status: failed ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+          result,
+        });
+      } catch {
+        /* thread store unavailable — non-fatal; status/history already set */
+      }
+      recordHistory(bgTask, result, deps);
+      // Delivery failure must NOT cascade into .catch: the task genuinely
+      // completed, so its status/history must reflect that. Swallow sendMessage
+      // errors (e.g. session already shut down) as non-fatal.
+      try {
+        deliverCompletion(bgTask, result, deps);
+      } catch {
+        /* delivery failed — non-fatal; status/history already recorded */
+      }
+      scheduleEviction(taskId);
+    })
+    .catch((err: unknown) => {
+      // Reached when runOne itself rejects (delivery is isolated above; any
+      // other side-effect throw in .then is also caught here defensively).
+      bgTask.completedAt = Date.now();
+      bgTask.status = "failed";
+      const errMsg = err instanceof Error ? err.message : String(err);
+      try {
+        deps.threadStore.updateThread(thread.id, { status: "failed" });
+      } catch {
+        /* thread store unavailable — non-fatal */
+      }
+      recordHistory(bgTask, undefined, deps, errMsg);
+      try {
+        deliverError(bgTask, errMsg, deps);
+      } catch {
+        /* delivery failed — non-fatal */
+      }
+      scheduleEviction(taskId);
+    });
+
+  const receipt = [
+    `Started background task ${taskId} (${agent}).`,
+    `Use subagent operation:"status" taskId:"${taskId}" to inspect progress.`,
+    "You will be notified automatically when it completes — DO NOT poll or sleep.",
+  ].join("\n");
+
+  return { taskId, receipt };
+}
+
+// ---------------------------------------------------------------------------
+// Completion delivery (follow-up turn)
+// ---------------------------------------------------------------------------
+
+function deliverCompletion(task: BackgroundTask, result: SubAgentResult, deps: BackgroundDeps): void {
+  const output = getFinalOutput(result.messages) || getResultOutput(result) || "(no output)";
+  const failed = isFailedResult(result);
+  const phase = task.status;
+  const summary = output.split("\n").slice(0, 1)[0]!.slice(0, 200);
+  const elapsedMs = (task.completedAt ?? Date.now()) - task.startedAt;
+
+  deps.pi.sendMessage(
+    {
+      customType: "pi-subagent-complete",
+      content: failed
+        ? `Background task ${task.id} (${task.agent}) ${phase}.\n\n${getResultOutput(result)}`
+        : `Background task ${task.id} (${task.agent}) completed.\n\n${output}`,
+      display: true,
+      details: {
+        task_id: task.id,
+        agent: task.agent,
+        status: task.status,
+        summary,
+        full_output: output,
+        elapsed_ms: elapsedMs,
+        model: result.model,
+        usage: result.usage,
+        background: true,
+      },
+    },
+    { triggerTurn: true, deliverAs: "followUp" },
+  );
+}
+
+function deliverError(task: BackgroundTask, errMsg: string, deps: BackgroundDeps): void {
+  deps.pi.sendMessage(
+    {
+      customType: "pi-subagent-complete",
+      content: `Background task ${task.id} (${task.agent}) failed: ${errMsg}`,
+      display: true,
+      details: {
+        task_id: task.id,
+        agent: task.agent,
+        status: "failed" as const,
+        summary: errMsg,
+        full_output: errMsg,
+        background: true,
+      },
+    },
+    { triggerTurn: true, deliverAs: "followUp" },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// History recording (durable metadata for /subagent history)
+// ---------------------------------------------------------------------------
+
+function recordHistory(
+  task: BackgroundTask,
+  result: SubAgentResult | undefined,
+  deps: BackgroundDeps,
+  errMsg?: string,
+): void {
+  try {
+    const output = errMsg ?? (result ? getFinalOutput(result.messages) || getResultOutput(result) : "");
+    const structured = parseStructuredResult(output);
+    const piDir = join(deps.ctx.cwd, CONFIG_DIR_NAME);
+    appendHistory(piDir, {
+      id: task.id,
+      agent: task.agent,
+      task: task.task,
+      status: task.status === "running" ? "interrupted" : (task.status as "completed" | "failed" | "aborted" | "timeout"),
+      startedAt: task.startedAt,
+      completedAt: task.completedAt,
+      summary: structured.summary,
+      background: true,
+      model: result?.model,
+    });
+  } catch {
+    // History file not writable — non-fatal.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cancellation
+// ---------------------------------------------------------------------------
+
+export type CancelOutcome = "cancelled" | "not_found" | "already_done";
+
+export function cancelBackgroundTask(id: string): { outcome: CancelOutcome; task?: BackgroundTask } {
+  const task = backgroundTasks.get(id);
+  if (!task) return { outcome: "not_found" };
+  if (task.status !== "running") return { outcome: "already_done", task };
+  task.controller.abort();
+  // Status will be finalized by the runOne promise resolving with aborted.
+  return { outcome: "cancelled", task };
+}
+
+// ---------------------------------------------------------------------------
+// Eviction — completed tasks are retained briefly for status queries, then
+// dropped so the in-memory registry doesn't grow unbounded across a session.
+// ---------------------------------------------------------------------------
+
+const TASK_RETENTION_MS = 60_000;
+
+function scheduleEviction(taskId: string): void {
+  const timer = setTimeout(() => {
+    backgroundTasks.delete(taskId);
+  }, TASK_RETENTION_MS);
+  timer.unref?.();
+}

package/extensions/history.ts

@@ -0,0 +1,117 @@
+/**
+ * Task history registry — durable metadata for listing and re-run.
+ *
+ * Persists completed task metadata under .pi/subagent-history.json so the user
+ * can review past delegations via `/subagent history`. This is metadata ONLY:
+ * in-process SDK cannot resume a live session, so we never advertise "resume".
+ *
+ * On session start, any `running` entries from a prior session (crash/restart)
+ * are marked `interrupted` — honest about the architectural ceiling.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type HistoryStatus = "completed" | "failed" | "aborted" | "timeout" | "interrupted" | "running";
+
+export interface HistoryEntry {
+  id: string;
+  agent: string;
+  task: string;
+  status: HistoryStatus;
+  startedAt: number;
+  completedAt?: number;
+  summary?: string;
+  cwd?: string;
+  background?: boolean;
+  model?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+const HISTORY_FILE = "subagent-history.json";
+
+/** Maximum history entries kept on disk. */
+export const MAX_HISTORY_ENTRIES = 200;
+
+export function getHistoryPath(piDir: string): string {
+  return join(piDir, HISTORY_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+
+function readJsonArray(file: string): HistoryEntry[] {
+  try {
+    if (!existsSync(file)) return [];
+    const parsed = JSON.parse(readFileSync(file, "utf-8")) as unknown;
+    return Array.isArray(parsed) ? (parsed as HistoryEntry[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function readHistory(piDir: string): HistoryEntry[] {
+  return readJsonArray(getHistoryPath(piDir));
+}
+
+export function appendHistory(piDir: string, entry: HistoryEntry): void {
+  const file = getHistoryPath(piDir);
+  const entries = readJsonArray(file);
+  // Upsert by id — if the id exists, replace it.
+  const idx = entries.findIndex((e) => e.id === entry.id);
+  if (idx >= 0) entries[idx] = entry;
+  else entries.push(entry);
+  writeHistory(piDir, entries);
+  // ponytail: bound the file inline — every append trims, so the file can
+  // never grow unbounded no matter which caller forgets to trim.
+  trimHistory(piDir, MAX_HISTORY_ENTRIES);
+}
+
+export function writeHistory(piDir: string, entries: HistoryEntry[]): void {
+  const file = getHistoryPath(piDir);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(entries, null, 2)}\n`, "utf-8");
+}
+
+export function findHistory(piDir: string, id: string): HistoryEntry | undefined {
+  return readHistory(piDir).find((e) => e.id === id);
+}
+
+/**
+ * On session start, mark any `running` entries from a prior session as
+ * `interrupted`. We cannot resume them (in-process SDK sessions don't survive
+ * a restart). Honest about the architectural ceiling.
+ */
+export function markInterruptedOnRestart(piDir: string): number {
+  const entries = readHistory(piDir);
+  let changed = 0;
+  for (const e of entries) {
+    if (e.status === "running") {
+      e.status = "interrupted";
+      changed++;
+    }
+  }
+  if (changed > 0) writeHistory(piDir, entries);
+  return changed;
+}
+
+/**
+ * Keep the history file bounded — trim to the most recent N entries by
+ * completedAt (or startedAt as fallback). Returns the new length.
+ */
+export function trimHistory(piDir: string, maxEntries = 200): number {
+  const entries = readHistory(piDir);
+  if (entries.length <= maxEntries) return entries.length;
+  entries.sort((a, b) => (b.completedAt ?? b.startedAt) - (a.completedAt ?? a.startedAt));
+  const trimmed = entries.slice(0, maxEntries);
+  writeHistory(piDir, trimmed);
+  return trimmed.length;
+}