@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/ui/session-navigation.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 type { SubagentOutcome, SubagentPhase } 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 phase: SubagentPhase;
+  readonly outcome?: SubagentOutcome;
+  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 phase: SubagentPhase;
+  readonly outcome?: SubagentOutcome;
+  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: () =>
+      record.phase === "running"
+        ? { 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.outcome ?? fields.phase} · ${duration}${marker}`;
+}

package/src/ui/session-navigator.ts

@@ -0,0 +1,257 @@
+/**
+ * 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 overlay, 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 overlay 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 overlay.
+ */
+
+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: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+const VIEWPORT_HEIGHT_PCT = 70;
+/** Overlay width as a share of the terminal, as handed to Pi's overlay compositor. */
+const OVERLAY_WIDTH_PCT = 90;
+
+/** 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 `/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 overlay. */
+export interface TranscriptOverlayOptions {
+  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 TranscriptOverlay({ tui, theme, source, done, cwd, markdownTheme }),
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "center",
+          width: `${OVERLAY_WIDTH_PCT}%`,
+          maxHeight: `${VIEWPORT_HEIGHT_PCT}%`,
+        },
+      },
+    );
+  }
+}
+
+/**
+ * Read-only scrollable transcript overlay.
+ *
+ * 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 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 done: (result: undefined) => void;
+  private readonly content: TranscriptContent;
+  /** Inner width the compositor last rendered at; input must use the same layout. */
+  private renderedInnerWidth: number | undefined;
+
+  constructor({ tui, theme, source, done, cwd, markdownTheme }: TranscriptOverlayOptions) {
+    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 totalLines = this.content.lineCount(this.inputWidth());
+    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;
+    this.renderedInnerWidth = innerW;
+    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 totalLines = this.content.lineCount(innerW);
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, totalLines - viewportHeight);
+    if (this.autoScroll) this.scrollOffset = maxScroll;
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = this.content.slice(innerW, visibleStart, viewportHeight);
+    for (let i = 0; i < viewportHeight; i++) lines.push(row(visible[i] ?? ""));
+
+    lines.push(hrMid);
+    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, 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 {
+    this.content.invalidate();
+  }
+
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  /**
+   * The width `handleInput` must lay out at: the one the compositor actually
+   * supplied, so scroll bounds match the layout on screen. Before the first
+   * paint there is none, so fall back to the overlay's share of the terminal.
+   */
+  private inputWidth(): number {
+    return (
+      this.renderedInnerWidth ??
+      Math.max(0, Math.floor((this.tui.terminal.columns * OVERLAY_WIDTH_PCT) / 100) - 4)
+    );
+  }
+
+  private viewportHeight(): number {
+    const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+    return Math.max(MIN_VIEWPORT, maxRows - CHROME_LINES);
+  }
+}

package/src/ui/subagents-agents.ts

