pi-herdr-subagents 0.1.0 → 0.1.2

package/README.md

@@ -2,14 +2,12 @@
 
 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.
+Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all tracked agents with their projected state — for example `starting`, `active`, `waiting`, `interrupted`, `stalled`, `running`, or `finalizing`. The header summarizes **active** (processing) vs **open** (not processing). When every tracked subagent is open, the border switches to amber. 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.
 
 ```
-╭─ Subagents ──────────────────────────── 2 running ─╮
+╭─ Subagents ──────────────────── 1 active · 1 open ─╮
 │ 00:23  Scout: Auth (scout)        active · bash 7m │
 │ 00:45  Scout: DB (scout)                waiting 2m │
 ╰────────────────────────────────────────────────────╯
@@ -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.
@@ -95,31 +93,47 @@ Agent discovery follows priority: **project-local** (`.pi/agents/`) > **global**
 5. Main agent processes result     → continues with new context
 ```
 
-Multiple subagents run concurrently — each steers its result back independently as it finishes. The live widget above the input tracks all running agents:
+Multiple subagents run concurrently — each steers its result back independently as it finishes. The live widget above the input tracks every agent still in flight:
 
 ```
-╭─ Subagents ───────────────────────────────── 3 running ─╮
+╭─ Subagents ──────────────────── 1 active · 2 open ─╮
 │ 01:23  Scout: Auth (scout)            active · write 7m │
 │ 00:45  Researcher (researcher)               stalled 4m │
 │ 00:12  Scout: DB (scout)                      starting… │
 ╰─────────────────────────────────────────────────────────╯
 ```
 
-Completion messages render with a colored background and are expandable with `Ctrl+O` to show the full summary and session file path.
+Completion messages render with a colored background and are expandable with `Ctrl+O` to show the full summary and session file path. Completed rows are removed from the widget as soon as their result is delivered or suppressed.
 
 ### In-progress status updates
 
-The widget tracks each Pi-backed sub-agent from a child-written runtime snapshot and labels it with a coarse state:
+The widget projects each sub-agent from a **process + turn lifecycle**:
+
+- **Herdr pane inspection** is the coarse authority for whether the child process is present and whether Herdr reports it as idle, working, blocked, or done.
+- **Child activity snapshots** enrich the label with Pi-only detail (tool name, streaming, etc.) when available.
+- Session JSONL is still used for transcript, resume, lineage, and result extraction — not for liveness.
+
+Projected labels include:
+
+- `starting` — launched; pane/activity confirmation is still settling
+- `active` — processing work (agent turn, provider request, streaming, or tool execution)
+- `blocked` — Herdr reports the child as blocked
+- `waiting` — turn finished; the process is intentionally open for more input or another stage
+- `interrupted` — the current turn was cancelled (Escape / `subagent_interrupt`); the process stays open and is **not** treated as active processing
+- `stalled` — pane inspection is unhealthy long enough that the parent can no longer trust the run
+- `running` — fallback when only coarse process presence is known (e.g. non-Pi backends)
+- `finalizing` — completion was observed and delivery is in progress; the process elapsed timer freezes here
+
+The widget header counts **active** vs **open**:
+
+- **active** — `active`, `starting`, `running`, or `blocked`
+- **open** — everything else still tracked (`waiting`, `interrupted`, `stalled`, `finalizing`, …)
 
-- `starting` — launched, but no valid child snapshot has been observed yet
-- `active` — the child is doing observed runtime work: agent turn, provider request, streaming, or tool execution
-- `waiting` — the child finished a turn and is intentionally open for more input or another stage
-- `stalled` — the parent has gone too long without a valid current child snapshot and can no longer trust the run is healthy
-- `running` — fallback for backends without child snapshots (e.g. Claude)
+When `activeCount === 0` (every tracked row is open), the border uses an amber accent. Process elapsed time (`MM:SS` on the left) freezes when the process reaches finalizing/completed/failed. Interrupt does **not** freeze that process clock; the interrupted state shows its own duration on the right while the process remains open.
 
