@nklisch/pi-enhanced 0.2.7 → 0.3.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/workspace.ts

@@ -11,7 +11,7 @@
  * synchronously at run-start. The core has no knowledge of git or worktrees.
  */
 
-import type { SubagentStatus } from "#src/lifecycle/subagent";
+import type { SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { AgentInvocation, SubagentType } from "#src/types";
 
 /** Context the core hands a provider when a child run starts. */

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/observation/notification.ts

@@ -1,14 +1,17 @@
 import { debugLog } from "#src/debug";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
-import type { Subagent } from "#src/types";
+import type { Subagent } from "#src/lifecycle/subagent";
+import type { SubagentTerminalReason } from "#src/lifecycle/subagent-state";
 
-/** Details attached to custom notification messages for visual rendering. */
 export interface NotificationDetails {
   id: string;
   description: string;
+  runId: number;
+  mode: string;
   modelLabel: string;
   thinkingLevel: Subagent["effectiveThinkingLevel"];
   status: string;
+  terminalReason?: SubagentTerminalReason;
   toolUses: number;
   turnCount: number;
   maxTurns?: number;
@@ -19,170 +22,129 @@ export interface NotificationDetails {
   resultPreview: string;
 }
 
-// ---- Pure helpers (exported for unit testing) ----
-
-/** Escape XML text and attribute delimiters in structured notifications. */
 export function escapeXml(s: string): string {
-  return s
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 
-/** Human-readable status label for agent completion. */
-export function getStatusLabel(status: string, error?: string): string {
-  switch (status) {
-    case "error":
-      return `Error: ${error ?? "unknown"}`;
-    case "aborted":
-      return "Aborted (max turns exceeded)";
-    case "steered":
-      return "Wrapped up (turn limit)";
-    case "stopped":
-      return "Stopped";
-    default:
-      return "Done";
-  }
+export function getStatusLabel(status: string, reason?: SubagentTerminalReason, error?: string): string {
+  if (status === "error") return `Error: ${error ?? "unknown"}`;
+  if (reason === "turn_limit_graceful") return "Completed (turn limit)";
+  if (reason === "turn_limit_hard") return "Stopped (turn limit)";
+  if (status === "stopped") return reason ? `Stopped (${reason.replaceAll("_", " ")})` : "Stopped";
+  return "Done";
 }
 
-/** Format a structured <task-notification> XML block for the parent agent to parse. */
 export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
-  const status = getStatusLabel(record.status, record.error);
-  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
-  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = record.getContextPercent();
-  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
-  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
-
-  const resultPreview = record.stoppedWhileQueued
-    ? "Agent was stopped while queued and never started. No work was performed."
-    : record.result
-    ? record.result.length > resultMaxLen
-      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
-      : record.result
+  const status = getStatusLabel(record.status, record.stateTerminalReason, record.error);
+  const resultPreview = record.result
+    ? record.result.length > resultMaxLen ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)" : record.result
     : "No output.";
-
-  const toolCallId = record.toolCallId;
   const outputFile = record.outputFile;
   return [
     "<task-notification>",
     `<task-id>${record.id}</task-id>`,
-    toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
-    outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
+    `<run-id>${record.runId}</run-id>`,
+    `<mode>${record.mode}</mode>`,
     `<status>${escapeXml(status)}</status>`,
+    record.stateTerminalReason ? `<terminal-reason>${record.stateTerminalReason}</terminal-reason>` : null,
     `<model>${escapeXml(record.modelLabel)}</model>`,
     `<thinking_level>${escapeXml(record.effectiveThinkingLevel)}</thinking_level>`,
-    `<summary>Subagent "${escapeXml(record.description)}" ${record.status}</summary>`,
+    `<summary>Subagent "${escapeXml(record.description)}" ${escapeXml(record.status)}</summary>`,
     `<result>${escapeXml(resultPreview)}</result>`,
-    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
+    `<usage><total_tokens>${getLifetimeTotal(record.lifetimeUsage)}</total_tokens><tool_uses>${record.toolUses}</tool_uses><duration_ms>${record.activeRuntimeMs}</duration_ms></usage>`,
+    outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
     "</task-notification>",
-  ]
-    .filter(Boolean)
-    .join("\n");
+  ].filter((line): line is string => line !== null).join("\n");
 }
 
-/** Build notification details for the custom message renderer. */
-export function buildNotificationDetails(
-  record: Subagent,
-  resultMaxLen: number,
-): NotificationDetails {
-  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-
+export function buildNotificationDetails(record: Subagent, resultMaxLen: number): NotificationDetails {
   return {
     id: record.id,
     description: record.description,
+    runId: record.runId,
+    mode: record.mode,
     modelLabel: record.modelLabel,
     thinkingLevel: record.effectiveThinkingLevel,
     status: record.status,
+    terminalReason: record.stateTerminalReason,
     toolUses: record.toolUses,
     turnCount: record.turnCount,
     maxTurns: record.maxTurns,
-    totalTokens,
-    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    totalTokens: getLifetimeTotal(record.lifetimeUsage),
+    durationMs: record.activeRuntimeMs,
     outputFile: record.outputFile,
     error: record.error,
-    resultPreview: record.stoppedWhileQueued
-      ? "Agent was stopped while queued and never started. No work was performed."
-      : record.result
-      ? record.result.length > resultMaxLen
-        ? record.result.slice(0, resultMaxLen) + "…"
-        : record.result
-      : "No output.",
+    resultPreview: record.result ? record.result.slice(0, resultMaxLen) : "No output.",
   };
 }
 
-/** Build event data for lifecycle events from a Subagent. */
 export function buildEventData(record: Subagent) {
-  const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
-  const u = record.lifetimeUsage;
-  const total = getLifetimeTotal(u);
-  const tokens =
-    total > 0
-      ? { input: u.input, output: u.output, total }
-      : undefined;
+  const usage = record.lifetimeUsage;
+  const total = getLifetimeTotal(usage);
   return {
     id: record.id,
+    runId: record.runId,
+    mode: record.mode,
     type: record.type,
     description: record.description,
     result: record.result,
     error: record.error,
     status: record.status,
+    terminalReason: record.stateTerminalReason,
+    modelLabel: record.modelLabel,
+    thinkingLevel: record.effectiveThinkingLevel,
     toolUses: record.toolUses,
-    durationMs,
-    tokens,
+    activeRuntimeMs: record.activeRuntimeMs,
+    tokens: total > 0 ? { input: usage.input, output: usage.output, total } : undefined,
   };
 }
 
-// ---- Notification system factory ----
-
 export interface NotificationSystem {
-  sendCompletion: (record: Subagent) => void;
-  dispose: () => void;
+  sendCompletion(record: Subagent): void;
+  dispose(): void;
 }
 
 export class NotificationManager implements NotificationSystem {
-  // Pi cannot recall a queued followUp. Hold records while the parent run is
-  // active so consumption can be rechecked at the actual delivery boundary.
-  private pendingNudges = new Map<string, Subagent>();
+  private readonly pendingNudges = new Map<string, { record: Subagent; runId: number; content: string; details: NotificationDetails }>();
   private parentRunActive = false;
   private disposed = false;
 
-  constructor(
-    private sendMessage: (
-      msg: { customType: string; content: string; display: boolean; details?: unknown },
-      opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
-    ) => void,
-  ) {}
+  constructor(private readonly sendMessage: (msg: { customType: string; content: string; display: boolean; details?: unknown }, opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }) => void) {}
 
   sendCompletion(record: Subagent): void {
-    // A blocking get-result request has already selected direct delivery for
-    // this terminal outcome. Never enqueue the same payload as a follow-up,
-    // even if Pi's parent lifecycle currently appears idle.
-    if (this.disposed || record.consumed || record.hasPendingResultWait) return;
+    if (this.disposed || record.mode !== "detached" || record.consumed) return;
     if (this.parentRunActive) {
-      this.pendingNudges.set(record.id, record);
-      return;
-    }
-    this.emitIndividualNudge(record);
+      this.pendingNudges.set(`${record.id}:${record.runId}`, {
+        record,
+        runId: record.runId,
+        content: formatTaskNotification(record, 500),
+        details: buildNotificationDetails(record, 500),
+      });
+    } else this.emitIndividualNudge(record);
   }
 
-  onParentAgentStart(): void {
-    if (!this.disposed) this.parentRunActive = true;
-  }
+  onParentAgentStart(): void { if (!this.disposed) this.parentRunActive = true; }
 
   onParentAgentSettled(): void {
     if (this.disposed) return;
     this.parentRunActive = false;
-    const withheld = [...this.pendingNudges.values()];
+    const pending = [...this.pendingNudges.values()];
     this.pendingNudges.clear();
-    for (const record of withheld) {
+    for (const nudge of pending) {
       try {
-        this.emitIndividualNudge(record);
-      } catch (err) {
-        debugLog("notification render", err);
-      }
+        // A resume may advance the record while the parent is running. The
+        // queued notification describes the old run and must not wake the
+        // parent after that run has been superseded (or after delivery mode
+        // changed to joined).
+        if (
+          nudge.runId === nudge.record.runId &&
+          nudge.record.mode === "detached" &&
+          !nudge.record.isActive() &&
+          !nudge.record.consumed
+        ) {
+          this.emitNudge(nudge.record, nudge.content, nudge.details);
+        }
+      } catch (error) { debugLog("notification render", error); }
     }
   }
 
@@ -192,24 +154,18 @@ export class NotificationManager implements NotificationSystem {
   }
 
   private emitIndividualNudge(record: Subagent): void {
-    if (this.disposed || record.consumed) return;
-
-    const notification = formatTaskNotification(record, 500);
-    const outputFile = record.outputFile;
-    const footer = !record.stoppedWhileQueued && outputFile
-      ? `\nFull transcript available at: ${outputFile}`
-      : "";
+    if (this.disposed || record.consumed || record.mode !== "detached") return;
+    this.emitNudge(record, formatTaskNotification(record, 500), buildNotificationDetails(record, 500));
+  }
 
-    this.sendMessage(
-      {
-        customType: "subagent-notification",
-        content: notification + footer,
-        display: true,
-        details: buildNotificationDetails(record, 500),
-      },
-      { deliverAs: "followUp", triggerTurn: true },
-    );
-    // Push delivery collected the terminal outcome just as surely as a pull.
-    record.markConsumed();
+  private emitNudge(record: Subagent, notification: string, details: NotificationDetails, markConsumed = true): void {
+    const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : "";
+    this.sendMessage({
+      customType: "subagent-notification",
+      content: notification + footer,
+      display: true,
+      details,
+    }, { deliverAs: "followUp", triggerTurn: true });
+    if (markConsumed) record.markConsumed();
   }
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/observation/renderer.ts

@@ -2,66 +2,39 @@ import { Text } from "@earendil-works/pi-tui";
 import type { NotificationDetails } from "#src/observation/notification";
 import { formatModelThinking, formatMs, formatTokens, formatTurns } from "#src/ui/display";
 
-/** Narrow theme interface — only the methods the renderer actually calls. */
 interface RendererTheme {
   fg(style: string, text: string): string;
   bold(text: string): string;
 }
+interface RendererMessage { details?: NotificationDetails; }
+interface RenderOptions { expanded: boolean; }
 
-/** Narrow message interface — only the fields the renderer reads. */
-interface RendererMessage {
-  details?: NotificationDetails;
-}
-
-/** Narrow render options — only the fields the renderer reads. */
-interface RenderOptions {
-  expanded: boolean;
-}
-
-/**
- * Create the notification renderer callback for `pi.registerMessageRenderer`.
- * Returns a factory so the renderer is independently testable without the Pi SDK.
- */
 export function createNotificationRenderer() {
   return (message: RendererMessage, { expanded }: RenderOptions, theme: RendererTheme): Text | undefined => {
     const d = message.details;
     if (!d) return undefined;
-
-    const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
-    const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
-    const statusText = isError
-      ? d.status
-      : d.status === "steered"
-        ? "completed (steered)"
-        : "completed";
-
-    // Line 1: icon + agent description + status
+    const stopped = d.status === "stopped" || d.status === "error";
+    const icon = stopped ? theme.fg("error", "✗") : theme.fg("success", "✓");
+    const statusText = d.status === "error"
+      ? `Error: ${d.error ?? "unknown"}`
+      : d.terminalReason === "turn_limit_graceful"
+        ? "completed (turn limit)"
+        : d.status === "stopped" && d.terminalReason
+          ? `stopped (${d.terminalReason})`
+          : d.status;
     let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
-
-    // Line 2: stats
     const parts: string[] = [formatModelThinking(d.modelLabel, d.thinkingLevel)];
     if (d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
     if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
     if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
     if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
-    if (parts.length) {
-      line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
-    }
-
-    // Line 3: result preview (collapsed) or full (expanded)
+    line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
     if (expanded) {
-      const lines = d.resultPreview.split("\n").slice(0, 30);
-      for (const l of lines) line += "\n" + theme.fg("dim", `  ${l}`);
+      for (const item of d.resultPreview.split("\n").slice(0, 30)) line += "\n" + theme.fg("dim", `  ${item}`);
     } else {
-      const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
-      line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
+      line += "\n  " + theme.fg("dim", `⎿  ${d.resultPreview.split("\n")[0]?.slice(0, 80) ?? ""}`);
     }
-
-    // Line 4: output file link (if present)
-    if (d.outputFile) {
-      line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
-    }
-
+    if (d.outputFile) line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
     return new Text(line, 0, 0);
   };
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/observation/subagent-events-observer.ts

@@ -3,106 +3,55 @@ import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
 import { buildEventData, type NotificationSystem } from "#src/observation/notification";
 import type { CompactionInfo, Subagent } from "#src/types";
 
-/** Emit callback — a subset of `pi.events.emit`. */
 export type EventEmit = (channel: string, data: unknown) => void;
-
-/** Append callback — a subset of `pi.appendEntry`. */
 export type AppendEntry = (customType: string, data: unknown) => void;
 
 export interface SubagentEventsObserverDeps {
-	emit: EventEmit;
-	appendEntry: AppendEntry;
-	notifications: NotificationSystem;
+  emit: EventEmit;
+  appendEntry: AppendEntry;
+  notifications: NotificationSystem;
 }
 
-/**
- * Receives agent lifecycle notifications from SubagentManager and dispatches
- * them to three concerns: pi.events lifecycle events, session-entry persistence,
- * and completion notifications.
- *
- * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
- * three concerns are unit-testable without booting the extension.
- */
 export class SubagentEventsObserver implements SubagentManagerObserver {
-	private readonly emit: EventEmit;
-	private readonly appendEntry: AppendEntry;
-	private readonly notifications: NotificationSystem;
-
-	constructor(deps: SubagentEventsObserverDeps) {
-		this.emit = deps.emit;
-		this.appendEntry = deps.appendEntry;
-		this.notifications = deps.notifications;
-	}
-
-	onSubagentStarted(record: Subagent): void {
-		// Emit started event when agent transitions to running (including from queue).
-		runSafely("subagent event emission started", () => this.emit("subagents:started", {
-			id: record.id,
-			type: record.type,
-			description: record.description,
-		}));
-	}
-
-	onSubagentCompleted(record: Subagent): void {
-		// Emit lifecycle event based on terminal status.
-		const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-		const eventData = buildEventData(record);
-		if (isError) {
-			runSafely("subagent event emission failed", () => this.emit("subagents:failed", eventData));
-		} else {
-			runSafely("subagent event emission completed", () => this.emit("subagents:completed", eventData));
-		}
-
-		// Persist final record for cross-extension history reconstruction.
-		runSafely("subagent record append", () => this.appendEntry("subagents:record", {
-			id: record.id,
-			type: record.type,
-			description: record.description,
-			status: record.status,
-			result: record.result,
-			error: record.error,
-			startedAt: record.startedAt,
-			completedAt: record.completedAt,
-		}));
-
-		// The manager decides whether to nudge (it owns the consumed-result state).
-		runSafely("subagent completion notification", () => this.notifications.sendCompletion(record));
-	}
-
-	onSubagentResumed(record: Subagent): void {
-		const eventData = buildEventData(record);
-		runSafely("subagent event emission resumed", () => this.emit("subagents:resumed", eventData));
-		runSafely("subagent record append resumed", () => this.appendEntry("subagents:record", {
-			id: record.id,
-			type: record.type,
-			description: record.description,
-			status: record.status,
-			result: record.result,
-			error: record.error,
-			startedAt: record.startedAt,
-			completedAt: record.completedAt,
-		}));
-	}
-
-	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
-		// Emit compacted event when agent's session compacts (preserves count on record).
-		runSafely("subagent event emission compacted", () => this.emit("subagents:compacted", {
-			id: record.id,
-			type: record.type,
-			description: record.description,
-			reason: info.reason,
-			tokensBefore: info.tokensBefore,
-			compactionCount: record.compactionCount,
-		}));
-	}
-
-	onSubagentCreated(record: Subagent): void {
-		// Emit created event for background agents (before limiter admission).
-		runSafely("subagent event emission created", () => this.emit("subagents:created", {
-			id: record.id,
-			type: record.type,
-			description: record.description,
-			isBackground: true,
-		}));
-	}
+  constructor(private readonly deps: SubagentEventsObserverDeps) {}
+
+  onSubagentStarted(record: Subagent): void {
+    runSafely("subagent event emission started", () => this.deps.emit("subagents:started", {
+      id: record.id, runId: record.runId, mode: record.mode, type: record.type, description: record.description,
+    }));
+  }
+
+  onSubagentCompleted(record: Subagent): void {
+    const eventData = buildEventData(record);
+    const channel = record.status === "error" || record.status === "stopped" ? "subagents:failed" : "subagents:completed";
+    runSafely("subagent event emission terminal", () => this.deps.emit(channel, eventData));
+    runSafely("subagent record append", () => this.deps.appendEntry("subagents:record", eventData));
+    runSafely("subagent completion notification", () => this.deps.notifications.sendCompletion(record));
+  }
+
+  onSubagentResumedStarted(record: Subagent): void {
+    runSafely("subagent event emission resumed-started", () => this.deps.emit("subagents:started", {
+      id: record.id, runId: record.runId, mode: record.mode, type: record.type, description: record.description, resumed: true,
+    }));
+  }
+
+  onSubagentResumed(record: Subagent): void {
+    const eventData = buildEventData(record);
+    runSafely("subagent event emission resumed", () => this.deps.emit("subagents:resumed", eventData));
+    runSafely("subagent record append resumed", () => this.deps.appendEntry("subagents:record", eventData));
+    runSafely("subagent resumed notification", () => this.deps.notifications.sendCompletion(record));
+  }
+
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+    runSafely("subagent event emission compacted", () => this.deps.emit("subagents:compacted", {
+      id: record.id, runId: record.runId, mode: record.mode, type: record.type, description: record.description,
+      reason: info.reason, tokensBefore: info.tokensBefore, compactionCount: record.compactionCount,
+    }));
+  }
+
+  onSubagentCreated(record: Subagent): void {
+    runSafely("subagent event emission created", () => this.deps.emit("subagents:created", {
+      id: record.id, runId: record.runId, mode: record.mode, type: record.type, description: record.description,
+    }));
+  }
 }