@gotgenes/pi-subagents 17.1.0 → 17.3.0

package/src/lifecycle/subagent.ts

@@ -20,7 +20,7 @@ import { WorkspaceBracket } from "#src/lifecycle/workspace-bracket";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SessionMessage, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Per-subagent lifecycle observer — created by SubagentManager for each spawn. */
 export interface SubagentLifecycleObserver {
@@ -162,6 +162,11 @@ export class Subagent {
 		return this.subagentSession?.messages ?? [];
 	}
 
+	/** The session's message history typed for Pi's session-rendering machinery, or empty if no session. */
+	get agentMessages(): readonly SessionMessage[] {
+		return this.subagentSession?.agentMessages ?? [];
+	}
+
 	constructor(init: SubagentInit) {
 		// Identity
 		this.id = init.id;

package/src/types.ts

@@ -3,13 +3,22 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent, SessionContext as SdkSessionContext } from "@earendil-works/pi-coding-agent";
 import type { ModelRegistry } from "#src/session/model-resolver";
 
 
 export { Subagent } from "#src/lifecycle/subagent";
 export type { AgentSessionEvent, ThinkingLevel };
 
+/**
+ * One message in a child session's history, typed from Pi's `SessionContext`.
+ *
+ * Derived from the barrel-exported `SessionContext` (whose `messages` field is
+ * `AgentMessage[]`) so the package needs no direct dependency on
+ * `@earendil-works/pi-agent-core`, which is not re-exported from the public barrel.
+ */
+export type SessionMessage = SdkSessionContext["messages"][number];
+
 /**
  * Narrow session interface for event subscription.
  * Used by record-observer — only the subscribe method is needed.

package/src/ui/agent-widget.ts

@@ -148,6 +148,16 @@ export class AgentWidget implements SubagentManagerObserver {
     return age < maxAge;
   }
 
+  /**
+   * Background agents only — the widget's sole audience (ADR-0004 Decision A).
+   * Foreground runs are rendered by the `subagent` tool's inline `onUpdate` stream,
+   * so funneling both `listAgents()` call sites through this accessor applies the
+   * background predicate exactly once at the source.
+   */
+  private listBackgroundAgents(): Subagent[] {
+    return this.manager.listAgents().filter(record => record.invocation?.runInBackground === true);
+  }
+
   /** Project a live Subagent record onto a pure-data WidgetAgent snapshot. */
   private toWidgetAgent(record: Subagent): WidgetAgent {
     return {
@@ -172,7 +182,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.manager.listAgents().map(r => this.toWidgetAgent(r)),
+      agents: this.listBackgroundAgents().map(r => this.toWidgetAgent(r)),
       registry: this.registry,
       spinnerFrame: this.widgetFrame,
       terminalWidth: tui.terminal.columns,
@@ -183,10 +193,10 @@ export class AgentWidget implements SubagentManagerObserver {
 
   /**
    * Unregister the widget, clear the status bar, stop the interval timer, and
-   * purge stale `finishedTurnAge` entries for agents no longer in `allAgents`.
+   * purge stale `finishedTurnAge` entries for agents no longer in `backgroundAgents`.
    * Called only from `update`'s idle path — not from `dispose`.
    */
-  private clearWidget(allAgents: readonly AgentSummary[]): void {
+  private clearWidget(backgroundAgents: readonly AgentSummary[]): void {
     if (this.widgetRegistered) {
       this.uiCtx!.setWidget("agents", undefined);
       this.widgetRegistered = false;
@@ -198,7 +208,7 @@ export class AgentWidget implements SubagentManagerObserver {
     }
     if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
     for (const [id] of this.finishedTurnAge) {
-      if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
+      if (!backgroundAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
     }
   }
 
@@ -240,12 +250,12 @@ export class AgentWidget implements SubagentManagerObserver {
   update() {
     if (!this.uiCtx) return;
 
-    const allAgents = this.manager.listAgents();
-    this.seedFinishedAgents(allAgents);
-    const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
+    const backgroundAgents = this.listBackgroundAgents();
+    this.seedFinishedAgents(backgroundAgents);
+    const state = assembleWidgetState(backgroundAgents, (id, status) => this.shouldShowFinished(id, status));
 
     if (!state.hasActive && !state.hasFinished) {
-      this.clearWidget(allAgents);
+      this.clearWidget(backgroundAgents);
       return;
     }
 

package/src/ui/session-navigation.ts

@@ -0,0 +1,114 @@
+/**
+ * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
+ *
+ * Splits the unit-testable core of the `/subagent-sessions` command from its TUI
+ * wiring (`session-navigator.ts`): which subagents are navigable, how a picked
+ * agent's transcript is sourced (live, in this slice), and how the transcript
+ * renders to plain text via Pi's own `serializeConversation`.
+ *
+ * The `TranscriptSource` seam decouples *how messages are sourced* (live record
+ * here; a file snapshot in a follow-up) from *how they render* (text here; Pi's
+ * per-entry components in a follow-up). The renderer talks only to this seam.
+ */
+
+import { serializeConversation } 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 } from "#src/types";
+import { describeActivity, formatDuration, getDisplayName } from "#src/ui/display";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The record fields the navigator reads to label and live-source a transcript. */
+export interface NavigableSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+  readonly agentMessages: readonly SessionMessage[];
+  isSessionReady(): boolean;
+  subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+}
+
+/** A navigable entry: a record plus the label shown in the picker. */
+export interface NavigationEntry {
+  readonly record: NavigableSubagent;
+  readonly label: string;
+}
+
+/** Running-agent streaming state, surfaced by a live source. */
+export interface StreamingState {
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+}
+
+/** Liveness-agnostic transcript source consumed by the renderer. */
+export interface TranscriptSource {
+  /** Current message history. */
+  getMessages(): readonly SessionMessage[];
+  /** Subscribe to changes; returns an unsubscribe, or undefined for a static snapshot. */
+  subscribe(onChange: () => void): (() => void) | undefined;
+  /** Running-agent streaming state, or undefined when not streaming. */
+  streaming(): StreamingState | undefined;
+}
+
+/** Filter the agents to those with a viewable session and label each for the picker. */
+export function listNavigableAgents(
+  agents: readonly NavigableSubagent[],
+  registry: AgentConfigLookup,
+): NavigationEntry[] {
+  return agents
+    .filter((record) => record.isSessionReady())
+    .map((record) => ({ record, label: buildLabel(record, registry) }));
+}
+
+/** Source a transcript live from an in-memory record (this slice's only source). */
+export function liveSource(record: NavigableSubagent): TranscriptSource {
+  return {
+    getMessages: () => record.agentMessages,
+    subscribe: (onChange) => record.subscribeToUpdates(() => onChange()),
+    streaming: () =>
+      record.status === "running"
+        ? { activeTools: record.activeTools, responseText: record.responseText }
+        : undefined,
+  };
+}
+
+/** Render a source's transcript to plain text lines via Pi's `serializeConversation`. */
+export function renderTranscriptLines(source: TranscriptSource): string[] {
+  const messages = source.getMessages();
+  const lines =
+    messages.length === 0 ? ["(no messages yet)"] : serializeConversation(toMessages(messages)).split("\n");
+
+  const streaming = source.streaming();
+  if (streaming) {
+    lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
+  }
+  return lines;
+}
+
+/**
+ * Bridge the session's `AgentMessage[]` to `serializeConversation`'s `Message[]`.
+ *
+ * `AgentMessage` is a superset of `Message` (it adds session-display variants such
+ * as `BashExecutionMessage`); `serializeConversation` renders the shared shape and
+ * best-effort text for the rest. `Message` is not re-exported from the public
+ * `@earendil-works/pi-ai` barrel, so the parameter type is referenced via the
+ * function signature rather than imported by name.
+ */
+function toMessages(
+  messages: readonly SessionMessage[],
+): Parameters<typeof serializeConversation>[0] {
+  return messages as unknown as Parameters<typeof serializeConversation>[0];
+}
+
+function buildLabel(record: NavigableSubagent, registry: AgentConfigLookup): string {
+  const name = getDisplayName(record.type, registry);
+  const duration = formatDuration(record.startedAt, record.completedAt);
+  return `${name} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${duration}`;
+}

package/src/ui/session-navigator.ts

@@ -0,0 +1,237 @@
+/**
+ * session-navigator.ts — The `/subagent-sessions` command: pick a subagent and
+ * read its transcript through Pi's own session-rendering text.
+ *
+ * SDK/TUI consumer half of native session navigation. The unit-testable core
+ * (selection, sourcing, text rendering) lives in `session-navigation.ts`; this
+ * module wires that core to the command picker and a read-only scrollable overlay.
+ *
+ * The overlay is strictly read-only — steering stays in the `steer_subagent` tool
+ * and the widget. It consumes a `TranscriptSource`, so the renderer-upgrade and
+ * evicted-agent-source follow-ups swap the source/renderer without touching it.
+ */
+
+import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { Theme } from "#src/ui/display";
+import {
+  listNavigableAgents,
+  liveSource,
+  type NavigableSubagent,
+  renderTranscriptLines,
+  type TranscriptSource,
+} from "#src/ui/session-navigation";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Chrome lines: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+const VIEWPORT_HEIGHT_PCT = 70;
+
+/** Component factory shape Pi's `ui.custom` invokes to mount an overlay. */
+export type OverlayComponentFactory<R> = (
+  tui: TUI,
+  theme: Theme,
+  keybindings: unknown,
+  done: (result: R) => void,
+) => Component;
+
+/** Narrow UI interface — only the `ctx.ui` methods the navigator calls. */
+export interface SessionNavigatorUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  custom<R>(component: OverlayComponentFactory<R>, options?: unknown): Promise<R>;
+}
+
+/** Parameters for one `/subagent-sessions` invocation. */
+export interface SessionNavigatorParams {
+  ui: SessionNavigatorUI;
+  agents: readonly NavigableSubagent[];
+  registry: AgentConfigLookup;
+}
+
+/** Options for the read-only transcript overlay. */
+export interface TranscriptOverlayOptions {
+  tui: TUI;
+  theme: Theme;
+  source: TranscriptSource;
+  done: (result: undefined) => void;
+  wrapText: (text: string, width: number) => string[];
+}
+
+/**
+ * Handler for the `/subagent-sessions` slash command.
+ *
+ * Lists navigable subagents, lets the operator pick one, and opens its transcript
+ * read-only. Receives the agent snapshot (`manager.listAgents()`) rather than the
+ * manager, so it stays a reactive consumer with no inbound call into the core.
+ */
+export class SessionNavigatorHandler {
+  async handle({ ui, agents, registry }: SessionNavigatorParams): Promise<void> {
+    const entries = listNavigableAgents(agents, registry);
+    if (entries.length === 0) {
+      ui.notify("No subagent sessions to view.", "info");
+      return;
+    }
+
+    const choice = await ui.select(
+      "Subagent sessions",
+      entries.map((entry) => entry.label),
+    );
+    const entry = entries.find((candidate) => candidate.label === choice);
+    if (!entry) return;
+
+    const source = liveSource(entry.record);
+    await ui.custom<undefined>(
+      (tui, theme, _keybindings, done) =>
+        new TranscriptOverlay({ tui, theme, source, done, wrapText: wrapTextWithAnsi }),
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
+      },
+    );
+  }
+}
+
+/**
+ * Read-only scrollable transcript overlay.
+ *
+ * Re-renders on every source update (live agents); the transcript text is Pi's
+ * `serializeConversation` output from `renderTranscriptLines` — this class owns
+ * only scroll state and chrome, no message formatting.
+ */
+export class TranscriptOverlay implements Component {
+  private scrollOffset = 0;
+  private autoScroll = true;
+  private unsubscribe: (() => void) | undefined;
+  private closed = false;
+
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly source: TranscriptSource;
+  private readonly done: (result: undefined) => void;
+  private readonly wrapText: (text: string, width: number) => string[];
+
+  constructor({ tui, theme, source, done, wrapText }: TranscriptOverlayOptions) {
+    this.tui = tui;
+    this.theme = theme;
+    this.source = source;
+    this.done = done;
+    this.wrapText = wrapText;
+    this.unsubscribe = source.subscribe(() => {
+      if (this.closed) return;
+      this.tui.requestRender();
+    });
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.closed = true;
+      this.done(undefined);
+      return;
+    }
+
+    const totalLines = this.buildContentLines(this.innerWidth()).length;
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, totalLines - viewportHeight);
+
+    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
+      this.autoScroll = false;
+    } else if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "home")) {
+      this.scrollOffset = 0;
+      this.autoScroll = false;
+    } else if (matchesKey(data, "end")) {
+      this.scrollOffset = maxScroll;
+      this.autoScroll = true;
+    }
+  }
+
+  render(width: number): string[] {
+    if (width < 6) return [];
+    const th = this.theme;
+    const innerW = width - 4;
+    const lines: string[] = [];
+
+    const pad = (s: string, len: number): string => s + " ".repeat(Math.max(0, len - visibleWidth(s)));
+    const row = (content: string): string =>
+      th.fg("border", "│") + " " + truncateToWidth(pad(content, innerW), innerW) + " " + th.fg("border", "│");
+    const hrTop = th.fg("border", `╭${"─".repeat(width - 2)}╮`);
+    const hrBot = th.fg("border", `╰${"─".repeat(width - 2)}╯`);
+    const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+    lines.push(hrTop);
+    lines.push(row(th.bold("Subagent session")));
+    lines.push(hrMid);
+
+    const contentLines = this.buildContentLines(innerW);
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, contentLines.length - viewportHeight);
+    if (this.autoScroll) this.scrollOffset = maxScroll;
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = contentLines.slice(visibleStart, visibleStart + viewportHeight);
+    for (let i = 0; i < viewportHeight; i++) lines.push(row(visible[i] ?? ""));
+
+    lines.push(hrMid);
+    const scrollPct =
+      contentLines.length <= viewportHeight
+        ? "100%"
+        : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
+    const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
+    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+    const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
+    lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
+    lines.push(hrBot);
+
+    return lines;
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  invalidate(): void {
+    /* no cached state to clear */
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  private innerWidth(): number {
+    return Math.max(0, this.tui.terminal.columns - 4);
+  }
+
+  private viewportHeight(): number {
+    const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+    return Math.max(MIN_VIEWPORT, maxRows - CHROME_LINES);
+  }
+
+  private buildContentLines(innerW: number): string[] {
+    if (innerW <= 0) return [];
+    const wrapped: string[] = [];
+    for (const line of renderTranscriptLines(this.source)) {
+      if (line === "") {
+        wrapped.push("");
+        continue;
+      }
+      wrapped.push(...this.wrapText(line, innerW));
+    }
+    return wrapped.map((l) => truncateToWidth(l, innerW));
+  }
+}