@d3ara1n/pi-subagent 1.0.0 → 1.0.1

package/README.md

@@ -260,7 +260,7 @@ When a provider error (429, quota, timeout, ...) kills a run and the whole task
 
 ### Run history
 
-Every completed delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json`, recording role, task, usage, activity log, the **full raw output** (even when the main model saw a compressed/truncated version), and the `fallbackFrom` snapshot when the run was retried on the fallback role. Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
+Every **spawned** delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json` — finished, failed, and aborted alike (an aborted run already consumed tokens, so its partial activity and cost stay auditable). Records cover role, task, usage, activity log, the **full raw output** (even when the main model saw a compressed/truncated version), and the `fallbackFrom` snapshot when the run was retried on the fallback role. Runs that never spawned (cancelled while queued, role/model resolution failures) are not recorded. Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/history.ts

@@ -1,9 +1,13 @@
 /**
  * History persistence for pi-subagent delegate runs.
  *
- * Best-effort audit log: writes one JSON record per delegate run under
- * ~/.pi/subagent/history/{sessionId}/{toolCallId}.json. Never throws — persistence
- * must not fail the delegation. Privacy parity with pi's own session files.
+ * Best-effort audit log: writes one JSON record per *spawned* delegate run —
+ * finished, failed, and aborted alike (an aborted run already consumed
+ * tokens, so its partial activity and cost stay auditable). Pre-run failures
+ * that never spawned (queued-cancel, role/model resolution) are not recorded.
+ * Records land under ~/.pi/subagent/history/{sessionId}/{toolCallId}.json.
+ * Never throws — persistence must not fail the delegation. Privacy parity
+ * with pi's own session files.
  */
 
 import * as os from "node:os";

package/src/index.ts

