@tintinweb/pi-subagents 0.10.3 → 0.10.4

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.4] - 2026-06-23
+
+### Fixed
+- **Background agent records lost before result is read** ([#108](https://github.com/tintinweb/pi-subagents/issues/108) — thanks [@philipmw](https://github.com/philipmw)). On session switch or `/new`/`/resume`, `clearCompleted()` removed completed agent records regardless of whether the LLM had retrieved the result, causing `get_subagent_result` to return "Agent not found" for agents that had finished but hadn't been checked yet. `clearCompleted()` now accepts a `skipUnconsumed` flag; session event handlers pass `true`, so records with `resultConsumed=false` are preserved across session transitions. The 10-minute cleanup timer handles eventual eviction. Note: a full session shutdown (`session_shutdown`) calls `dispose()` which clears all records unconditionally — that path is not affected by this fix.
+
+### Added
+- **Foreground agent lifecycle completion and conversation logging** ([#105](https://github.com/tintinweb/pi-subagents/pull/105) — thanks [@benrhodeland](https://github.com/benrhodeland)). Two gaps closed: (1) **`onComplete` now fires for foreground agents**, emitting `subagents:completed` / `subagents:failed` lifecycle events and writing a `subagents:record` entry to the parent JSONL — previously only background agents emitted these, leaving cross-extension observers with an orphaned `subagents:started` event and no matching completion. `resultConsumed` is pre-set so the callback skips notifications (the result is returned inline); no change to the tool's return value. (2) **Foreground agent conversations are now streamed to `.output` files** (same `.pi/output/agent-<id>.jsonl` path as background agents) — inline subagent transcripts were previously permanently lost after `spawnAndWait` returned.
+
 ## [0.10.3] - 2026-06-12
 
 ### Added

package/README.md

@@ -124,7 +124,7 @@ Individual agent results render Claude Code-style in the conversation:
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
 
-Background agent completion notifications render as styled boxes:
+Both foreground and background agents stream their full conversation to a `.pi/output/agent-<id>.jsonl` transcript file. Background agent completion notifications render as styled boxes:
 
 ```
 ✓ Find auth files completed
@@ -418,8 +418,8 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 |-------|------|------------|
 | `subagents:created` | Background agent registered | `id`, `type`, `description`, `isBackground` |
 | `subagents:started` | Agent transitions to running (including queued→running) | `id`, `type`, `description` |
-| `subagents:completed` | Agent finished successfully | `id`, `type`, `durationMs`, `tokens` (lifetime `{ input, output, total }`), `toolUses`, `result` |
-| `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
+| `subagents:completed` | Agent finished successfully (background and foreground) | `id`, `type`, `durationMs`, `tokens` (lifetime `{ input, output, total }`), `toolUses`, `result` |
+| `subagents:failed` | Agent errored, stopped, or aborted (background and foreground) | same as completed + `error`, `status` |
 | `subagents:steered` | Steering message sent | `id`, `message` |
 | `subagents:compacted` | Agent's session successfully compacted | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
 | `subagents:scheduled` | Schedule lifecycle change | `{ type: "added" \| "removed" \| "updated" \| "fired" \| "error", … }` (job/agentId/error fields per type) |

package/dist/agent-manager.d.ts

@@ -89,11 +89,24 @@ export declare class AgentManager {
     private startAgent;
     /** Start queued agents up to the concurrency limit. */
     private drainQueue;
+    /**
+     * Called synchronously right after spawn, before onSessionCreated fires.
+     * Lets the caller set up the output file path on the record.
+     * The record is guaranteed to be in this.agents at this point.
+     */
+    private onSpawned?;
     /**
      * Spawn an agent and wait for completion (foreground use).
      * Foreground agents bypass the concurrency queue.
+     * Returns { id, record } so callers can access the agent ID.
+     *
+     * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+     *   Use this to set record.outputFile so streamToOutputFile can pick it up.
      */
-    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">): Promise<AgentRecord>;
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">, onSpawned?: (id: string) => void): Promise<{
+        id: string;
+        record: AgentRecord;
+    }>;
     /**
      * Resume an existing agent session with a new prompt.
      */
@@ -107,8 +120,10 @@ export declare class AgentManager {
     /**
      * Remove all completed/stopped/errored records immediately.
      * Called on session start/switch so tasks from a prior session don't persist.
+     * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+     * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
      */
-    clearCompleted(): void;
+    clearCompleted(skipUnconsumed?: boolean): void;
     /** Whether any agents are still running or queued. */
     hasRunning(): boolean;
     /** Abort all running and queued agents immediately. */

package/dist/agent-manager.js

@@ -225,7 +225,16 @@ export class AgentManager {
                         `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
                 }
             }
-            if (options.isBackground) {
+            // Fire onComplete for foreground agents too — lifecycle symmetry.
+            // Mark resultConsumed so the callback skips notifications (result returned inline).
+            if (!options.isBackground) {
+                record.resultConsumed = true;
+                try {
+                    this.onComplete?.(record);
+                }
+                catch { /* ignore completion side-effect errors */ }
+            }
+            else {
                 this.runningBackground--;
                 try {
                     this.onComplete?.(record);
@@ -259,7 +268,13 @@ export class AgentManager {
                 }
                 catch { /* ignore cleanup errors */ }
             }
-            if (options.isBackground) {
+            // Fire onComplete for foreground agents too — lifecycle symmetry.
+            // Mark resultConsumed so the callback skips notifications (result returned inline).
+            if (!options.isBackground) {
+                record.resultConsumed = true;
+                this.onComplete?.(record);
+            }
+            else {
                 this.runningBackground--;
                 this.onComplete?.(record);
                 this.drainQueue();
@@ -267,6 +282,10 @@ export class AgentManager {
             return "";
         });
         record.promise = promise;
+        // Notify caller that spawn is complete (record is in the map, promise is set).
+        // Called synchronously — onSessionCreated fires asynchronously inside runAgent.
+        // Used by spawnAndWait to let the caller set up output files before streaming starts.
+        this.onSpawned?.(id);
     }
     /** Start queued agents up to the concurrency limit. */
     drainQueue() {
@@ -288,15 +307,33 @@ export class AgentManager {
             }
         }
     }
+    /**
+     * Called synchronously right after spawn, before onSessionCreated fires.
+     * Lets the caller set up the output file path on the record.
+     * The record is guaranteed to be in this.agents at this point.
+     */
+    onSpawned;
     /**
      * Spawn an agent and wait for completion (foreground use).
      * Foreground agents bypass the concurrency queue.
+     * Returns { id, record } so callers can access the agent ID.
+     *
+     * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+     *   Use this to set record.outputFile so streamToOutputFile can pick it up.
      */
-    async spawnAndWait(pi, ctx, type, prompt, options) {
-        const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-        const record = this.agents.get(id);
-        await record.promise;
-        return record;
+    async spawnAndWait(pi, ctx, type, prompt, options, onSpawned) {
+        // Temporarily register the onSpawned hook so startAgent can call it.
+        const prevOnSpawned = this.onSpawned;
+        this.onSpawned = onSpawned;
+        try {
+            const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+            const record = this.agents.get(id);
+            await record.promise;
+            return { id, record };
+        }
+        finally {
+            this.onSpawned = prevOnSpawned;
+        }
     }
     /**
      * Resume an existing agent session with a new prompt.
@@ -379,11 +416,15 @@ export class AgentManager {
     /**
      * Remove all completed/stopped/errored records immediately.
      * Called on session start/switch so tasks from a prior session don't persist.
+     * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+     * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
      */
-    clearCompleted() {
+    clearCompleted(skipUnconsumed = false) {
         for (const [id, record] of this.agents) {
             if (record.status === "running" || record.status === "queued")
                 continue;
+            if (skipUnconsumed && !record.resultConsumed)
+                continue;
             this.removeRecord(id, record);
         }
     }

package/dist/index.js

@@ -406,12 +406,12 @@ export default function (pi) {
     // Capture ctx from session_start for RPC spawn handler + start the scheduler.
     pi.on("session_start", async (_event, ctx) => {
         currentCtx = ctx;
-        manager.clearCompleted();
+        manager.clearCompleted(true);
         if (isSchedulingEnabled() && !scheduler.isActive())
             startScheduler(ctx);
     });
     pi.on("session_before_switch", () => {
-        manager.clearCompleted();
+        manager.clearCompleted(true);
         scheduler.stop();
     });
     const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
@@ -1065,7 +1065,9 @@ Terse command-style prompts produce shallow, generic work.
                 });
             };
             const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
-            // Wire session creation to register in widget
+            // Wire session creation: register in widget + stream to output file.
+            // The output file path is set synchronously after spawn (below),
+            // before onSessionCreated fires — same pattern as background agents.
             const origOnSession = fgCallbacks.onSessionCreated;
             fgCallbacks.onSessionCreated = (session) => {
                 origOnSession(session);
@@ -1077,6 +1079,13 @@ Terse command-style prompts produce shallow, generic work.
                         break;
                     }
                 }
+                // Stream conversation to output file (foreground agent logging)
+                if (fgId) {
+                    const rec = manager.getRecord(fgId);
+                    if (rec?.outputFile) {
+                        rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd);
+                    }
+                }
             };
             // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
             const spinnerInterval = setInterval(() => {
@@ -1086,7 +1095,7 @@ Terse command-style prompts produce shallow, generic work.
             streamUpdate();
             let record;
             try {
-                record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+                const fgResult = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
                     description: params.description,
                     model,
                     maxTurns: effectiveMaxTurns,
@@ -1097,7 +1106,16 @@ Terse command-style prompts produce shallow, generic work.
                     invocation: agentInvocation,
                     signal,
                     ...fgCallbacks,
+                }, (fgAgentId) => {
+                    // onSpawned: called synchronously after spawn, before onSessionCreated fires.
+                    // Set up the output file so streamToOutputFile can pick it up.
+                    const fgRec = manager.getRecord(fgAgentId);
+                    if (fgRec) {
+                        fgRec.outputFile = createOutputFilePath(ctx.cwd, fgAgentId, ctx.sessionManager.getSessionId());
+                        writeInitialEntry(fgRec.outputFile, fgAgentId, params.prompt, ctx.cwd);
+                    }
                 });
+                record = fgResult.record;
             }
             catch (err) {
                 clearInterval(spinnerInterval);
@@ -1671,7 +1689,7 @@ Guidelines for choosing settings:
 - Only include frontmatter fields that differ from defaults — omit fields where the default is fine
 
 Write the file using the write tool. Only write the file, nothing else.`;
-        const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+        const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
             description: `Generate ${name} agent`,
             maxTurns: 5,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -311,7 +311,12 @@ export class AgentManager {
           }
         }
 
-        if (options.isBackground) {
+        // Fire onComplete for foreground agents too — lifecycle symmetry.
+        // Mark resultConsumed so the callback skips notifications (result returned inline).
+        if (!options.isBackground) {
+          record.resultConsumed = true;
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+        } else {
           this.runningBackground--;
           try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
           this.drainQueue();
@@ -342,7 +347,12 @@ export class AgentManager {
           } catch { /* ignore cleanup errors */ }
         }
 
-        if (options.isBackground) {
+        // Fire onComplete for foreground agents too — lifecycle symmetry.
+        // Mark resultConsumed so the callback skips notifications (result returned inline).
+        if (!options.isBackground) {
+          record.resultConsumed = true;
+          this.onComplete?.(record);
+        } else {
           this.runningBackground--;
           this.onComplete?.(record);
           this.drainQueue();
@@ -351,6 +361,11 @@ export class AgentManager {
       });
 
     record.promise = promise;
+
+    // Notify caller that spawn is complete (record is in the map, promise is set).
+    // Called synchronously — onSessionCreated fires asynchronously inside runAgent.
+    // Used by spawnAndWait to let the caller set up output files before streaming starts.
+    this.onSpawned?.(id);
   }
 
   /** Start queued agents up to the concurrency limit. */
@@ -372,9 +387,20 @@ export class AgentManager {
     }
   }
 
+  /**
+   * Called synchronously right after spawn, before onSessionCreated fires.
+   * Lets the caller set up the output file path on the record.
+   * The record is guaranteed to be in this.agents at this point.
+   */
+  private onSpawned?: (id: string) => void;
+
   /**
    * Spawn an agent and wait for completion (foreground use).
    * Foreground agents bypass the concurrency queue.
+   * Returns { id, record } so callers can access the agent ID.
+   *
+   * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+   *   Use this to set record.outputFile so streamToOutputFile can pick it up.
    */
   async spawnAndWait(
     pi: ExtensionAPI,
@@ -382,11 +408,19 @@ export class AgentManager {
     type: SubagentType,
     prompt: string,
     options: Omit<SpawnOptions, "isBackground">,
-  ): Promise<AgentRecord> {
-    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-    const record = this.agents.get(id)!;
-    await record.promise;
-    return record;
+    onSpawned?: (id: string) => void,
+  ): Promise<{ id: string; record: AgentRecord }> {
+    // Temporarily register the onSpawned hook so startAgent can call it.
+    const prevOnSpawned = this.onSpawned;
+    this.onSpawned = onSpawned;
+    try {
+      const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+      const record = this.agents.get(id)!;
+      await record.promise;
+      return { id, record };
+    } finally {
+      this.onSpawned = prevOnSpawned;
+    }
   }
 
   /**
@@ -480,10 +514,13 @@ export class AgentManager {
   /**
    * Remove all completed/stopped/errored records immediately.
    * Called on session start/switch so tasks from a prior session don't persist.
+   * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+   * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
    */
-  clearCompleted(): void {
+  clearCompleted(skipUnconsumed = false): void {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
+      if (skipUnconsumed && !record.resultConsumed) continue;
       this.removeRecord(id, record);
     }
   }

package/src/index.ts

@@ -458,12 +458,12 @@ export default function (pi: ExtensionAPI) {
   // Capture ctx from session_start for RPC spawn handler + start the scheduler.
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
-    manager.clearCompleted();
+    manager.clearCompleted(true);
     if (isSchedulingEnabled() && !scheduler.isActive()) startScheduler(ctx);
   });
 
   pi.on("session_before_switch", () => {
-    manager.clearCompleted();
+    manager.clearCompleted(true);
     scheduler.stop();
   });
 
@@ -1200,7 +1200,9 @@ Terse command-style prompts produce shallow, generic work.
 
       const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
 
-      // Wire session creation to register in widget
+      // Wire session creation: register in widget + stream to output file.
+      // The output file path is set synchronously after spawn (below),
+      // before onSessionCreated fires — same pattern as background agents.
       const origOnSession = fgCallbacks.onSessionCreated;
       fgCallbacks.onSessionCreated = (session: any) => {
         origOnSession(session);
@@ -1212,6 +1214,13 @@ Terse command-style prompts produce shallow, generic work.
             break;
           }
         }
+        // Stream conversation to output file (foreground agent logging)
+        if (fgId) {
+          const rec = manager.getRecord(fgId);
+          if (rec?.outputFile) {
+            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd);
+          }
+        }
       };
 
       // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
@@ -1224,7 +1233,7 @@ Terse command-style prompts produce shallow, generic work.
 
       let record: AgentRecord;
       try {
-        record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+        const fgResult = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
           description: params.description,
           model,
           maxTurns: effectiveMaxTurns,
@@ -1235,7 +1244,16 @@ Terse command-style prompts produce shallow, generic work.
           invocation: agentInvocation,
           signal,
           ...fgCallbacks,
+        }, (fgAgentId) => {
+          // onSpawned: called synchronously after spawn, before onSessionCreated fires.
+          // Set up the output file so streamToOutputFile can pick it up.
+          const fgRec = manager.getRecord(fgAgentId);
+          if (fgRec) {
+            fgRec.outputFile = createOutputFilePath(ctx.cwd, fgAgentId, ctx.sessionManager.getSessionId());
+            writeInitialEntry(fgRec.outputFile, fgAgentId, params.prompt, ctx.cwd);
+          }
         });
+        record = fgResult.record;
       } catch (err) {
         clearInterval(spinnerInterval);
         return textResult(err instanceof Error ? err.message : String(err));
@@ -1838,7 +1856,7 @@ Guidelines for choosing settings:
 
 Write the file using the write tool. Only write the file, nothing else.`;
 
-    const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+    const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
       description: `Generate ${name} agent`,
       maxTurns: 5,
     });