@tintinweb/pi-subagents 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.5] - 2026-03-16
+
+### Changed
+- **Widget render-once pattern** — the widget callback is now registered once via `setWidget()` and subsequent updates use `requestRender()` instead of re-registering the entire widget on every `update()` call. Eliminates layout thrashing from repeated widget teardown/setup cycles.
+- **Status bar dedup** — `setStatus()` is now only called when the status text actually changes, avoiding redundant TUI updates.
+- **UICtx change detection** — `setUICtx()` detects context changes and forces widget re-registration, correctly handling session switches.
+
+### Refactored
+- Extracted `renderWidget()` private method — moves all widget content rendering out of the `update()` closure into a standalone method that reads live state on each call.
+- `update()` is now a lightweight coordinator: counts agents, manages registration lifecycle, and triggers re-renders.
+
+## [0.4.4] - 2026-03-16
+
+### Fixed
+- **Race condition in `get_subagent_result` with `wait: true`** — `resultConsumed` is now set before `await record.promise`, preventing a redundant follow-up notification. Previously the `onComplete` callback (attached at spawn time via `.then()`) always fired before the await resumed, seeing `resultConsumed` as false.
+- **Stale agent records across sessions** — new `clearCompleted()` method removes all completed/stopped/errored agent records on `session_start` and `session_switch` events, so tasks from a prior session don't persist into a new one.
+- **`steer_subagent` race on freshly launched agents** — steering an agent before its session initialized silently dropped the message. Now steers are queued on the record and flushed once `onSessionCreated` fires.
+
+### Changed
+- Extracted `removeRecord()` private helper in `AgentManager` — deduplicates dispose+delete logic between `cleanup()` and `clearCompleted()`.
+
+### Added
+- 8 new tests covering `resultConsumed` race condition and `clearCompleted` behavior (185 total).
+
 ## [0.4.3] - 2026-03-13
 
 ### Added
@@ -242,6 +266,8 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.4.5]: https://github.com/tintinweb/pi-subagents/compare/v0.4.4...v0.4.5
+[0.4.4]: https://github.com/tintinweb/pi-subagents/compare/v0.4.3...v0.4.4
 [0.4.3]: https://github.com/tintinweb/pi-subagents/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/tintinweb/pi-subagents/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/tintinweb/pi-subagents/compare/v0.4.0...v0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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

@@ -152,6 +152,13 @@ export class AgentManager {
       onTextDelta: options.onTextDelta,
       onSessionCreated: (session) => {
         record.session = session;
+        // Flush any steers that arrived before the session was ready
+        if (record.pendingSteers?.length) {
+          for (const msg of record.pendingSteers) {
+            session.steer(msg).catch(() => {});
+          }
+          record.pendingSteers = undefined;
+        }
         options.onSessionCreated?.(session);
       },
     })
@@ -300,18 +307,30 @@ export class AgentManager {
     return true;
   }
 
+  /** Dispose a record's session and remove it from the map. */
+  private removeRecord(id: string, record: AgentRecord): void {
+    record.session?.dispose?.();
+    record.session = undefined;
+    this.agents.delete(id);
+  }
+
   private cleanup() {
     const cutoff = Date.now() - 10 * 60_000;
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;
+      this.removeRecord(id, record);
+    }
+  }
 
-      // Dispose and clear session so memory can be reclaimed
-      if (record.session) {
-        record.session.dispose();
-        record.session = undefined;
-      }
-      this.agents.delete(id);
+  /**
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   */
+  clearCompleted(): void {
+    for (const [id, record] of this.agents) {
+      if (record.status === "running" || record.status === "queued") continue;
+      this.removeRecord(id, record);
     }
   }
 

package/src/index.ts

@@ -284,6 +284,10 @@ export default function (pi: ExtensionAPI) {
     getRecord: (id: string) => manager.getRecord(id),
   };
 
