@jopqior/pi-subagents 1.0.0

package/src/ui/session-navigation.ts

@@ -0,0 +1,150 @@
+/**
+ * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
+ *
+ * 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).
+ *
+ * The `TranscriptSource` seam decouples *how messages are sourced* (live record
+ * here; a file snapshot in a follow-up) 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.
+ */
+
+import { buildSessionContext, parseSessionEntries, type SessionEntry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import { isRunningStatus, type SubagentStatus } from "#src/lifecycle/subagent-state";
+import type { AgentSessionEvent, SessionMessage, SubagentType } from "#src/types";
+import { 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[];
+  /** Persisted transcript path, retained after the live session is released. */
+  readonly outputFile: string | undefined;
+  isSessionReady(): boolean;
+  subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+  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 record; a `snapshot`
+ * entry sources it from the persisted session file (the session was released by
+ * the retention sweep, but the record and its transcript pointer survive).
+ */
+export type NavigationEntry =
+  | { readonly kind: "live"; readonly label: string; readonly record: NavigableSubagent }
+  | { readonly kind: "snapshot"; readonly label: string; readonly outputFile: string };
+
+/** The fields `buildLabel` reads — shared by the live and snapshot (released-session) label paths. */
+interface LabelFields {
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+}
+
+/** 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. The session event is forwarded so a consumer can route on it —
+   * a streaming delta and a settled message warrant very different work.
+   */
+  subscribe(onChange: (event?: AgentSessionEvent) => void): (() => void) | undefined;
+  /** Running-agent streaming state, or undefined when not streaming. */
+  streaming(): StreamingState | undefined;
+  /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
+  getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+/**
+ * Label every navigable subagent for the picker: records with a live session
+ * source their transcript in-memory (`live`); records whose session the
+ * retention sweep released but which retain a transcript pointer source it from
+ * disk (`snapshot`). Records with neither are not navigable. Live entries first.
+ */
+export function listNavigableAgents(
+  agents: readonly NavigableSubagent[],
+  registry: AgentConfigLookup,
+): NavigationEntry[] {
+  const live: NavigationEntry[] = [];
+  const snapshots: NavigationEntry[] = [];
+  for (const record of agents) {
+    if (record.isSessionReady()) {
+      live.push({ kind: "live", record, label: buildLabel(record, registry) });
+    } else if (record.outputFile) {
+      snapshots.push({ kind: "snapshot", outputFile: record.outputFile, label: buildLabel(record, registry, true) });
+    }
+  }
+  return [...live, ...snapshots];
+}
+
+/**
+ * Source a transcript from a persisted child-session JSONL snapshot.
+ *
+ * For an agent whose live session the retention sweep released: the in-memory
+ * message history is gone, but the session file survives on disk (and the
+ * record retains its path). Reads the file, drops the `SessionHeader`, and resolves the
+ * message list via Pi's own parser. A static snapshot — no subscription, no
+ * streaming, no live tool registry. `readFile` is injected so this module makes
+ * no `fs` calls.
+ */
+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);
+  return {
+    getMessages: () => messages,
+    subscribe: () => undefined,
+    streaming: () => undefined,
+    getToolDefinition: () => undefined,
+  };
+}
+
+/** 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: () =>
+      isRunningStatus(record.status)
+        ? { activeTools: record.activeTools, responseText: record.responseText }
+        : undefined,
+    getToolDefinition: (name) => record.getToolDefinition(name),
+  };
+}
+
+function buildLabel(fields: LabelFields, registry: AgentConfigLookup, released = false): string {
+  const name = getDisplayName(fields.type, registry);
+  const duration = formatDuration(fields.startedAt, fields.completedAt);
+  const marker = released ? " · session released (snapshot)" : "";
+  return `${name} (${fields.description}) · ${fields.toolUses} tools · ${fields.status} · ${duration}${marker}`;
+}

package/src/ui/session-navigator.ts

@@ -0,0 +1,255 @@
+/**
+ * session-navigator.ts — The `/subagents:sessions` command: pick a subagent and
+ * read its transcript through Pi's own per-entry session components.
+ *
+ * SDK/TUI consumer half of native session navigation. The unit-testable core
+ * (selection, sourcing) lives in `session-navigation.ts`; this module wires that
+ * core to the command picker and a read-only scrollable pane, and owns the
+ * renderer — it mounts Pi's interactive components (`AssistantMessageComponent`,
+ * `ToolExecutionComponent`, …) into a `Container`, mirroring Pi's own
+ * `renderSessionContext` mapping. Rendering lives here, not in the pure module,
+ * because the components require a `TUI`, `cwd`, and markdown theme.
+ *
+ * The pane is strictly read-only — steering stays in the `steer_subagent` tool
+ * and the widget. It consumes a `TranscriptSource`, so a released agent's disk
+ * snapshot (`fileSnapshotSource`) swaps in without touching the renderer or the pane.
+ *
+ * It mounts through `ui.custom`'s non-overlay path deliberately: Pi's regular-mode
+ * renderer composites overlays into the buffer that backs scrollback, so an overlay
+ * mount bakes this pane's chrome into terminal history. See
+ * `docs/decisions/0007-transcript-viewer-is-not-an-overlay.md`.
+ */
+
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  type MarkdownTheme,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { Theme } from "#src/ui/display";
+import { fileSnapshotSource, listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
+import { TranscriptContent } from "#src/ui/transcript-content";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Chrome lines: the header and the footer. The pane is docked, so it needs no frame. */
+const CHROME_LINES = 2;
+const MIN_VIEWPORT = 3;
+const VIEWPORT_HEIGHT_PCT = 70;
+
+/** Component factory shape Pi's `ui.custom` invokes to mount a component. */
+export type CustomComponentFactory<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: CustomComponentFactory<R>, options?: unknown): Promise<R>;
+}
+
+/** Parameters for one `/subagents:sessions` invocation. */
+export interface SessionNavigatorParams {
+  ui: SessionNavigatorUI;
+  agents: readonly NavigableSubagent[];
+  registry: AgentConfigLookup;
+  /** Working directory for tool-call rendering (relative path display). */
+  cwd: string;
+  /** Reads a persisted session file for the file-snapshot source. */
+  readFile: (path: string) => string;
+}
+
+/** Options for the read-only transcript pane. */
+export interface TranscriptPaneOptions {
+  tui: TUI;
+  theme: Theme;
+  source: TranscriptSource;
+  done: (result: undefined) => void;
+  cwd: string;
+  markdownTheme: MarkdownTheme;
+}
+
+/**
+ * Handler for the `/subagents: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, cwd, readFile }: 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;
+
+    let source: TranscriptSource;
+    try {
+      source = entry.kind === "live" ? liveSource(entry.record) : fileSnapshotSource(entry.outputFile, readFile);
+    } catch {
+      ui.notify("Could not read the session transcript file.", "error");
+      return;
+    }
+    const markdownTheme = getMarkdownTheme();
+    await ui.custom<undefined>(
+      (tui, theme, _keybindings, done) =>
+        new TranscriptPane({ tui, theme, source, done, cwd, markdownTheme }),
+      { overlay: false },
+    );
+  }
+}
+
+/**
+ * Read-only scrollable transcript pane.
+ *
+ * Owns scroll state, chrome, and key handling; the rows it paints come from a
+ * `TranscriptContent` collaborator, which holds the transcript's components and
+ * refreshes them when the source changes (live agents).
+ */
+export class TranscriptPane 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 done: (result: undefined) => void;
+  private readonly content: TranscriptContent;
+  /** Width the host last rendered at; input must use the same layout. */
+  private renderedWidth: number | undefined;
+
+  constructor({ tui, theme, source, done, cwd, markdownTheme }: TranscriptPaneOptions) {
+    this.tui = tui;
+    this.theme = theme;
+    this.done = done;
+    this.content = new TranscriptContent({ tui, cwd, markdownTheme, source });
+    this.unsubscribe = source.subscribe((event) => {
+      if (this.closed) return;
+      this.content.apply(event);
+      this.tui.requestRender();
+    });
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.closed = true;
+      this.done(undefined);
+      return;
+    }
+
+    const { viewportHeight, maxScroll } = this.scrollBounds(this.inputWidth());
+
+    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;
+    this.renderedWidth = width;
+    const lines: string[] = [];
+
+    // No frame, so no padding either: a row padded to the full terminal width
+    // wraps onto the next terminal row.
+    const fit = (content: string): string => truncateToWidth(content, width);
+
+    lines.push(fit(th.bold("Subagent session")));
+
+    const { totalLines, viewportHeight, maxScroll } = this.scrollBounds(width);
+    if (this.autoScroll) this.scrollOffset = maxScroll;
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = this.content.slice(width, visibleStart, viewportHeight);
+    for (let i = 0; i < viewportHeight; i++) lines.push(fit(visible[i] ?? ""));
+
+    const scrollPct =
+      totalLines <= viewportHeight
+        ? "100%"
+        : `${Math.round(((visibleStart + viewportHeight) / totalLines) * 100)}%`;
+    const footerLeft = th.fg("dim", `${totalLines} lines · ${scrollPct}`);
+    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+    const footerGap = Math.max(1, width - visibleWidth(footerLeft) - visibleWidth(footerRight));
+    lines.push(fit(footerLeft + " ".repeat(footerGap) + footerRight));
+
+    return lines;
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  invalidate(): void {
+    this.content.invalidate();
+  }
+
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  /**
+   * Scroll geometry at a given layout width.
+   *
+   * The single place a width becomes a viewport height, so `render` and
+   * `handleInput` cannot disagree about how far the transcript scrolls.
+   */
+  private scrollBounds(width: number): { totalLines: number; viewportHeight: number; maxScroll: number } {
+    const totalLines = this.content.lineCount(width);
+    const viewportHeight = this.viewportHeight(totalLines);
+    return { totalLines, viewportHeight, maxScroll: Math.max(0, totalLines - viewportHeight) };
+  }
+
+  /**
+   * The width `handleInput` must lay out at: the one the host actually supplied,
+   * so scroll bounds match the layout on screen. Before the first paint there is
+   * none, so fall back to the full terminal width.
+   */
+  private inputWidth(): number {
+    return this.renderedWidth ?? this.tui.terminal.columns;
+  }
+
+  /**
+   * Rows the transcript gets: what it needs, capped at the pane's share of the
+   * terminal so a long or live transcript cannot crowd out the conversation, and
+   * floored so a short one still reads as a pane.
+   */
+  private viewportHeight(totalLines: number): number {
+    const cap = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100) - CHROME_LINES;
+    return Math.max(MIN_VIEWPORT, Math.min(totalLines, cap));
+  }
+}

