pi-herdr-subagents 0.1.0 → 0.1.1

package/README.md

@@ -2,8 +2,6 @@
 
 Async subagents for [pi](https://github.com/badlogic/pi-mono) running exclusively in [herdr](https://herdr.dev). Spawn, orchestrate, and manage sub-agent sessions in dedicated herdr tabs or panes. **Fully non-blocking** — the main agent keeps working while subagents run in the background.
 
-https://github.com/user-attachments/assets/30adb156-cfb4-4c47-84ca-dd4aa80cba9f
-
 ## How It Works
 
 Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it.
@@ -25,10 +23,10 @@ subagent({ name: "Scout: DB", agent: "scout", task: "Map database schema" });
 
 ## Install
 
-Install the package explicitly from this repository (replace the URL if you use a fork):
+Install the package from npm:
 
 ```bash
-pi install git:github.com/0xRichardH/pi-herdr-subagents
+pi install npm:pi-herdr-subagents
 ```
 
 This project does not install or load `HazAT/pi-interactive-subagents` automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-subagents",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Interactive subagents for pi running in herdr",
   "keywords": [
     "pi-package"

package/pi-extension/subagents/index.ts

@@ -57,12 +57,12 @@ import {
 /** Absolute path to `pi-extension/subagents`. https://github.com/nodejs/node/issues/37845 */
 const SUBAGENTS_DIR = dirname(fileURLToPath(import.meta.url));
 
-// Survive /reload: clear timers and abort poll loops from the previous module load.
-// /reload re-imports this file, giving fresh module-level state, but closures from
-// the old module keep running. These global symbols preserve reload compatibility.
+// Survive /reload: replace presentation timers while keeping active completion
+// watchers and their registry alive. Old module closures continue watching the
+// children; the reloaded module adopts the shared registry for status/interrupts.
 const WIDGET_INTERVAL_KEY = Symbol.for("pi-subagents/widget-interval");
 const STATUS_INTERVAL_KEY = Symbol.for("pi-subagents/status-interval");
-const POLL_ABORT_KEY = Symbol.for("pi-subagents/poll-abort-controller");
+const RUNTIME_KEY = Symbol.for("pi-subagents/runtime");
 
 {
   const prevInterval = (globalThis as any)[WIDGET_INTERVAL_KEY];
@@ -75,13 +75,6 @@ const POLL_ABORT_KEY = Symbol.for("pi-subagents/poll-abort-controller");
     clearInterval(prevStatusInterval);
     (globalThis as any)[STATUS_INTERVAL_KEY] = null;
   }
-  const prevAbort = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
-  if (prevAbort) prevAbort.abort();
-  (globalThis as any)[POLL_ABORT_KEY] = new AbortController();
-}
-
-function getModuleAbortSignal(): AbortSignal {
-  return ((globalThis as any)[POLL_ABORT_KEY] as AbortController).signal;
 }
 
 const SubagentParams = Type.Object({
@@ -503,6 +496,8 @@ interface RunningSubagent {
     error?: string;
   };
   abortController?: AbortController;
+  /** False after terminal parent shutdown; watcher results must not be delivered. */
+  completionDeliveryEnabled?: boolean;
   cli?: string;
   sentinelFile?: string;
   statusState: SubagentStatusState;
@@ -515,13 +510,50 @@ interface RunningSubagent {
   interactive: boolean;
 }
 
-/** All currently running subagents, keyed by id. */
-const runningSubagents = new Map<string, RunningSubagent>();
+interface SubagentRuntime {
+  runningSubagents: Map<string, RunningSubagent>;
+  pi?: ExtensionAPI;
+  latestCtx?: ExtensionContext;
+}
+
+function createSubagentRuntime(): SubagentRuntime {
+  return { runningSubagents: new Map<string, RunningSubagent>() };
+}
 
-// ── Widget management ──
+/** Runtime state preserved across /reload. */
+const runtime: SubagentRuntime =
+  (globalThis as any)[RUNTIME_KEY] ??
+  ((globalThis as any)[RUNTIME_KEY] = createSubagentRuntime());
+const runningSubagents = runtime.runningSubagents;
+
+export function shouldPreserveSubagentsOnShutdown(reason: unknown): boolean {
+  return reason === "reload";
+}
+
+export function cleanupSubagentsForShutdown(
+  reason: unknown,
+  agents: Map<string, Pick<RunningSubagent, "abortController" | "completionDeliveryEnabled">>,
+): void {
+  if (shouldPreserveSubagentsOnShutdown(reason)) return;
+
+  for (const agent of agents.values()) {
+    agent.completionDeliveryEnabled = false;
+    agent.abortController?.abort();
+  }
+  agents.clear();
+}
+
+export function shouldDeliverSubagentCompletion(
+  running: Pick<RunningSubagent, "completionDeliveryEnabled">,
+): boolean {
+  return running.completionDeliveryEnabled !== false;
+}
 
-/** Latest ExtensionContext from session_start, used for widget updates. */
-let latestCtx: ExtensionContext | null = null;
+export function selectCompletionApi<T>(previous: T, current: T | undefined): T {
+  return current ?? previous;
+}
+
+// ── Widget management ──
 
 /** Interval timer for widget re-renders. */
 let widgetInterval: ReturnType<typeof setInterval> | null = null;
@@ -622,6 +654,7 @@ function renderSubagentWidgetLines(agents: RunningSubagent[], width: number): st
 }
 
 function updateWidget() {
+  const latestCtx = runtime.latestCtx;
   if (!latestCtx?.hasUI) return;
 
   if (runningSubagents.size === 0) {
@@ -1249,7 +1282,7 @@ async function watchSubagent(
   const { name, task, surface, startTime, sessionFile } = running;
 
   try {
-    const result = await waitForCompletion(AbortSignal.any([signal, getModuleAbortSignal()]), {
+    const result = await waitForCompletion(signal, {
       intervalMs: 1000,
       sessionFile,
       sentinelFile: running.sentinelFile,
@@ -1358,13 +1391,21 @@ async function watchSubagent(
 }
 
 export default function subagentsExtension(pi: ExtensionAPI) {
-  // Capture the UI context for widget updates
+  runtime.pi = pi;
+
+  // Capture the UI context for widget updates and restore presentation for
+  // subagents whose watchers survived a reload.
   pi.on("session_start", (_event, ctx) => {
-    latestCtx = ctx;
+    runtime.latestCtx = ctx;
+    if (runningSubagents.size > 0) {
+      startWidgetRefresh();
+      startStatusRefresh(pi);
+      updateWidget();
+    }
   });
 
   // Clean up on session shutdown
-  pi.on("session_shutdown", (_event, _ctx) => {
+  pi.on("session_shutdown", (event, _ctx) => {
     if (widgetInterval) {
       clearInterval(widgetInterval);
       widgetInterval = null;
@@ -1375,12 +1416,8 @@ export default function subagentsExtension(pi: ExtensionAPI) {
       statusInterval = null;
       (globalThis as any)[STATUS_INTERVAL_KEY] = null;
     }
-    const moduleAbort = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
-    if (moduleAbort) moduleAbort.abort();
-    for (const [_id, agent] of runningSubagents) {
-      agent.abortController?.abort();
-    }
-    runningSubagents.clear();
+
+    cleanupSubagentsForShutdown((event as any).reason, runningSubagents);
   });
 
   // Tools denied via PI_DENY_TOOLS env var (set by parent agent based on frontmatter)
@@ -1461,12 +1498,14 @@ export default function subagentsExtension(pi: ExtensionAPI) {
         // Fire-and-forget: start watching in background
         watchSubagent(running, watcherAbort.signal)
           .then((result) => {
+            if (!shouldDeliverSubagentCompletion(running)) return;
             updateWidget(); // reflect removal from Map immediately
+            const completionApi = selectCompletionApi(pi, runtime.pi);
 
             if (result.ping) {
               // Subagent is requesting help — steer a ping message with session path for resume
               const sessionRef = `\n\nSession: ${result.sessionFile}\nResume: pi --session ${result.sessionFile}`;
-              pi.sendMessage(
+              completionApi.sendMessage(
                 {
                   customType: "subagent_ping",
                   content: `Sub-agent "${result.ping.name}" needs help (${formatElapsed(result.elapsed)}):\n\n${result.ping.message}${sessionRef}`,
@@ -1485,7 +1524,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
             const presentation = resolveResultPresentation(result, running.name);
 
-            pi.sendMessage(
+            completionApi.sendMessage(
               {
                 customType: "subagent_result",
                 content: presentation,
@@ -1505,8 +1544,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             );
           })
           .catch((err) => {
+            if (!shouldDeliverSubagentCompletion(running)) return;
             updateWidget();
-            pi.sendMessage(
+            selectCompletionApi(pi, runtime.pi).sendMessage(
               {
                 customType: "subagent_result",
                 content: `Sub-agent "${running.name}" error: ${err?.message ?? String(err)}`,
@@ -1888,11 +1928,13 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
         watchSubagent(running, watcherAbort.signal)
           .then((result) => {
+            if (!shouldDeliverSubagentCompletion(running)) return;
             updateWidget();
+            const completionApi = selectCompletionApi(pi, runtime.pi);
 
             if (result.ping) {
               const sessionRef = `\n\nSession: ${params.sessionPath}\nResume: pi --session ${params.sessionPath}`;
-              pi.sendMessage(
+              completionApi.sendMessage(
                 {
                   customType: "subagent_ping",
                   content: `Sub-agent "${result.ping.name}" needs help (${formatElapsed(result.elapsed)}):\n\n${result.ping.message}${sessionRef}`,
@@ -1920,7 +1962,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
               name,
             );
 
-            pi.sendMessage(
+            completionApi.sendMessage(
               {
                 customType: "subagent_result",
                 content: presentation,
@@ -1938,8 +1980,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             );
           })
           .catch((err) => {
+            if (!shouldDeliverSubagentCompletion(running)) return;
             updateWidget();
-            pi.sendMessage(
+            selectCompletionApi(pi, runtime.pi).sendMessage(
               {
                 customType: "subagent_result",
                 content: `Resume error: ${err?.message ?? String(err)}`,

package/test/test.ts

@@ -6,6 +6,12 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import * as subagentsModule from "../pi-extension/subagents/index.ts";
+import {
+  cleanupSubagentsForShutdown,
+  selectCompletionApi,
+  shouldDeliverSubagentCompletion,
+  shouldPreserveSubagentsOnShutdown,
+} from "../pi-extension/subagents/index.ts";
 
 import {
   getLeafId,
@@ -1479,6 +1485,43 @@ describe("tool registration", () => {
   });
 });
 
+describe("subagent parent lifecycle", () => {
+  it("preserves active subagents during extension reload", () => {
+    const abortController = new AbortController();
+    const agents = new Map([["child", { abortController }]]);
+
+    cleanupSubagentsForShutdown("reload", agents);
+
+    assert.equal(shouldPreserveSubagentsOnShutdown("reload"), true);
+    assert.equal(abortController.signal.aborted, false);
+    assert.equal(shouldDeliverSubagentCompletion(agents.get("child")!), true);
+    assert.equal(agents.size, 1);
+  });
+
+  it("aborts and clears active subagents during final shutdown", () => {
+    for (const reason of ["quit", "new", "resume", "fork", undefined]) {
+      const abortController = new AbortController();
+      const running = { abortController };
+      const agents = new Map([["child", running]]);
+
+      cleanupSubagentsForShutdown(reason, agents);
+
+      assert.equal(shouldPreserveSubagentsOnShutdown(reason), false);
+      assert.equal(abortController.signal.aborted, true);
+      assert.equal(shouldDeliverSubagentCompletion(running), false);
+      assert.equal(agents.size, 0);
+    }
+  });
+
+  it("delivers completion through the reloaded extension API", () => {
+    const previous = { id: "previous" };
+    const current = { id: "current" };
+
+    assert.equal(selectCompletionApi(previous, current), current);
+    assert.equal(selectCompletionApi(previous, undefined), previous);
+  });
+});
+
 describe("subagent activity snapshots", () => {
   function validActivity(overrides: Record<string, unknown> = {}) {
     return {