+  // Clear completed tasks when a new session starts (e.g. /new) so stale records don't persist
+  pi.on("session_start", () => { manager.clearCompleted(); });
+  pi.on("session_switch", () => { manager.clearCompleted(); });
+
   // Wait for all subagents on shutdown, then dispose the manager
   pi.on("session_shutdown", async () => {
     delete (globalThis as any)[MANAGER_KEY];
@@ -812,8 +816,12 @@ Guidelines:
         return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
       }
 
-      // Wait for completion if requested
+      // Wait for completion if requested.
+      // Pre-mark resultConsumed BEFORE awaiting: onComplete fires inside .then()
+      // (attached earlier at spawn time) and always runs before this await resumes.
+      // Setting the flag here prevents a redundant follow-up notification.
       if (params.wait && record.status === "running" && record.promise) {
+        record.resultConsumed = true;
         await record.promise;
       }
 
@@ -877,7 +885,10 @@ Guidelines:
         return textResult(`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`);
       }
       if (!record.session) {
-        return textResult(`Agent "${params.agent_id}" has no active session yet. It may still be initializing.`);
+        // Session not ready yet — queue the steer for delivery once initialized
+        (record.pendingSteers ??= []).push(params.message);
+        pi.events.emit("subagents:steered", { id: record.id, message: params.message });
+        return textResult(`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`);
       }
 
       try {

package/src/types.ts

@@ -73,6 +73,8 @@ export interface AgentRecord {
   joinMode?: JoinMode;
   /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
   resultConsumed?: boolean;
+  /** Steering messages queued before the session was ready. */
+  pendingSteers?: string[];
   /** Worktree info if the agent is running in an isolated worktree. */
   worktree?: { path: string; branch: string };
   /** Worktree cleanup result after agent completion. */

package/src/ui/agent-widget.ts

@@ -155,6 +155,13 @@ export class AgentWidget {
   /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
   private static readonly ERROR_LINGER_TURNS = 2;
 
+  /** Whether the widget callback is currently registered with the TUI. */
+  private widgetRegistered = false;
+  /** Cached TUI reference from widget factory callback, used for requestRender(). */
+  private tui: any | undefined;
+  /** Last status bar text, used to avoid redundant setStatus calls. */
+  private lastStatusText: string | undefined;
+
   constructor(
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
@@ -162,7 +169,14 @@ export class AgentWidget {
 
   /** Set the UI context (grabbed from first tool execution). */
   setUICtx(ctx: UICtx) {
-    this.uiCtx = ctx;
+    if (ctx !== this.uiCtx) {
+      // UICtx changed — the widget registered on the old context is gone.
+      // Force re-registration on next update().
+      this.uiCtx = ctx;
+      this.widgetRegistered = false;
+      this.tui = undefined;
+      this.lastStatusText = undefined;
+    }
   }
 
   /**
@@ -234,9 +248,11 @@ export class AgentWidget {
     return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
   }
 
-  /** Force an immediate widget update. */
-  update() {
-    if (!this.uiCtx) return;
+  /**
+   * Render the widget content. Called from the registered widget's render() callback,
+   * reading live state each time instead of capturing it in a closure.
+   */
+  private renderWidget(tui: any, theme: Theme): string[] {
     const allAgents = this.manager.listAgents();
     const running = allAgents.filter(a => a.status === "running");
     const queued = allAgents.filter(a => a.status === "queued");
@@ -248,148 +264,196 @@ export class AgentWidget {
     const hasActive = running.length > 0 || queued.length > 0;
     const hasFinished = finished.length > 0;
 
-    // Nothing to show — clear widget
-    if (!hasActive && !hasFinished) {
-      this.uiCtx.setWidget("agents", undefined);
-      this.uiCtx.setStatus("subagents", undefined);
-      if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
-      // Clean up stale entries
-      for (const [id] of this.finishedTurnAge) {
-        if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
-      }
-      return;
-    }
+    // Nothing to show — return empty (widget will be unregistered by update())
+    if (!hasActive && !hasFinished) return [];
 
-    // Status bar
-    if (hasActive) {
-      const statusParts: string[] = [];
-      if (running.length > 0) statusParts.push(`${running.length} running`);
-      if (queued.length > 0) statusParts.push(`${queued.length} queued`);
-      const total = running.length + queued.length;
-      this.uiCtx.setStatus("subagents", `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`);
-    } else {
-      this.uiCtx.setStatus("subagents", undefined);
-    }
-
-    this.widgetFrame++;
+    const w = tui.terminal.columns;
+    const truncate = (line: string) => truncateToWidth(line, w);
+    const headingColor = hasActive ? "accent" : "dim";
+    const headingIcon = hasActive ? "●" : "○";
     const frame = SPINNER[this.widgetFrame % SPINNER.length];
 
-    this.uiCtx.setWidget("agents", (tui, theme) => {
-      const w = tui.terminal.columns;
-      const truncate = (line: string) => truncateToWidth(line, w);
-      const headingColor = hasActive ? "accent" : "dim";
-      const headingIcon = hasActive ? "●" : "○";
+    // Build sections separately for overflow-aware assembly.
+    // Each running agent = 2 lines (header + activity), finished = 1 line, queued = 1 line.
 
-      // Build sections separately for overflow-aware assembly.
-      // Each running agent = 2 lines (header + activity), finished = 1 line, queued = 1 line.
+    const finishedLines: string[] = [];
+    for (const a of finished) {
+      finishedLines.push(truncate(theme.fg("dim", "├─") + " " + this.renderFinishedLine(a, theme)));
+    }
 
-      const finishedLines: string[] = [];
-      for (const a of finished) {
-        finishedLines.push(truncate(theme.fg("dim", "├─") + " " + this.renderFinishedLine(a, theme)));
+    const runningLines: string[][] = []; // each entry is [header, activity]
+    for (const a of running) {
+      const name = getDisplayName(a.type);
+      const modeLabel = getPromptModeLabel(a.type);
+      const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+      const elapsed = formatMs(Date.now() - a.startedAt);
+
+      const bg = this.agentActivity.get(a.id);
+      const toolUses = bg?.toolUses ?? a.toolUses;
+      let tokenText = "";
+      if (bg?.session) {
+        try { tokenText = formatTokens(bg.session.getSessionStats().tokens.total); } catch { /* */ }
       }
 
-      const runningLines: string[][] = []; // each entry is [header, activity]
-      for (const a of running) {
-        const name = getDisplayName(a.type);
-        const modeLabel = getPromptModeLabel(a.type);
-        const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-        const elapsed = formatMs(Date.now() - a.startedAt);
-
-        const bg = this.agentActivity.get(a.id);
-        const toolUses = bg?.toolUses ?? a.toolUses;
-        let tokenText = "";
-        if (bg?.session) {
-          try { tokenText = formatTokens(bg.session.getSessionStats().tokens.total); } catch { /* */ }
-        }
+      const parts: string[] = [];
+      if (toolUses > 0) parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
+      if (tokenText) parts.push(tokenText);
+      parts.push(elapsed);
+      const statsText = parts.join(" · ");
 
-        const parts: string[] = [];
-        if (toolUses > 0) parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
-        if (tokenText) parts.push(tokenText);
-        parts.push(elapsed);
-        const statsText = parts.join(" · ");
+      const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
 
-        const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
-
-        runningLines.push([
-          truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`),
-          truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
-        ]);
-      }
+      runningLines.push([
+        truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`),
+        truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
+      ]);
+    }
 
-      const queuedLine = queued.length > 0
-        ? truncate(theme.fg("dim", "├─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)
-        : undefined;
-
-      // Assemble with overflow cap (heading + overflow indicator = 2 reserved lines).
-      const maxBody = MAX_WIDGET_LINES - 1; // heading takes 1 line
-      const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
-
-      const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
-
-      if (totalBody <= maxBody) {
-        // Everything fits — add all lines and fix up connectors for the last item.
-        lines.push(...finishedLines);
-        for (const pair of runningLines) lines.push(...pair);
-        if (queuedLine) lines.push(queuedLine);
-
-        // Fix last connector: swap ├─ → └─ and │ → space for activity lines.
-        if (lines.length > 1) {
-          const last = lines.length - 1;
-          lines[last] = lines[last].replace("├─", "└─");
-          // If last item is a running agent activity line, fix indent of that line
-          // and fix the header line above it.
-          if (runningLines.length > 0 && !queuedLine) {
-            // The last two lines are the last running agent's header + activity.
-            if (last >= 2) {
-              lines[last - 1] = lines[last - 1].replace("├─", "└─");
-              lines[last] = lines[last].replace("│  ", "   ");
-            }
+    const queuedLine = queued.length > 0
+      ? truncate(theme.fg("dim", "├─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)
+      : undefined;
+
+    // Assemble with overflow cap (heading + overflow indicator = 2 reserved lines).
+    const maxBody = MAX_WIDGET_LINES - 1; // heading takes 1 line
+    const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
+
+    const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
+
+    if (totalBody <= maxBody) {
+      // Everything fits — add all lines and fix up connectors for the last item.
+      lines.push(...finishedLines);
+      for (const pair of runningLines) lines.push(...pair);
+      if (queuedLine) lines.push(queuedLine);
+
+      // Fix last connector: swap ├─ → └─ and │ → space for activity lines.
+      if (lines.length > 1) {
+        const last = lines.length - 1;
+        lines[last] = lines[last].replace("├─", "└─");
+        // If last item is a running agent activity line, fix indent of that line
+        // and fix the header line above it.
+        if (runningLines.length > 0 && !queuedLine) {
+          // The last two lines are the last running agent's header + activity.
+          if (last >= 2) {
+            lines[last - 1] = lines[last - 1].replace("├─", "└─");
+            lines[last] = lines[last].replace("│  ", "   ");
           }
         }
-      } else {
-        // Overflow — prioritize: running > queued > finished.
-        // Reserve 1 line for overflow indicator.
-        let budget = maxBody - 1;
-        let hiddenRunning = 0;
-        let hiddenFinished = 0;
-
-        // 1. Running agents (2 lines each)
-        for (const pair of runningLines) {
-          if (budget >= 2) {
-            lines.push(...pair);
-            budget -= 2;
-          } else {
-            hiddenRunning++;
-          }
+      }
+    } else {
+      // Overflow — prioritize: running > queued > finished.
+      // Reserve 1 line for overflow indicator.
+      let budget = maxBody - 1;
+      let hiddenRunning = 0;
+      let hiddenFinished = 0;
+
+      // 1. Running agents (2 lines each)
+      for (const pair of runningLines) {
+        if (budget >= 2) {
+          lines.push(...pair);
+          budget -= 2;
+        } else {
+          hiddenRunning++;
         }
+      }
 
-        // 2. Queued line
-        if (queuedLine && budget >= 1) {
-          lines.push(queuedLine);
+      // 2. Queued line
+      if (queuedLine && budget >= 1) {
+        lines.push(queuedLine);
+        budget--;
+      }
+
+      // 3. Finished agents
+      for (const fl of finishedLines) {
+        if (budget >= 1) {
+          lines.push(fl);
           budget--;
+        } else {
+          hiddenFinished++;
         }
+      }
 
-        // 3. Finished agents
-        for (const fl of finishedLines) {
-          if (budget >= 1) {
-            lines.push(fl);
-            budget--;
-          } else {
-            hiddenFinished++;
-          }
-        }
+      // Overflow summary
+      const overflowParts: string[] = [];
+      if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
+      if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
+      const overflowText = overflowParts.join(", ");
+      lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`)
+      );
+    }
+
+    return lines;
+  }
 
-        // Overflow summary
-        const overflowParts: string[] = [];
-        if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
-        if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
-        const overflowText = overflowParts.join(", ");
-        lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`)
-        );
+  /** Force an immediate widget update. */
+  update() {
+    if (!this.uiCtx) return;
+    const allAgents = this.manager.listAgents();
+
+    // Lightweight existence checks — full categorization happens in renderWidget()
+    let runningCount = 0;
+    let queuedCount = 0;
+    let hasFinished = false;
+    for (const a of allAgents) {
+      if (a.status === "running") { runningCount++; }
+      else if (a.status === "queued") { queuedCount++; }
+      else if (a.completedAt && this.shouldShowFinished(a.id, a.status)) { hasFinished = true; }
+    }
+    const hasActive = runningCount > 0 || queuedCount > 0;
+
+    // Nothing to show — clear widget
+    if (!hasActive && !hasFinished) {
+      if (this.widgetRegistered) {
+        this.uiCtx.setWidget("agents", undefined);
+        this.widgetRegistered = false;
+        this.tui = undefined;
       }
+      if (this.lastStatusText !== undefined) {
+        this.uiCtx.setStatus("subagents", undefined);
+        this.lastStatusText = undefined;
+      }
+      if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
+      // Clean up stale entries
+      for (const [id] of this.finishedTurnAge) {
+        if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
+      }
+      return;
+    }
 
-      return { render: () => lines, invalidate: () => {} };
-    }, { placement: "aboveEditor" });
+    // Status bar — only call setStatus when the text actually changes
+    let newStatusText: string | undefined;
+    if (hasActive) {
+      const statusParts: string[] = [];
+      if (runningCount > 0) statusParts.push(`${runningCount} running`);
+      if (queuedCount > 0) statusParts.push(`${queuedCount} queued`);
+      const total = runningCount + queuedCount;
+      newStatusText = `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`;
+    }
+    if (newStatusText !== this.lastStatusText) {
+      this.uiCtx.setStatus("subagents", newStatusText);
+      this.lastStatusText = newStatusText;
+    }
+
+    this.widgetFrame++;
+
+    // Register widget callback once; subsequent updates use requestRender()
+    // which re-invokes render() without replacing the component (avoids layout thrashing).
+    if (!this.widgetRegistered) {
+      this.uiCtx.setWidget("agents", (tui, theme) => {
+        this.tui = tui;
+        return {
+          render: () => this.renderWidget(tui, theme),
+          invalidate: () => {
+            // Theme changed — force re-registration so factory captures fresh theme.
+            this.widgetRegistered = false;
+            this.tui = undefined;
+          },
+        };
+      }, { placement: "aboveEditor" });
+      this.widgetRegistered = true;
+    } else {
+      // Widget already registered — just request a re-render of existing components.
+      this.tui?.requestRender();
+    }
   }
 
   dispose() {
@@ -401,5 +465,8 @@ export class AgentWidget {
       this.uiCtx.setWidget("agents", undefined);
       this.uiCtx.setStatus("subagents", undefined);
     }
+    this.widgetRegistered = false;
+    this.tui = undefined;
+    this.lastStatusText = undefined;
   }
 }