@@ -0,0 +1,116 @@
+import type { AgentEnablementScope, AgentEnablementState } from "#src/config/agent-enablement";
+import type { AgentTypeRegistry } from "#src/config/agent-types";
+import { BUILTIN_TOOL_NAMES } from "#src/config/agent-types";
+import type { AgentConfig } from "#src/types";
+
+interface AgentSettings {
+  getState(name: string): AgentEnablementState;
+  getPath(scope: AgentEnablementScope): string;
+  set(scope: AgentEnablementScope, name: string, enabled: boolean | undefined): void | Promise<void>;
+}
+
+export interface SubagentsAgentsUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+}
+
+const SOURCE_LABELS = { project: "当前项目", global: "全局", default: "默认" } as const;
+const BACK = "返回代理列表";
+const ACTIONS = ["启用", "禁用", "恢复继承"];
+
+function stateLabel(enabled: boolean): string {
+  return enabled ? "启用" : "禁用";
+}
+
+function overrideLabel(enabled: boolean | undefined): string {
+  return enabled === undefined ? "继承" : stateLabel(enabled);
+}
+
+/** Native dialogs keep keyboard navigation, filtering and terminal sizing in Pi. */
+export class SubagentsAgentsHandler {
+  constructor(
+    private readonly registry: Pick<AgentTypeRegistry, "getAllTypes" | "resolveAgentConfig">,
+    private readonly settings: AgentSettings,
+    private readonly refresh: () => void,
+  ) {}
+
+  async handle({ ui }: { ui: SubagentsAgentsUI }): Promise<void> {
+    while (true) {
+      this.refresh();
+      const entries = this.registry.getAllTypes().map((name) => {
+        const state = this.settings.getState(name);
+        return { name, label: `[${stateLabel(state.enabled)}] ${name} · ${SOURCE_LABELS[state.source]}` };
+      });
+      if (entries.length === 0) {
+        ui.notify("没有可管理的子代理。", "info");
+        return;
+      }
+      const enabled = entries.filter(({ name }) => this.settings.getState(name).enabled).length;
+      const choice = await ui.select(
+        `子代理（${enabled} 启用 / ${entries.length - enabled} 禁用）`,
+        entries.map(({ label }) => label),
+      );
+      const entry = entries.find(({ label }) => label === choice);
+      if (!entry) return;
+      await this.manageAgent(entry.name, ui);
+    }
+  }
+
+  private async manageAgent(name: string, ui: SubagentsAgentsUI): Promise<void> {
+    while (true) {
+      this.refresh();
+      // 用户可能在菜单打开期间删除定义；不要把回退配置显示成原代理。
+      if (!this.registry.getAllTypes().includes(name)) {
+        ui.notify(`代理 ${name} 的定义已移除。`, "warning");
+        return;
+      }
+      const state = this.settings.getState(name);
+      const config = this.registry.resolveAgentConfig(name);
+      const scopes = [
+        { scope: "project" as const, label: `当前项目（${overrideLabel(state.project)}）` },
+        { scope: "global" as const, label: `全局（${overrideLabel(state.global)}）` },
+      ];
+      const choice = await ui.select(this.details(config, state), [...scopes.map(({ label }) => label), BACK]);
+      const selected = scopes.find(({ label }) => label === choice);
+      if (!selected) return;
+      await this.changeState(name, selected.scope, ui);
+    }
+  }
+
+  private details(config: AgentConfig, state: AgentEnablementState): string {
+    const tools = config.toolNames ?? BUILTIN_TOOL_NAMES;
+    return [
+      config.displayName ? `${config.displayName} (${config.name})` : config.name,
+      config.description,
+      `状态：${stateLabel(state.enabled)} · 来源：${SOURCE_LABELS[state.source]}`,
+      `模型：${config.model ?? "继承父代理"} · 思考：${config.thinking ?? "继承父代理"}`,
+      `工具：${tools.length ? tools.join(", ") : "无"}`,
+      `定义：${config.filePath ?? "内置"}`,
+      "选择启停设置的作用域：",
+    ].join("\n");
+  }
+
+  private async changeState(name: string, scope: AgentEnablementScope, ui: SubagentsAgentsUI): Promise<void> {
+    const choice = await ui.select(
+      `${name} · ${SOURCE_LABELS[scope]}\n保存到：${this.settings.getPath(scope)}\n恢复继承：${scope === "project" ? "跟随全局设置" : "回到默认启用"}`,
+      ACTIONS,
+    );
+    if (!choice || !ACTIONS.includes(choice)) return;
+    const enabled = choice === "恢复继承" ? undefined : choice === "启用";
+    try {
+      await this.settings.set(scope, name, enabled);
+    } catch (error) {
+      ui.notify(`保存失败：${error instanceof Error ? error.message : String(error)}`, "error");
+      return;
+    }
+    this.refresh();
+    const state = this.settings.getState(name);
+    const overridden = scope === "global" && state.project !== undefined;
+    ui.notify(
+      `${name}：已在${SOURCE_LABELS[scope]}${choice === "恢复继承" ? "恢复继承" : `设为${choice}`}。` +
+      `当前项目${stateLabel(state.enabled)}（${SOURCE_LABELS[state.source]}）。` +
+      (overridden ? "全局设置被当前项目设置覆盖。" : ""),
+      overridden ? "warning" : "info",
+    );
+  }
+}