@@ -345,14 +345,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
       try {
         const result = await run.promise;
 
-        // Pipeline throws (abort, spawn crash) surface as tool errors. The
-        // empty-results frame keeps the TUI on the plain-content fallback.
-        if (run.thrown) {
-          const errorText = `Subagent (${params.role}) error: ${run.thrown.message || run.thrown}`;
-          emit([], errorText);
-          throw new Error(errorText);
-        }
-
         // Fallback note: the main model must know the answer came from the
         // fallback model, not the role's primary — on success AND failure.
         // Budget note: budget stops are intentional successes, but the model
@@ -360,6 +352,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
         const fallbackNote = formatFallbackNote(result);
         const budgetNote = formatBudgetNote(result);
 
+        // Aborts and spawn crashes arrive here too: the engine resolves them
+        // into failed results that keep the partial frame (task, activity,
+        // output, usage), so the TUI renders them like any failure instead
+        // of collapsing to a bare error line.
         if (isFailedResult(result)) {
           const failedText =
             `Subagent (${params.role}) failed: ${result.errorMessage || result.stderr || "unknown error"}\n\nPartial output:\n${result.output}` +

package/src/render.ts

@@ -45,11 +45,11 @@ export const renderDelegateResult: RenderResultFn = (result, { expanded }, theme
   const isRunning = !!details?.results[0] && details.results[0].exitCode === -1;
 
   // Tick elapsed time every second while running; stop once terminal.
-  // Placed BEFORE the empty-results early return so every terminal path
-  // (abort, model-resolution failure, catch) still clears the timer —
-  // otherwise the interval leaks a permanent 1 Hz re-render per aborted run.
-  // The timer calls context.invalidate() so the render recomputes elapsed
-  // time fresh from Date.now() without dirtying the data layer.
+  // Placed BEFORE the missing-details early return so every terminal path
+  // still clears the timer — otherwise the interval leaks a permanent
+  // 1 Hz re-render per row. The timer calls context.invalidate() so the
+  // render recomputes elapsed time fresh from Date.now() without dirtying
+  // the data layer.
   if (isRunning) {
     ensureElapsedTimer(context);
   } else {

package/src/run.test.ts

@@ -123,7 +123,11 @@ test("non-zero exit yields state failed without thrown", async () => {
 });
 
 test("a throwing spawn resolves the promise with a failed result carrying the error", async () => {
-  const spawnImpl: SpawnImpl = async () => {
+  const spawnImpl: SpawnImpl = async (_m, _t, options) => {
+    options.onProgress?.({
+      output: "partial",
+      activityLog: [{ kind: "toolCall", id: "t1", status: "done", toolName: "read", args: {} }],
+    });
     throw new Error("Subagent was aborted");
   };
 
@@ -134,6 +138,67 @@ test("a throwing spawn resolves the promise with a failed result carrying the er
   assert.ok(run.thrown instanceof Error);
   assert.strictEqual(run.thrown.message, "Subagent was aborted");
   assert.strictEqual(result.errorMessage, "Subagent was aborted");
+  // The partial frame survives — the foreground path renders aborts like any
+  // failure (task line + activity + result line) instead of a bare error.
+  assert.strictEqual(result.output, "partial");
+  assert.strictEqual(result.activityLog.length, 1);
+});
+
+test("spawned runs persist to history on every terminal path; pre-run failures do not", async () => {
+  const persisted: SubagentResult[] = [];
+  const persistImpl = (
+    _sessionId: string | undefined,
+    _toolCallId: string,
+    _role: string,
+    _task: string,
+    r: SubagentResult,
+  ) => {
+    persisted.push(r);
+  };
+  const historyConfig = { ...testConfig, history: { enabled: true } };
+
+  // Abort mid-run: the run spawned, so it must be audited.
+  const aborted = startSubagentRun(
+    makeDeps({
+      config: historyConfig,
+      spawnImpl: async (_m, _t, options) => {
+        options.onProgress?.({
+          output: "partial",
+          activityLog: [{ kind: "toolCall", id: "t1", status: "running", toolName: "bash", args: {} }],
+        });
+        throw new Error("Subagent was aborted");
+      },
+      persistImpl,
+    }),
+  );
+  await aborted.promise;
+  assert.equal(persisted.length, 1);
+  assert.match(persisted[0].errorMessage!, /aborted/);
+  assert.equal(persisted[0].activityLog.length, 1);
+
+  // Pre-run failure (roles api unavailable): never spawned, not audited.
+  const prerun = startSubagentRun(
+    makeDeps({
+      config: historyConfig,
+      getRolesApi: () => {
+        throw new Error("not initialized");
+      },
+      persistImpl,
+    }),
+  );
+  await prerun.promise;
+  assert.equal(persisted.length, 1);
+
+  // Normal success is audited too.
+  const ok = startSubagentRun(
+    makeDeps({
+      config: historyConfig,
+      spawnImpl: async () => makeResult({ output: "done" }),
+      persistImpl,
+    }),
+  );
+  await ok.promise;
+  assert.equal(persisted.length, 2);
 });
 
 test("provider error on first attempt retries on the fallback role", async () => {

package/src/run.ts

@@ -48,7 +48,7 @@ export interface RunHandle {
   readonly snapshot: SubagentResult;
   /** Terminal result; undefined while queued/running. */
   readonly result: SubagentResult | undefined;
-  /** Set when the pipeline threw (abort, spawn crash). Foreground callers rethrow; wait/check only see state "failed". */
+  /** Set when the pipeline threw (abort, spawn crash). The terminal result still carries the partial frame — callers report it as an ordinary failed result; wait/check only see state "failed". */
   readonly thrown: Error | undefined;
   /** Resolves with the terminal result once the run finishes (always succeeds). */
   readonly promise: Promise<SubagentResult>;
@@ -81,6 +81,8 @@ export interface StartRunOptions {
   getSessionId?: () => string | undefined;
   /** @internal — injectable spawn for tests. */
   spawnImpl?: typeof spawnSubagent;
+  /** @internal — injectable history persistence for tests. */
+  persistImpl?: typeof persistSubagentHistory;
 }
 
 export function startSubagentRun(opts: StartRunOptions): RunHandle {
@@ -164,11 +166,27 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
     try {
       await opts.gate.acquire(opts.signal);
     } catch {
-      const msg = `Subagent (${opts.role}) was cancelled while queued.`;
-      finish({ ...inputFrame(1, false), errorMessage: msg }, new Error("cancelled while queued"));
+      const msg = "cancelled while queued for a concurrency slot";
+      finish({ ...inputFrame(1, false), errorMessage: msg }, new Error(msg));
       return;
     }
 
+    // Audit every spawned run — finished, failed, and aborted alike: an
+    // aborted run already consumed tokens, so its cost must stay in the
+    // audit log. Pre-run failures (queued-cancel, role/model resolution)
+    // never spawned and are not recorded.
+    const persist = opts.persistImpl ?? persistSubagentHistory;
+    const persistHistory = (terminal: SubagentResult, rawOutput?: string): void => {
+      if (!opts.config.history.enabled) return;
+      let sessionId: string | undefined;
+      try {
+        sessionId = opts.getSessionId?.();
+      } catch {
+        /* ignore */
+      }
+      persist(sessionId, opts.toolCallId, opts.role, opts.task, terminal, rawOutput);
+    };
+
     try {
       // Resolve the model AFTER acquiring so the queued period stays zero-cost.
       let rolesApi: ModelRolesAPI;
@@ -312,37 +330,30 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         runResult.summary = await generateSummary(rolesApi, runResult.output, opts.config.summary);
       }
 
-      // Persist audit record (best-effort; covers both success and failure).
-      // History keeps the raw original output even when LLM/TUI saw a compressed/truncated version.
-      if (opts.config.history.enabled) {
-        let sessionId: string | undefined;
-        try {
-          sessionId = opts.getSessionId?.();
-        } catch {
-          /* ignore */
-        }
-        persistSubagentHistory(sessionId, opts.toolCallId, opts.role, opts.task, runResult, rawOutput);
-      }
+      // Best-effort audit record. The raw original output is kept even when
+      // the LLM/TUI saw a compressed/truncated version.
+      persistHistory(runResult, rawOutput);
 
       finish(runResult);
     } catch (err: any) {
       // Keep whatever the last live frame gathered so aborted/crashed runs
       // still show their partial activity and usage.
       const partial = snapshot;
-      finish(
-        {
-          ...inputFrame(1, false),
-          output: partial.output,
-          usage: partial.usage,
-          model: partial.model,
-          stopReason: partial.stopReason,
-          activityLog: partial.activityLog,
-          budgetMs: partial.budgetMs,
-          elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
-          errorMessage: err?.message || String(err),
-        },
-        err instanceof Error ? err : new Error(String(err)),
-      );
+      const terminal: SubagentResult = {
+        ...inputFrame(1, false),
+        output: partial.output,
+        usage: partial.usage,
+        model: partial.model,
+        stopReason: partial.stopReason,
+        activityLog: partial.activityLog,
+        budgetMs: partial.budgetMs,
+        elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
+        errorMessage: err?.message || String(err),
+      };
+      // The run spawned before throwing — audit it like any terminal state.
+      // The partial output is raw (compression never ran on it).
+      persistHistory(terminal);
+      finish(terminal, err instanceof Error ? err : new Error(String(err)));
     } finally {
       opts.gate.release();
     }

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}/{toolCallId}.json for auditing. */
+  /** Persist every spawned delegate run (finished/failed/aborted alike) to ~/.pi/subagent/history/{sessionId}/{toolCallId}.json for auditing. Pre-run failures that never spawned are not recorded. */
   history: SubagentHistoryConfig;
   summary: SubagentSummaryConfig;
   /**