@d3ara1n/pi-subagent 0.10.3 → 1.0.0

package/src/spawn.ts

@@ -1,9 +1,10 @@
 /**
  * Spawn a pi child process and collect structured output with real-time progress.
  *
- * Uses pi's --mode json to get a JSON event stream.
- * Collects all messages (assistant + tool results) for TUI rendering.
- * Fires onProgress on each event for streaming updates.
+ * Uses pi's --mode json to get a JSON event stream. Fires onProgress on each
+ * event for streaming TUI updates; the message stream is parsed for
+ * usage/output extraction, with thinking blocks and tool calls mirrored into
+ * the activity log for rendering.
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
@@ -134,7 +135,9 @@ export async function spawnSubagent(
     subagentRoles?: string[];
     timeoutMs?: number;
     depth?: number;
+    /** Kill after this many assistant turns; 0/undefined = unlimited (negatives normalize to 0). */
     maxTurns?: number;
+    /** Kill after this cumulative cost in USD; 0/undefined = unlimited (negatives normalize to 0). */
     maxCost?: number;
     signal?: AbortSignal;
     onProgress?: (update: Partial<SubagentResult>) => void;
@@ -144,7 +147,6 @@ export async function spawnSubagent(
     role: "",
     task,
     exitCode: 0,
-    messages: [],
     output: "",
     stderr: "",
     usage: {
@@ -161,17 +163,17 @@ export async function spawnSubagent(
 
   // ── Active-time timeout accounting ──
   // The parent's timeout clock PAUSES while the child is inside a nested
-  // `delegate` tool call, so each nested subagent gets its own full timeout
+  // `subagent_delegate` tool call, so each nested subagent gets its own full timeout
   // budget instead of racing the parent's wall clock. `graceMs` is the
   // accumulated paused time — display only; the verdict is always
   // "active elapsed >= budget" (pausing grants no extra active time).
   const budgetMs = Number.isFinite(options.timeoutMs) ? Math.max(0, options.timeoutMs ?? 0) : 0;
   let activeElapsedAccum = 0; // settled active ms (excludes suspended spans)
   let segmentStart = 0; // wall-clock start of the current active segment; 0 = no active segment
-  let isSuspended = false; // true while a child `delegate` call is in flight
+  let isSuspended = false; // true while a child `subagent_delegate` call is in flight
   let pauseStart = 0; // wall-clock mark when the current suspend began
   let graceMs = 0; // accumulated suspended ms (display only)
-  /** toolCallIds of in-flight `delegate` calls — end events lack toolName, so we pair by id. */
+  /** toolCallIds of in-flight `subagent_delegate` calls — end events lack toolName, so we pair by id. */
   const delegateCallIds = new Set<string>();
 
   let tmpDir: string | null = null;
@@ -264,7 +266,6 @@ export async function spawnSubagent(
     const emitProgress = () => {
       options.onProgress?.({
         output: result.output,
-        messages: [...result.messages],
         usage: { ...result.usage },
         model: result.model,
         stopReason: result.stopReason,
@@ -278,13 +279,16 @@ export async function spawnSubagent(
     // O(1) lookup from toolCallId → activityLog index.
     const toolCallIndex = new Map<string, number>();
 
+    // Normalized turn/cost budgets (0 = unlimited). Role overrides can arrive
+    // raw from settings.json, so negatives/non-finites normalize here.
+    const maxTurns = Number.isFinite(options.maxTurns) ? Math.max(0, options.maxTurns ?? 0) : 0;
+    const maxCost = Number.isFinite(options.maxCost) ? Math.max(0, options.maxCost ?? 0) : 0;
+
     // Kill the child when the configured turn/cost budget is exceeded.
     // Called after each assistant message_end (usage already accumulated).
     const checkBudget = () => {
-      const mt = Number.isFinite(options.maxTurns) ? Math.max(0, options.maxTurns ?? 0) : 0;
-      const mc = Number.isFinite(options.maxCost) ? Math.max(0, options.maxCost ?? 0) : 0;
       if (budgetExceeded || wasTimeout) return;
-      if ((mt > 0 && result.usage.turns >= mt) || (mc > 0 && result.usage.cost >= mc)) {
+      if ((maxTurns > 0 && result.usage.turns >= maxTurns) || (maxCost > 0 && result.usage.cost >= maxCost)) {
         budgetExceeded = true;
         killProc("budget");
       }
@@ -301,7 +305,6 @@ export async function spawnSubagent(
 
       if (event.type === "message_end" && event.message) {
         const msg = event.message as SubagentMessage;
-        result.messages.push(msg);
 
         if (msg.role === "assistant") {
           result.usage.turns++;
@@ -348,9 +351,9 @@ export async function spawnSubagent(
         });
         // Pause the parent timeout clock while the child delegates — nested
         // subagents get their own full budget instead of racing this clock.
-        // Ref-counted: concurrent delegate calls pause once and resume only when
-        // the last in-flight delegate returns.
-        if (event.toolName === "delegate") {
+        // Ref-counted: concurrent subagent_delegate calls pause once and resume
+        // only when the last in-flight one returns.
+        if (event.toolName === "subagent_delegate") {
           const first = delegateCallIds.size === 0;
           delegateCallIds.add(event.toolCallId);
           if (first) suspendTimeout();
@@ -395,14 +398,13 @@ export async function spawnSubagent(
       }
     };
 
-    // Build env with optional subagent allowlist and tmpdir for researcher role
+    // Child env: the role allowlist for nested delegation, the shared scratch
+    // tmpdir for subagent bash work (e.g. git clone), and the nesting depth.
     const childEnv: NodeJS.ProcessEnv = { ...process.env };
     if (options.subagentRoles && options.subagentRoles.length > 0) {
       childEnv.PI_SUBAGENT_ALLOWED = options.subagentRoles.join(",");
     }
-    // Expose tmpdir as env var so subagent bash commands (e.g. git clone) can use it
     childEnv.PI_SUBAGENT_TMPDIR = tmpDir;
-    // Propagate nesting depth so child delegate calls can bound recursion
     childEnv.PI_SUBAGENT_DEPTH = String(options.depth ?? 0);
 
     let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
@@ -427,9 +429,8 @@ export async function spawnSubagent(
       else if (reason === "budget") {
         result.stopReason = "budget_exceeded";
         // Human-readable so the caller/TUI never falls back to raw stderr noise.
-        const mt = Number.isFinite(options.maxTurns) ? Math.max(0, options.maxTurns ?? 0) : 0;
         const why =
-          mt > 0 && result.usage.turns >= mt
+          maxTurns > 0 && result.usage.turns >= maxTurns
             ? `${result.usage.turns} turns`
             : `$${result.usage.cost.toFixed(4)}`;
         result.errorMessage = `Budget exceeded (${why}; partial output returned)`;
@@ -457,7 +458,7 @@ export async function spawnSubagent(
       }, 5000);
     };
 
-    /** Pause the active-time clock (called on child `delegate` start). */
+    /** Pause the active-time clock (called on child `subagent_delegate` start). */
     const suspendTimeout = () => {
       if (isSuspended) return;
       if (segmentStart > 0) {
@@ -471,7 +472,7 @@ export async function spawnSubagent(
       pauseStart = Date.now();
       isSuspended = true;
     };
-    /** Resume the active-time clock (called on child `delegate` end). */
+    /** Resume the active-time clock (called on child `subagent_delegate` end). */
     const resumeTimeout = () => {
       if (!isSuspended) return;
       graceMs += Date.now() - pauseStart;
@@ -540,7 +541,7 @@ export async function spawnSubagent(
           result.stopReason = "error";
         }
 
-        // Budget stops are intentional (success); timeouts and external kills
+        // Budget stops are intentional (finished); timeouts and external kills
         // are failures (non-zero); otherwise use the real exit code.
         resolve(budgetExceeded ? 0 : wasTimeout || externalKill ? (code ?? 128) : (code ?? 0));
       });
@@ -556,7 +557,7 @@ export async function spawnSubagent(
       });
 
       // Start the active-time clock. segmentStart marks the first active span;
-      // it pauses/resumes around child `delegate` calls (see suspend/resumeTimeout).
+      // it pauses/resumes around child `subagent_delegate` calls (see suspend/resumeTimeout).
       // No wall-clock fallback needed: each nested subagent has its own timeout,
       // so a stuck inner run is killed by its own clock and this layer resumes.
       segmentStart = Date.now();
@@ -567,8 +568,7 @@ export async function spawnSubagent(
 
     result.exitCode = exitCode;
     if (wasAborted) throw new Error("Subagent was aborted");
-    // NOTE: large outputs are kept raw here — compression/truncation happens in
-    // the extension layer (index.ts) so the summary model can compress first.
+    // Large outputs stay raw here — compression/summary run in the engine (run.ts).
   } finally {
     // Cleanup temp directory and all contents
     if (tmpDir)

package/src/types.ts

@@ -12,7 +12,7 @@ export interface SubagentConfig {
   maxTurns: number;
   /** Default cumulative cost budget in USD. `0` means unlimited; negative values are normalized to `0`. Per-role maxCost overrides this. */
   maxCost: number;
-  /** Persist each delegate run to ~/.pi/subagent/history/{sessionId}/{id}.json for auditing. */
+  /** Persist each delegate run to ~/.pi/subagent/history/{sessionId}/{toolCallId}.json for auditing. */
   history: SubagentHistoryConfig;
   summary: SubagentSummaryConfig;
   /**
@@ -64,7 +64,7 @@ export interface SubagentRole {
   maxTurns?: number;
   /** Max cumulative cost in USD. `0` means unlimited; negative values are normalized to `0`. */
   maxCost?: number;
-  /** Fallback pi-model-roles role name when this role's model is unavailable (provider error). Defaults to "default". */
+  /** Fallback pi-model-roles role name to retry the whole run on when this role's model hits a provider error. Unset = no retry (the failure stands). */
   fallbackRole?: string;
 }
 
@@ -93,7 +93,7 @@ export interface SubagentUsage {
   turns: number;
 }
 
-/** A message from the subagent's JSON event stream. */
+/** A message from the child's JSON event stream (parsed for usage/output extraction). */
 export interface SubagentMessage {
   role: string;
   content: Array<{
@@ -129,8 +129,6 @@ export interface SubagentResult {
   queued?: boolean;
   /** How `output` was prepared for display: raw, compressed by summary model, or mechanically truncated. */
   outputMethod?: "raw" | "compressed" | "truncated";
-  /** All messages from the event stream (assistant + tool results) */
-  messages: SubagentMessage[];
   /** Last assistant text output */
   output: string;
   /** AI-generated one-line summary for TUI display */
@@ -145,6 +143,8 @@ export interface SubagentResult {
   stopReason?: string;
   /** Error message if failed */
   errorMessage?: string;
+  /** Present when the first attempt hit a provider error and the whole run was retried on the fallback role: what the first attempt ran on and why it failed. The retry overwrites every other trace, so this is the only record of the first attempt. */
+  fallbackFrom?: FallbackFrom;
   /** Real-time activity log: thinking blocks and tool calls in arrival order. */
   activityLog: ActivityEntry[];
 
@@ -165,8 +165,56 @@ export interface SubagentResult {
   context?: string;
 }
 
-/** TUI details structure passed via tool result details. */
+/** Snapshot of a failed first attempt that was retried on the fallback role. */
+export interface FallbackFrom {
+  /** Model identifier the first attempt ran on. */
+  model?: string;
+  /** Stop reason of the first attempt. */
+  stopReason?: string;
+  /** Human-readable error message of the first attempt. */
+  errorMessage?: string;
+  /** Tail of the first attempt's stderr, truncated for diagnostics. */
+  stderrTail?: string;
+}
+
+/** TUI details for a foreground delegate tool result/update: one result per call. */
 export interface SubagentDetails {
-  mode: "single";
   results: SubagentResult[];
 }
+
+// ── Background delegation (delegate background:true / wait / check) ──────
+
+/** Lifecycle state of a delegation run, derived from the latest snapshot frame. */
+export type RunState = "queued" | "running" | "finished" | "failed";
+
+/** Details for a background delegate result — the input snapshot for the TUI's static input block. */
+export interface BackgroundDelegateDetails {
+  /** Registry id (sub-N) the model uses with wait/check. */
+  id: string;
+  role: string;
+  task: string;
+  context?: string;
+  files?: string[];
+}
+
+/** One watched run inside a wait/check view. */
+export interface RunViewEntry {
+  id: string;
+  role: string;
+  /** Live frame while running, terminal result once finished. */
+  result: SubagentResult;
+}
+
+/** Details for wait tool updates/results — the combined live view of all watched runs. */
+export interface WaitDetails {
+  entries: RunViewEntry[];
+  /** True when the wait timed out with unfinished runs (marks the tool result as an error). */
+  timedOut?: boolean;
+}
+
+/** Details for a check tool result — a frozen one-shot snapshot of a single run. */
+export interface CheckDetails {
+  id: string;
+  role: string;
+  result: SubagentResult;
+}