@nklisch/pi-enhanced 0.2.7 → 0.3.1

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/ui/agent-widget.ts

@@ -87,14 +87,14 @@ export class AgentWidget implements SubagentManagerObserver {
   private widgetFrame = 0;
   private widgetInterval: ReturnType<typeof setInterval> | undefined;
   /**
-   * Bounded reactive read model: lifecycle callbacks add active background
+   * Bounded reactive read model: lifecycle callbacks add active detached
    * records and the small terminal linger set; render ticks never ask the
    * manager to clone or sort its retained history.
    */
-  private readonly backgroundAgents = new Map<string, Subagent>();
+  private readonly detachedAgents = new Map<string, Subagent>();
   /** Tracks how many turns each finished agent has survived. */
   private finishedTurnAge = new Map<string, number>();
-  /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+  /** How many extra turns errors/stopped agents linger (completed agents clear after 1 turn). */
   private static readonly ERROR_LINGER_TURNS = 2;
   /** Pi renders the whole component tree for each requestRender call. */
   private static readonly STATUS_REFRESH_INTERVAL_MS = 500;
@@ -122,7 +122,7 @@ export class AgentWidget implements SubagentManagerObserver {
     // Lifecycle events can arrive before the first tool gives us a UI context.
     // Refresh when that context becomes available, but let update() decide
     // whether any active record actually needs an animation timer.
-    if (contextChanged && this.uiCtx && this.backgroundAgents.size > 0) this.refresh();
+    if (contextChanged && this.uiCtx && this.detachedAgents.size > 0) this.refresh();
   }
 
   /**
@@ -131,13 +131,13 @@ export class AgentWidget implements SubagentManagerObserver {
    */
   onTurnStart() {
     // Age terminal records and remove them before the next render. Completed
-    // records linger for one turn; errors and aborted records linger for two.
+    // records linger for one turn; errors and stopped records linger for two.
     for (const [id, age] of this.finishedTurnAge) {
-      const record = this.backgroundAgents.get(id);
+      const record = this.detachedAgents.get(id);
       const nextAge = age + 1;
       if (!record || nextAge >= this.maxFinishedAge(record.status)) {
         this.finishedTurnAge.delete(id);
-        this.backgroundAgents.delete(id);
+        this.detachedAgents.delete(id);
       } else {
         this.finishedTurnAge.set(id, nextAge);
       }
@@ -149,47 +149,47 @@ export class AgentWidget implements SubagentManagerObserver {
 
   /** A subagent started running — ensure the update loop is live and render. */
   onSubagentStarted(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.delete(record.id);
     this.startLoop();
   }
 
-  /** A background subagent was created (queued) — ensure the loop is live and render. */
+  /** A detached subagent was created (queued) — ensure the loop is live and render. */
   onSubagentCreated(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.delete(record.id);
     this.startLoop();
   }
 
   /** A subagent completed — seed its bounded linger entry and render. */
   onSubagentCompleted(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.set(record.id, 0);
     this.refresh();
   }
 
   /** A resumed subagent started — ensure the update loop is live and render. */
   onSubagentResumedStarted(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.delete(record.id);
     this.startLoop();
   }
 
   /** A resumed subagent settled — seed its terminal linger entry. */
   onSubagentResumed(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.set(record.id, 0);
     this.refresh();
   }
 
   /** A subagent's session compacted — render to refresh the compaction count. */
   onSubagentCompacted(record: Subagent, _info: CompactionInfo) {
-    if (this.trackBackground(record)) this.refresh();
+    if (this.trackDetached(record)) this.refresh();
   }
 
   /** Remove terminal state when the manager clears a parent session. */
   onSubagentCleared(record: Subagent) {
-    if (!this.backgroundAgents.delete(record.id)) return;
+    if (!this.detachedAgents.delete(record.id)) return;
     this.finishedTurnAge.delete(record.id);
     this.refresh();
   }
@@ -226,19 +226,23 @@ export class AgentWidget implements SubagentManagerObserver {
     return ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
   }
 
-  /** Add a record only when its immutable invocation snapshot marks it background. */
-  private trackBackground(record: Subagent): boolean {
-    if (record.invocation?.runInBackground !== true) return false;
-    this.backgroundAgents.set(record.id, record);
+  /** Add a record only when its current run mode is detached. */
+  private trackDetached(record: Subagent): boolean {
+    if (record.mode !== "detached") {
+      this.detachedAgents.delete(record.id);
+      this.finishedTurnAge.delete(record.id);
+      return false;
+    }
+    this.detachedAgents.set(record.id, record);
     return true;
   }
 
   /** Drop terminal entries whose turn-based linger window has already elapsed. */
   private pruneExpiredFinished(): void {
-    for (const [id, record] of this.backgroundAgents) {
+    for (const [id, record] of this.detachedAgents) {
       if (record.isActive()) continue;
       if (record.completedAt == null || !this.shouldShowFinished(id, record.status)) {
-        this.backgroundAgents.delete(id);
+        this.detachedAgents.delete(id);
         this.finishedTurnAge.delete(id);
       }
     }
@@ -250,12 +254,14 @@ export class AgentWidget implements SubagentManagerObserver {
       id: record.id,
       type: record.type,
       status: record.status,
+      terminalReason: record.stateTerminalReason,
       description: record.description,
       modelLabel: record.modelLabel,
       thinkingLevel: record.effectiveThinkingLevel,
       toolUses: record.toolUses,
       startedAt: record.startedAt,
       completedAt: record.completedAt,
+      activeRuntimeMs: record.activeRuntimeMs,
       error: record.error,
       lifetimeUsage: record.lifetimeUsage,
       compactionCount: record.compactionCount,
@@ -270,7 +276,7 @@ export class AgentWidget implements SubagentManagerObserver {
   /** Delegate rendering to the pure widget-renderer module. */
   private renderWidget(tui: any, theme: Theme): string[] {
     return renderWidgetLines({
-      agents: [...this.backgroundAgents.values()].map(r => this.toWidgetAgent(r)),
+      agents: [...this.detachedAgents.values()].map(r => this.toWidgetAgent(r)),
       registry: this.registry,
       spinnerFrame: this.widgetFrame,
       terminalWidth: tui.terminal.columns,
@@ -295,7 +301,7 @@ export class AgentWidget implements SubagentManagerObserver {
       this.lastStatusText = undefined;
     }
     this.stopTimer();
-    this.backgroundAgents.clear();
+    this.detachedAgents.clear();
     this.finishedTurnAge.clear();
   }
 
@@ -316,8 +322,8 @@ export class AgentWidget implements SubagentManagerObserver {
     if (!this.uiCtx) return;
 
     this.pruneExpiredFinished();
-    const backgroundAgents = [...this.backgroundAgents.values()];
-    const state = assembleWidgetState(backgroundAgents, (id, status) => this.shouldShowFinished(id, status));
+    const detachedAgents = [...this.detachedAgents.values()];
+    const state = assembleWidgetState(detachedAgents, (id, status) => this.shouldShowFinished(id, status));
 
     if (!state.hasActive && !state.hasFinished) {
       this.clearWidget();
@@ -329,7 +335,7 @@ export class AgentWidget implements SubagentManagerObserver {
     // static completion widget remains registered.
     if (state.hasActive) this.ensureTimer();
     else this.stopTimer();
-    this.updateStatusBar(state, backgroundAgents);
+    this.updateStatusBar(state, detachedAgents);
     this.widgetFrame++;
 
     // Register widget callback once; subsequent updates use requestRender()
@@ -387,7 +393,7 @@ export class AgentWidget implements SubagentManagerObserver {
     this.widgetRegistered = false;
     this.tui = undefined;
     this.lastStatusText = undefined;
-    this.backgroundAgents.clear();
+    this.detachedAgents.clear();
     this.finishedTurnAge.clear();
   }
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/ui/display.ts

@@ -7,6 +7,7 @@
 
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import { GLYPHS } from "#src/ui/glyphs";
+import type { SubagentTerminalReason } from "#src/lifecycle/subagent-state";
 import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
 
 // ---- Types ----
@@ -24,7 +25,8 @@ export interface AgentDetails {
   toolUses: number;
   tokens: string;
   durationMs: number;
-  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+  status: "queued" | "running" | "completed" | "stopped" | "error";
+  terminalReason?: SubagentTerminalReason;
   /** Human-readable description of what the agent is currently doing. */
   activity?: string;
   /** Current spinner frame index (for animated running indicator). */
@@ -49,7 +51,7 @@ export interface AgentDetails {
 export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 /** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
-export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+export const ERROR_STATUSES = new Set(["error", "stopped"]);
 
 /** Tool name → human-readable action for activity descriptions. */
 const TOOL_DISPLAY: Record<string, string> = {
@@ -146,8 +148,9 @@ export function buildInvocationTags(
   if (!invocation) return { tags };
   if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
   if (invocation.inheritContext) tags.push("inherit context");
-  if (invocation.runInBackground) tags.push("background");
+  if (invocation.mode) tags.push(`mode: ${invocation.mode}`);
   if (invocation.maxTurns != null) tags.push(`max turns: ${invocation.maxTurns}`);
+  if (invocation.timeoutSeconds != null) tags.push(`timeout: ${invocation.timeoutSeconds}s`);
   return { modelName: invocation.modelName, tags };
 }
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/ui/session-navigation.ts

@@ -3,20 +3,22 @@
  *
  * Splits the unit-testable core of the `/subagents:sessions` command from its TUI
  * wiring (`session-navigator.ts`): which subagents are navigable and how a picked
- * agent's transcript is sourced (live, in this slice).
+ * agent's transcript is sourced (live or a retained file snapshot).
  *
  * The `TranscriptSource` seam decouples *how messages are sourced* (live record
- * here; a file snapshot in a follow-up) from *how they render* — the renderer
+ * or a retained file snapshot) from *how they render* — the renderer
  * (`session-navigator.ts`, which mounts Pi's per-entry components) talks only to
  * this seam. Rendering lives in the SDK/TUI module because the per-entry
- * components require a `TUI`, `cwd`, and markdown theme.
+ * components require a `TUI`, `cwd`, and markdown theme. The query tool uses
+ * the same JSONL adapter so file and live reads cannot drift.
  */
 
-import { buildSessionContext, parseSessionEntries, type SessionEntry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import type { SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { AgentSessionEvent, SessionMessage, SubagentType, ThinkingLevel } from "#src/types";
 import { formatDuration, formatModelThinking, getDisplayName } from "#src/ui/display";
+import { parseSessionFileMessages } from "#src/session/query-source";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -37,14 +39,17 @@ export interface NavigableSubagent {
   readonly agentMessages: readonly SessionMessage[];
   isSessionReady(): boolean;
   subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+  /** Notifies consumers when a retained session is released and changes source. */
+  subscribeToRecordUpdates?: (fn: () => void) => () => void;
   getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
 /**
  * A navigable entry plus the label shown in the picker.
  *
- * A `live` entry sources its transcript from the in-memory session; an
- * `evicted`-kind entry is a persisted snapshot for a released live session.
+ * A `live` entry sources its transcript from the in-memory session and can
+ * transition to its retained file; an `evicted`-kind entry is a persisted
+ * snapshot for a released live session.
  */
 export interface RunDisplayMetadata {
   readonly modelLabel: string;
@@ -75,6 +80,12 @@ export interface StreamingState {
   readonly responseText: string;
 }
 
+/** Source state shown when a live record is released or its snapshot cannot load. */
+export type TranscriptSourceAvailability =
+  | { readonly kind: "live"; readonly path?: string }
+  | { readonly kind: "file"; readonly path: string }
+  | { readonly kind: "unavailable"; readonly path?: string; readonly error?: string };
+
 /** Liveness-agnostic transcript source consumed by the renderer. */
 export interface TranscriptSource {
   /** Current message history. */
@@ -85,6 +96,8 @@ export interface TranscriptSource {
   streaming(): StreamingState | undefined;
   /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
   getToolDefinition(name: string): ToolDefinition | undefined;
+  /** Current source state; unavailable retains the last readable messages. */
+  availability?(): TranscriptSourceAvailability;
 }
 
 /**
@@ -126,18 +139,17 @@ export function fileSnapshotSource(
   outputFile: string,
   readFile: (path: string) => string,
 ): TranscriptSource {
-  const entries = parseSessionEntries(readFile(outputFile));
-  const sessionEntries = entries.filter((entry): entry is SessionEntry => entry.type !== "session");
-  const { messages } = buildSessionContext(sessionEntries);
+  const messages = parseSessionFileMessages(readFile(outputFile));
   return {
     getMessages: () => messages,
     subscribe: () => undefined,
     streaming: () => undefined,
     getToolDefinition: () => undefined,
+    availability: () => ({ kind: "file", path: outputFile }),
   };
 }
 
-/** Source a transcript live from an in-memory record (this slice's only source). */
+/** Source a transcript live from an in-memory record. */
 export function liveSource(record: NavigableSubagent): TranscriptSource {
   return {
     getMessages: () => record.agentMessages,
@@ -147,6 +159,105 @@ export function liveSource(record: NavigableSubagent): TranscriptSource {
         ? { activeTools: record.activeTools, responseText: record.responseText }
         : undefined,
     getToolDefinition: (name) => record.getToolDefinition(name),
+    availability: () => ({ kind: "live", ...(record.outputFile ? { path: record.outputFile } : {}) }),
+  };
+}
+
+/**
+ * Keep a live viewer useful across retention release. The source swaps to the
+ * persisted snapshot on the release notification and retains the last live
+ * content when that snapshot cannot be read.
+ */
+export function liveFileSource(
+  record: NavigableSubagent,
+  readFile: (path: string) => string,
+): TranscriptSource {
+  let mode: "live" | "file" | "unavailable" = record.isSessionReady() ? "live" : "unavailable";
+  let messages: readonly SessionMessage[] = record.agentMessages;
+  let error: string | undefined;
+  let fileAttempted = false;
+
+  const swapIfReleased = (): void => {
+    if (record.isSessionReady()) {
+      mode = "live";
+      error = undefined;
+      messages = record.agentMessages;
+      return;
+    }
+    if (fileAttempted || !record.outputFile) {
+      if (!record.outputFile && mode === "live") mode = "unavailable";
+      return;
+    }
+    fileAttempted = true;
+    try {
+      messages = parseSessionFileMessages(readFile(record.outputFile));
+      mode = "file";
+      error = undefined;
+    } catch (cause) {
+      mode = "unavailable";
+      error = cause instanceof Error ? cause.message : String(cause);
+    }
+  };
+
+  const notify = (onChange: () => void): void => {
+    try {
+      // Do not replace the last live snapshot with Subagent's empty post-release
+      // getter before the file adapter succeeds; the degraded path must retain
+      // content that was already visible.
+      if (mode === "live" && record.isSessionReady()) messages = record.agentMessages;
+      swapIfReleased();
+      onChange();
+    } catch (cause) {
+      mode = "unavailable";
+      error = cause instanceof Error ? cause.message : String(cause);
+      onChange();
+    }
+  };
+
+  return {
+    getMessages: () => {
+      try {
+        if (mode === "live") {
+          if (!record.isSessionReady()) swapIfReleased();
+          else messages = record.agentMessages;
+        } else swapIfReleased();
+      } catch (cause) {
+        mode = "unavailable";
+        error = cause instanceof Error ? cause.message : String(cause);
+      }
+      return messages;
+    },
+    subscribe: (onChange) => {
+      const unsubscribers: Array<() => void> = [];
+      try {
+        const unsubscribe = record.subscribeToUpdates(() => notify(onChange));
+        if (unsubscribe) unsubscribers.push(unsubscribe);
+      } catch (cause) {
+        mode = "unavailable";
+        error = cause instanceof Error ? cause.message : String(cause);
+      }
+      if (record.subscribeToRecordUpdates) {
+        try {
+          unsubscribers.push(record.subscribeToRecordUpdates(() => notify(onChange)));
+        } catch (cause) {
+          mode = "unavailable";
+          error = cause instanceof Error ? cause.message : String(cause);
+        }
+      }
+      return unsubscribers.length === 0 ? undefined : () => {
+        for (const unsubscribe of unsubscribers) unsubscribe();
+      };
+    },
+    streaming: () => mode === "live" && record.status === "running"
+      ? { activeTools: record.activeTools, responseText: record.responseText }
+      : undefined,
+    getToolDefinition: (name) => mode === "live" ? record.getToolDefinition(name) : undefined,
+    availability: () => {
+      swapIfReleased();
+      if (mode === "live") return { kind: "live", ...(record.outputFile ? { path: record.outputFile } : {}) };
+      if (mode === "file" && record.outputFile) return { kind: "file", path: record.outputFile };
+      return { kind: "unavailable", ...(record.outputFile ? { path: record.outputFile } : {}), ...(error ? { error } : {}) };
+    },
   };
 }