-These labels are no longer derived from session-file growth. Session JSONL is still used for transcript, resume, lineage, and result extraction, but Pi-backed liveness now comes from a small activity snapshot written by the child extension. A fixed internal watchdog marks a run as `stalled` when valid snapshots never appear, stop being readable, or stop matching the current child; valid long-running `active` or `waiting` states do not become `stalled` just because time passes. When a run enters `stalled` or recovers from it, the parent agent receives a steer message so it can react. All other status transitions stay in the widget only.
+A fixed internal watchdog marks a run as `stalled` when pane inspection fails or the pane disappears without a completion sidecar; valid long-running `active` or `waiting` states do not become `stalled` just because time passes. When a run enters `stalled` or recovers from it, the parent agent receives a steer message so it can react. All other status transitions stay in the widget only.
 
-**Interactive subagents stay silent.** Long-running user-driven subagents (e.g. `planner`, or any `/iterate` fork) do not wake the parent session on `stalled`/`recovered` transitions — the user is working directly in the subagent's pane, and a steer message there would just burn an orchestrator turn on a no-op "still waiting" ping. The widget still updates normally, and child snapshots are still recorded/classified regardless of the `interactive` setting. By default, agents with `auto-exit: true` are treated as autonomous and get stall pings; agents without it are treated as interactive and stay quiet. Override per-agent with `interactive: true|false` in frontmatter, or per-spawn with `interactive: true|false` on the tool call.
+**Interactive subagents stay silent.** Long-running user-driven subagents (e.g. `planner`, or any `/iterate` fork) do not wake the parent session on `stalled`/`recovered` transitions — the user is working directly in the subagent's pane, and a steer message there would just burn an orchestrator turn on a no-op "still waiting" ping. The widget still updates normally, and activity snapshots are still recorded/classified regardless of the `interactive` setting. By default, agents with `auto-exit: true` are treated as autonomous and get stall pings; agents without it are treated as interactive and stay quiet. Override per-agent with `interactive: true|false` in frontmatter, or per-spawn with `interactive: true|false` on the tool call.
 
 #### Configuration
 