package/src/ui/subagents-settings.ts

@@ -0,0 +1,179 @@
+// ---- Narrow interfaces ----
+
+/** The toast a settings mutation returns for the UI to display. */
+export interface SettingsToast {
+  message: string;
+  level: "info" | "warning";
+}
+
+/** Narrow settings interface required by the subagents:settings command. */
+export interface SubagentsSettingsManager {
+  readonly maxConcurrent: number;
+  readonly defaultMaxTurns: number | undefined;
+  readonly graceTurns: number;
+  readonly consumedSessionRetentionMinutes: number;
+  readonly unconsumedSessionRetentionMinutes: number;
+  readonly abortAllOnInterrupt: boolean;
+  readonly midRunUpdates: boolean;
+  applyMaxConcurrent(n: number): SettingsToast;
+  applyDefaultMaxTurns(n: number): SettingsToast;
+  applyGraceTurns(n: number): SettingsToast;
+  applyConsumedSessionRetentionMinutes(n: number): SettingsToast;
+  applyUnconsumedSessionRetentionMinutes(n: number): SettingsToast;
+  toggleAbortAllOnInterrupt(): SettingsToast;
+  toggleMidRunUpdates(): SettingsToast;
+}
+
+/** Narrow UI interface — only the ctx.ui methods the settings handler calls. */
+export interface SubagentsSettingsUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  input(title: string, defaultValue?: string): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+}
+
+// ---- Descriptor table ----
+
+/** Fields every setting needs to render its line in the select list. */
+interface SettingDescriptorBase {
+  /** Prefix used both to build the select option and to match the user's choice. */
+  label: string;
+  /** Current value rendered in the select option (e.g. "unlimited" for an unset default). */
+  currentDisplay: (settings: SubagentsSettingsManager) => string | number;
+}
+
+/** Describes one numeric setting's prompt, validation, and apply behavior. */
+interface NumericSettingDescriptor extends SettingDescriptorBase {
+  kind: "numeric";
+  /** Title shown on the input prompt. */
+  inputTitle: string;
+  /** Value pre-filled into the input box. */
+  inputDefault: (settings: SubagentsSettingsManager) => string;
+  /** Minimum accepted integer, inclusive. */
+  minimum: number;
+  /** Warning shown when the parsed value is below the minimum. */
+  validationMessage: string;
+  /** Applies the validated value and returns the toast to display. */
+  apply: (settings: SubagentsSettingsManager, n: number) => SettingsToast;
+}
+
+/** Describes one boolean setting, flipped directly from the select list. */
+interface ToggleSettingDescriptor extends SettingDescriptorBase {
+  kind: "toggle";
+  /** Flips the setting and returns the toast to display. */
+  toggle: (settings: SubagentsSettingsManager) => SettingsToast;
+}
+
+type SettingDescriptor = NumericSettingDescriptor | ToggleSettingDescriptor;
+
+const SETTINGS: readonly SettingDescriptor[] = [
+  {
+    kind: "numeric",
+    label: "Max concurrency",
+    currentDisplay: (settings) => settings.maxConcurrent,
+    inputTitle: "Max concurrent background agents",
+    inputDefault: (settings) => String(settings.maxConcurrent),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyMaxConcurrent(n),
+  },
+  {
+    kind: "numeric",
+    label: "Default max turns",
+    currentDisplay: (settings) => settings.defaultMaxTurns ?? "unlimited",
+    inputTitle: "Default max turns before wrap-up (0 = unlimited)",
+    inputDefault: (settings) => String(settings.defaultMaxTurns ?? 0),
+    minimum: 0,
+    validationMessage: "Must be 0 (unlimited) or a positive integer.",
+    apply: (settings, n) => settings.applyDefaultMaxTurns(n),
+  },
+  {
+    kind: "numeric",
+    label: "Grace turns",
+    currentDisplay: (settings) => settings.graceTurns,
+    inputTitle: "Grace turns after wrap-up steer",
+    inputDefault: (settings) => String(settings.graceTurns),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyGraceTurns(n),
+  },
+  {
+    kind: "numeric",
+    label: "Consumed-session retention",
+    currentDisplay: (settings) => `${settings.consumedSessionRetentionMinutes} min`,
+    inputTitle: "Minutes to retain a consumed agent's session",
+    inputDefault: (settings) => String(settings.consumedSessionRetentionMinutes),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyConsumedSessionRetentionMinutes(n),
+  },
+  {
+    kind: "numeric",
+    label: "Unconsumed-session retention",
+    currentDisplay: (settings) => `${settings.unconsumedSessionRetentionMinutes} min`,
+    inputTitle: "Minutes to retain an unconsumed agent's session (safety cap)",
+    inputDefault: (settings) => String(settings.unconsumedSessionRetentionMinutes),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyUnconsumedSessionRetentionMinutes(n),
+  },
+  {
+    kind: "toggle",
+    label: "Abort all subagents on ESC",
+    currentDisplay: (settings) => (settings.abortAllOnInterrupt ? "on" : "off"),
+    toggle: (settings) => settings.toggleAbortAllOnInterrupt(),
+  },
+  {
+    kind: "toggle",
+    label: "Mid-run updates from background subagents",
+    currentDisplay: (settings) => (settings.midRunUpdates ? "on" : "off"),
+    toggle: (settings) => settings.toggleMidRunUpdates(),
+  },
+];
+
+// ---- Class ----
+
+/**
+ * Handler for the `/subagents:settings` slash command.
+ *
+ * Call `handle({ ui })` from the Pi command registration to open the interactive
+ * settings list. Lifted from `AgentsMenuHandler.showSettings`.
+ */
+export class SubagentsSettingsHandler {
+  constructor(private readonly settings: SubagentsSettingsManager) {}
+
+  async handle({ ui }: { ui: SubagentsSettingsUI }): Promise<void> {
+    const options = SETTINGS.map(
+      (d) => `${d.label} (current: ${d.currentDisplay(this.settings)})`,
+    );
+    const choice = await ui.select("Settings", options);
+    if (!choice) return;
+
+    const descriptor = SETTINGS.find((d) => choice.startsWith(d.label));
+    if (!descriptor) return;
+
+    if (descriptor.kind === "toggle") {
+      const toast = descriptor.toggle(this.settings);
+      ui.notify(toast.message, toast.level);
+      return;
+    }
+
+    await this.promptNumeric(ui, descriptor);
+  }
+
+  /** Ask for a number, validate it against the descriptor, apply it, and notify. */
+  private async promptNumeric(
+    ui: SubagentsSettingsUI,
+    descriptor: NumericSettingDescriptor,
+  ): Promise<void> {
+    const val = await ui.input(descriptor.inputTitle, descriptor.inputDefault(this.settings));
+    if (!val) return;
+
+    const n = parseInt(val, 10);
+    if (n >= descriptor.minimum) {
+      const toast = descriptor.apply(this.settings, n);
+      ui.notify(toast.message, toast.level);
+    } else {
+      ui.notify(descriptor.validationMessage, "warning");
+    }
+  }
+}