@@ -184,7 +198,7 @@ subagent_interrupt({ id: "abcd1234" });
 subagent_interrupt({ name: "Scout" });
 ```
 
-This sends Escape to the child pane, cancelling the in-progress model turn. The subagent session stays alive — the pane, session file, and background polling all remain intact. After the interrupt, the widget immediately moves the child back to `waiting`, and stale pre-interrupt snapshots are ignored. If the child starts work later, newer snapshots return it to `active`; completion, failure, and `caller_ping` still flow through normally.
+This sends Escape to the child pane, cancelling the in-progress model turn. The subagent session stays alive — the pane, session file, and background polling all remain intact. After the interrupt, the widget immediately labels the child as `interrupted` (counted as **open**, not active processing). Stale pre-interrupt activity snapshots are ignored so a lagging Herdr/`active` reading cannot overwrite the interrupt. The process elapsed timer keeps running because the pane is still open; only the interrupted-state duration freezes relative to the interrupt request. If the child starts work later, newer observations return it to `active`; completion, failure, and `caller_ping` still flow through normally.
 
 This is a turn-level interrupt, not a method for forcibly terminating a subagent session.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-subagents",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Interactive subagents for pi running in herdr",
   "keywords": [
     "pi-package"
@@ -13,6 +13,7 @@
   },
   "type": "module",
   "scripts": {
+    "lint": "oxlint pi-extension test",
     "test": "node --test test/test.ts",
     "test:integration": "node --test --test-concurrency=1 test/integration/*.test.ts"
   },
@@ -29,6 +30,7 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.6",
     "@earendil-works/pi-tui": "^0.80.6",
-    "@sinclair/typebox": "^0.34.52"
+    "@sinclair/typebox": "^0.34.52",
+    "oxlint": "^1.73.0"
   }
 }

package/pi-extension/subagents/completion.ts

@@ -13,6 +13,13 @@ export interface CompletionResult {
 export interface CompletionOptions {
   intervalMs: number;
   readTerminalTail: () => Promise<string>;
+  inspectPane?: () => Promise<import("./lifecycle.ts").PaneInspection>;
+  /** Bounded artifact grace after explicit pane disappearance. Default: 500ms. */
+  paneDisappearanceGraceMs?: number;
+  onPaneInspection?: (
+    inspection: import("./lifecycle.ts").PaneInspection,
+    observedAt: number,
+  ) => void;
   sessionFile?: string;
   sentinelFile?: string;
   onTick?: (elapsedSeconds: number) => void;
@@ -45,7 +52,13 @@ export function interpretExitSidecar(data: unknown): CompletionResult {
     return { reason: "error", exitCode: 1, errorMessage };
   }
 
-  return { reason: "done", exitCode: 0 };
+  if (payload?.type === "done") return { reason: "done", exitCode: 0 };
+
+  return {
+    reason: "error",
+    exitCode: 1,
+    errorMessage: "Invalid subagent completion sidecar: unsupported payload type.",
+  };
 }
 
 function consumeExitSidecar(sessionFile: string | undefined): CompletionResult | null {
@@ -69,6 +82,33 @@ function terminalExitCode(screen: string): number | null {
   return match ? Number.parseInt(match[1], 10) : null;
 }
 
+function completionArtifact(options: CompletionOptions): CompletionResult | null {
+  const sidecar = consumeExitSidecar(options.sessionFile);
+  if (sidecar) return sidecar;
+  if (options.sentinelFile && existsSync(options.sentinelFile)) {
+    return { reason: "sentinel", exitCode: 0 };
+  }
+  return null;
+}
+
+async function waitForDisappearanceArtifacts(
+  signal: AbortSignal,
+  options: CompletionOptions,
+): Promise<CompletionResult | null> {
+  const immediate = completionArtifact(options);
+  if (immediate) return immediate;
+
+  const graceMs = Math.max(0, options.paneDisappearanceGraceMs ?? 500);
+  const deadline = Date.now() + graceMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    await abortableDelay(Math.min(25, remaining), signal);
+    const result = completionArtifact(options);
+    if (result) return result;
+  }
+  return null;
+}
+
 function abortableDelay(milliseconds: number, signal: AbortSignal): Promise<void> {
   if (signal.aborted) return Promise.reject(new Error(ABORT_MESSAGE));
 
@@ -105,7 +145,30 @@ export async function waitForCompletion(
       const exitCode = terminalExitCode(await options.readTerminalTail());
       if (exitCode !== null) return { reason: "sentinel", exitCode };
     } catch {
-      // Pane reads can fail transiently while herdr updates or closes a pane.
+      // Terminal reads are only sentinel/output probes; Herdr status is polled
+      // independently below, even when terminal reads succeed.
+    }
+
+    if (options.inspectPane) {
+      let inspection: import("./lifecycle.ts").PaneInspection;
+      try {
+        inspection = await options.inspectPane();
+      } catch {
+        inspection = { kind: "unavailable", error: "inspectPane threw" };
+      }
+      const observedAt = Date.now();
+      options.onPaneInspection?.(inspection, observedAt);
+      if (inspection.kind === "missing") {
+        // Pane closure and atomic artifact publication are separate operations.
+        // Allow a short bounded grace window before declaring evidence lost.
+        const racedCompletion = await waitForDisappearanceArtifacts(signal, options);
+        if (racedCompletion) return racedCompletion;
+        return {
+          reason: "error",
+          exitCode: 1,
+          errorMessage: "Subagent pane disappeared before completion evidence was recorded.",
+        };
+      }
     }
 
     options.onTick?.(Math.floor((Date.now() - startedAt) / 1000));

package/pi-extension/subagents/herdr.ts

@@ -169,6 +169,72 @@ export async function readHerdrScreenAsync(surface: string, lines = 50): Promise
   return herdrExecAsync(["pane", "read", surface, "--source", "visible", "--lines", String(lines)]);
 }
 
+export type { PaneInspection, HerdrAgentStatus } from "./lifecycle.ts";
+
+type PaneInspectionResult =
+  | { kind: "present"; agent?: string; agentStatus: "idle" | "working" | "blocked" | "done" | "unknown" }
+  | { kind: "missing"; error?: string }
+  | { kind: "unavailable"; error: string };
+
+function parsePaneGetOutput(output: string, surface: string): PaneInspectionResult {
+  const parsed = parseHerdrJson(output) as
+    | { result?: { pane?: unknown }; error?: { code?: unknown; message?: unknown } }
+    | null;
+  const errorObj = parsed?.error;
+  if (errorObj?.code === "pane_not_found" || errorObj?.code === "not_found") {
+    return { kind: "missing", error: typeof errorObj.message === "string" ? errorObj.message : "pane not found" };
+  }
+  const pane = parsed?.result?.pane;
+  if (!pane || typeof pane !== "object") return { kind: "unavailable", error: "pane get returned no pane record" };
+  const record = pane as { pane_id?: unknown; agent?: unknown; agent_status?: unknown };
+  if (record.pane_id !== surface) return { kind: "unavailable", error: "pane id mismatch" };
+  const agent = typeof record.agent === "string" ? record.agent : undefined;
+  const rawStatus = typeof record.agent_status === "string" ? record.agent_status : "unknown";
+  const agentStatus = rawStatus === "idle" ||
+      rawStatus === "working" ||
+      rawStatus === "blocked" ||
+      rawStatus === "done" ||
+      rawStatus === "unknown"
+    ? rawStatus
+    : "unknown";
+  return { kind: "present", ...(agent ? { agent } : {}), agentStatus };
+}
+
+function parsePaneGetError(error: any): PaneInspectionResult {
+  for (const raw of [error?.stderr, error?.stdout]) {
+    if (typeof raw !== "string" || !raw.trim()) continue;
+    try {
+      const parsed = parsePaneGetOutput(raw, "");
+      if (parsed.kind === "missing") return parsed;
+    } catch {
+      // A CLI may emit plain diagnostics on one stream and structured JSON on
+      // the other. Parse each stream independently before giving up.
+    }
+    // Older/alternate Herdr builds may print the stable error code as plain
+    // text rather than JSON. Only match explicit identifiers, not generic
+    // prose such as "pane unavailable".
+    if (/\b(?:pane_not_found|not_found)\b/.test(raw)) {
+      return { kind: "missing", error: raw.trim() };
+    }
+  }
+  const message = error?.message ? String(error.message) : "herdr pane get failed";
+  return { kind: "unavailable", error: message };
+}
+
+/**
+ * Structured pane query.
+ * - present: pane is reachable; agent/agentStatus may be present when detected
+ * - missing: server responded, pane is gone
+ * - unavailable: server command failed; caller should keep polling
+ */
+export async function inspectHerdrPane(surface: string): Promise<PaneInspectionResult> {
+  try {
+    return parsePaneGetOutput(await herdrExecAsync(["pane", "get", surface]), surface);
+  } catch (error: any) {
+    return parsePaneGetError(error);
+  }
+}
+
 export function sendHerdrCommand(surface: string, command: string): void {
   // pane run sends the text and Enter in a single socket request, avoiding
   // a race where Enter could arrive before the text is fully processed.
@@ -197,4 +263,6 @@ export const __herdrTest__ = {
   parseHerdrJson,
   extractHerdrPaneId,
   extractHerdrRootPaneId,
+  parsePaneGetOutput,
+  parsePaneGetError,
 };