@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/ui/subagents-settings.ts

@@ -0,0 +1,207 @@
+// ---- 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 maxTurns: number;
+  readonly wrapUpTurns: number;
+  readonly maxDurationSeconds: number;
+  readonly maxQueueWaitSeconds: number;
+  readonly abortGraceSeconds: number;
+  readonly consumedSessionRetentionMinutes: number;
+  readonly unconsumedSessionRetentionMinutes: number;
+  readonly abortAllOnInterrupt: boolean;
+  applyMaxConcurrent(n: number): SettingsToast;
+  applyMaxTurns(n: number): SettingsToast;
+  applyWrapUpTurns(n: number): SettingsToast;
+  applyMaxDurationSeconds(n: number): SettingsToast;
+  applyMaxQueueWaitSeconds(n: number): SettingsToast;
+  applyAbortGraceSeconds(n: number): SettingsToast;
+  applyConsumedSessionRetentionMinutes(n: number): SettingsToast;
+  applyUnconsumedSessionRetentionMinutes(n: number): SettingsToast;
+  toggleAbortAllOnInterrupt(): 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. */
+  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: "Max turns",
+    currentDisplay: (settings) => settings.maxTurns,
+    inputTitle: "Max turns before the hard stop",
+    inputDefault: (settings) => String(settings.maxTurns),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyMaxTurns(n),
+  },
+  {
+    kind: "numeric",
+    label: "Wrap-up turns",
+    currentDisplay: (settings) => settings.wrapUpTurns,
+    inputTitle: "Turns reserved for wrap-up before the hard stop (0 = stop at the limit)",
+    inputDefault: (settings) => String(settings.wrapUpTurns),
+    minimum: 0,
+    validationMessage: "Must be 0 or a positive integer.",
+    apply: (settings, n) => settings.applyWrapUpTurns(n),
+  },
+  {
+    kind: "numeric",
+    label: "Max duration",
+    currentDisplay: (settings) => `${settings.maxDurationSeconds} s`,
+    inputTitle: "Max agent duration in seconds",
+    inputDefault: (settings) => String(settings.maxDurationSeconds),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyMaxDurationSeconds(n),
+  },
+  {
+    kind: "numeric",
+    label: "Max queue wait",
+    currentDisplay: (settings) => `${settings.maxQueueWaitSeconds} s`,
+    inputTitle: "Max queue wait in seconds",
+    inputDefault: (settings) => String(settings.maxQueueWaitSeconds),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyMaxQueueWaitSeconds(n),
+  },
+  {
+    kind: "numeric",
+    label: "Abort grace",
+    currentDisplay: (settings) => `${settings.abortGraceSeconds} s`,
+    inputTitle: "Abort grace period in seconds",
+    inputDefault: (settings) => String(settings.abortGraceSeconds),
+    minimum: 1,
+    validationMessage: "Must be a positive integer.",
+    apply: (settings, n) => settings.applyAbortGraceSeconds(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(),
+  },
+];
+
+// ---- 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");
+    }
+  }
+}

package/src/ui/transcript-content.ts

@@ -0,0 +1,374 @@
+/**
+ * transcript-content.ts — the rows the `/subagents:sessions` overlay paints.
+ *
+ * Owns the transcript's content model: the `SessionMessage` → Pi-component
+ * mapping (mirroring Pi's own interactive-mode `renderSessionContext`), and the
+ * rendered rows those components produce at a given width. The overlay
+ * (`session-navigator.ts`) owns scroll state, chrome, and key handling, and
+ * asks this collaborator only for rows — it never reaches into the components.
+ *
+ * Lives in the SDK/TUI layer rather than the pure `session-navigation.ts` core
+ * because Pi's per-entry components require a `TUI`, `cwd`, and markdown theme.
+ */
+
+import {
+  AssistantMessageComponent,
+  BashExecutionComponent,
+  BranchSummaryMessageComponent,
+  CompactionSummaryMessageComponent,
+  parseSkillBlock,
+  SkillInvocationMessageComponent,
+  ToolExecutionComponent,
+  UserMessageComponent,
+} from "@earendil-works/pi-coding-agent";
+import { Container, type MarkdownTheme, Spacer, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentSessionEvent, SessionMessage } from "#src/types";
+import { describeActivity } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+import type { TranscriptSource } from "#src/ui/session-navigation";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The SDK/TUI environment Pi's per-entry components need, plus the transcript's source. */
+export interface TranscriptContentOptions {
+  tui: TUI;
+  cwd: string;
+  markdownTheme: MarkdownTheme;
+  source: TranscriptSource;
+}
+
+/**
+ * The transcript's renderable rows: settled history rendered through Pi's
+ * per-entry components, followed by the running agent's activity row.
+ *
+ * Settled rows are rendered once per width and cached, so a paint or a scroll
+ * costs a slice rather than a walk of the whole component tree. The activity
+ * row is recomputed per call — it is two rows, and it tracks live state the
+ * source updates without a rebuild.
+ *
+ * Settled history is held as one block of components per message, so a message
+ * that settles appends a block and a tool result touches only its own — neither
+ * discards the rest of the transcript's rendering. This is sound because the
+ * agent core pushes a finished message into its message array before notifying
+ * listeners, so at event time the settled prefix is already visible.
+ *
+ * The message currently being streamed is held as its own component, updated
+ * per delta exactly as Pi's interactive mode does, so a token never touches
+ * settled history. The two provably cannot overlap: the agent core keeps the
+ * in-flight message outside its message array until it settles.
+ */
+export class TranscriptContent {
+  private readonly options: TranscriptContentOptions;
+  /** Settled history, one block per message that produced components. */
+  private blocks: SettledBlock[] = [];
+  /** How many source messages have been consumed into `blocks`. */
+  private consumedCount = 0;
+  /** The last consumed message; a mismatch means history was rewritten. */
+  private lastConsumed: SessionMessage | undefined;
+  /** Whether any consumed block holds components, driving user-message spacing. */
+  private hasVisibleContent = false;
+  /** In-flight tool components by tool-call id, pairing a later result to its block. */
+  private readonly pendingTools = new Map<string, PendingTool>();
+  /** Width `blocks` and `settledRows` were rendered at. */
+  private settledWidth: number | undefined;
+  /** Concatenation of every block's rows, or undefined when the cache is cold. */
+  private settledRows: readonly string[] | undefined;
+  /** The message being streamed right now, rendered below settled history. */
+  private inFlight: AssistantMessageComponent | undefined;
+  /** Width `inFlightRows` was rendered at. */
+  private inFlightWidth: number | undefined;
+  private inFlightRows: readonly string[] | undefined;
+
+  constructor(options: TranscriptContentOptions) {
+    this.options = options;
+    this.consumeSettled();
+  }
+
+  /** Total content rows at `width`: settled history plus the live tail. */
+  lineCount(width: number): number {
+    if (width <= 0) return 0;
+    return this.settled(width).length + this.tail(width).length;
+  }
+
+  /** Rows `[start, start + count)` at `width`, clamped to what exists. */
+  slice(width: number, start: number, count: number): string[] {
+    if (width <= 0) return [];
+    const settled = this.settled(width);
+    const end = start + count;
+    const rows = settled.slice(start, Math.min(end, settled.length));
+    if (end > settled.length) {
+      const tail = this.tail(width);
+      rows.push(...tail.slice(Math.max(0, start - settled.length), end - settled.length));
+    }
+    return rows;
+  }
+
+  /**
+   * Route one session event to the narrowest update it allows. A delta on the
+   * in-flight message touches only that component. A run or compaction boundary
+   * may have rewritten or mutated history in place, so it rebuilds wholesale.
+   * Everything else consumes whatever settled since the last check.
+   */
+  apply(event?: AgentSessionEvent): void {
+    const partial = inFlightAssistantMessage(event);
+    if (partial) {
+      this.updateInFlight(partial);
+      return;
+    }
+    if (event?.type === "agent_end" || event?.type === "compaction_end") {
+      this.reset();
+    } else if (event?.type === "message_end") {
+      this.clearInFlight();
+    }
+    this.consumeSettled();
+  }
+
+  /** Drop cached rendering held by the mounted components and by this object. */
+  invalidate(): void {
+    for (const block of this.blocks) {
+      block.container.invalidate();
+      block.rows = undefined;
+    }
+    this.settledRows = undefined;
+    this.inFlight?.invalidate();
+    this.inFlightRows = undefined;
+  }
+
+  // ---- Private ----
+
+  /** Settled rows at `width`; each block renders once per width and content change. */
+  private settled(width: number): readonly string[] {
+    if (this.settledWidth !== width) {
+      this.settledWidth = width;
+      for (const block of this.blocks) block.rows = undefined;
+      this.settledRows = undefined;
+    }
+    if (this.settledRows) return this.settledRows;
+    const rows: string[] = [];
+    for (const block of this.blocks) {
+      block.rows ??= block.container.render(width).map((row) => truncateToWidth(row, width));
+      rows.push(...block.rows);
+    }
+    this.settledRows = rows;
+    return rows;
+  }
+
+  /** Rows below settled history: the in-flight message, then the activity row. */
+  private tail(width: number): readonly string[] {
+    const rows = [...this.inFlightRendered(width)];
+    const streaming = this.options.source.streaming();
+    if (streaming) {
+      const activity = `${GLYPHS.streaming} ${describeActivity(streaming.activeTools, streaming.responseText)}`;
+      rows.push("", truncateToWidth(activity, width));
+    }
+    return rows;
+  }
+
+  /** The in-flight message's rows, re-rendered independently of settled history. */
+  private inFlightRendered(width: number): readonly string[] {
+    if (!this.inFlight) return [];
+    if (this.inFlightWidth !== width) {
+      this.inFlightWidth = width;
+      this.inFlightRows = undefined;
+    }
+    this.inFlightRows ??= this.inFlight.render(width).map((row) => truncateToWidth(row, width));
+    return this.inFlightRows;
+  }
+
+  private updateInFlight(message: AssistantSessionMessage): void {
+    if (this.inFlight) this.inFlight.updateContent(message);
+    else this.inFlight = new AssistantMessageComponent(message, false, this.options.markdownTheme);
+    this.inFlightRows = undefined;
+  }
+
+  private clearInFlight(): void {
+    this.inFlight = undefined;
+    this.inFlightRows = undefined;
+  }
+
+  /** Discard all settled state, so the next consume rebuilds from scratch. */
+  private reset(): void {
+    this.blocks = [];
+    this.consumedCount = 0;
+    this.lastConsumed = undefined;
+    this.hasVisibleContent = false;
+    this.pendingTools.clear();
+    this.settledRows = undefined;
+    this.clearInFlight();
+  }
+
+  /**
+   * Append blocks for every message that settled since the last check. When the
+   * consumed prefix no longer mirrors the source — history replaced wholesale by
+   * compaction or branching — start over rather than appending onto stale blocks.
+   */
+  private consumeSettled(): void {
+    const messages = this.options.source.getMessages();
+    if (this.hasRewrittenHistory(messages)) this.reset();
+    if (messages.length === this.consumedCount) return;
+    for (let i = this.consumedCount; i < messages.length; i++) this.consumeMessage(messages[i]);
+    this.consumedCount = messages.length;
+    this.lastConsumed = messages.at(-1);
+    this.settledRows = undefined;
+  }
+
+  private hasRewrittenHistory(messages: readonly SessionMessage[]): boolean {
+    if (messages.length < this.consumedCount) return true;
+    return this.consumedCount > 0 && messages[this.consumedCount - 1] !== this.lastConsumed;
+  }
+
+  /**
+   * Map one settled message onto its own block of Pi's per-entry components,
+   * mirroring Pi's own interactive-mode `renderSessionContext` mapping.
+   * `custom`-role messages produce no block — rendering them needs the child
+   * session's message-renderer registry, which the navigator does not hold.
+   */
+  private consumeMessage(message: SessionMessage): void {
+    switch (message.role) {
+      case "assistant":
+        this.consumeAssistant(message);
+        break;
+      case "toolResult":
+        this.consumeToolResult(message);
+        break;
+      case "user":
+        this.consumeUser(message);
+        break;
+      case "bashExecution":
+        this.consumeBashExecution(message);
+        break;
+      case "compactionSummary":
+        this.consumeSummary(new CompactionSummaryMessageComponent(message, this.options.markdownTheme));
+        break;
+      case "branchSummary":
+        this.consumeSummary(new BranchSummaryMessageComponent(message, this.options.markdownTheme));
+        break;
+    }
+  }
+
+  private consumeAssistant(message: AssistantSessionMessage): void {
+    const block = this.appendBlock();
+    block.container.addChild(new AssistantMessageComponent(message, false, this.options.markdownTheme));
+    for (const content of message.content) {
+      if (content.type !== "toolCall") continue;
+      const tool = new ToolExecutionComponent(
+        content.name,
+        content.id,
+        content.arguments,
+        { showImages: false },
+        this.options.source.getToolDefinition(content.name),
+        this.options.tui,
+        this.options.cwd,
+      );
+      tool.setExpanded(true);
+      block.container.addChild(tool);
+      this.pendingTools.set(content.id, { component: tool, block });
+    }
+    this.hasVisibleContent = true;
+  }
+
+  /** A tool result mutates the block holding its call; no other block changes. */
+  private consumeToolResult(message: Extract<SessionMessage, { role: "toolResult" }>): void {
+    const pending = this.pendingTools.get(message.toolCallId);
+    if (!pending) return;
+    pending.component.updateResult(message);
+    pending.block.rows = undefined;
+    this.settledRows = undefined;
+    this.pendingTools.delete(message.toolCallId);
+  }
+
+  private consumeUser(message: Extract<SessionMessage, { role: "user" }>): void {
+    const block = this.appendBlock();
+    addUserComponents(block.container, message.content, this.options.markdownTheme, this.hasVisibleContent);
+    if (block.container.children.length > 0) this.hasVisibleContent = true;
+  }
+
+  private consumeBashExecution(message: Extract<SessionMessage, { role: "bashExecution" }>): void {
+    const block = this.appendBlock();
+    const bash = new BashExecutionComponent(message.command, this.options.tui, message.excludeFromContext);
+    if (message.output) bash.appendOutput(message.output);
+    bash.setComplete(message.exitCode, message.cancelled, undefined, message.fullOutputPath);
+    block.container.addChild(bash);
+    this.hasVisibleContent = true;
+  }
+
+  /** Compaction and branch summaries share the same spacer-plus-expanded shape. */
+  private consumeSummary(
+    summary: CompactionSummaryMessageComponent | BranchSummaryMessageComponent,
+  ): void {
+    const block = this.appendBlock();
+    block.container.addChild(new Spacer(1));
+    summary.setExpanded(true);
+    block.container.addChild(summary);
+    this.hasVisibleContent = true;
+  }
+
+  private appendBlock(): SettledBlock {
+    const block: SettledBlock = { container: new Container(), rows: undefined };
+    this.blocks.push(block);
+    return block;
+  }
+}
+
+/** One settled message's components plus its rows at the current width. */
+interface SettledBlock {
+  readonly container: Container;
+  rows: readonly string[] | undefined;
+}
+
+/** A tool call awaiting its result, and the block whose rows it will invalidate. */
+interface PendingTool {
+  readonly component: ToolExecutionComponent;
+  readonly block: SettledBlock;
+}
+
+/** The assistant variant of a session message, as Pi's components consume it. */
+type AssistantSessionMessage = Extract<SessionMessage, { role: "assistant" }>;
+
+/**
+ * The in-flight assistant message a partial event carries, or undefined when the
+ * event is anything else. A partial for another role means a message settled
+ * elsewhere in the history, which only a rebuild can pick up.
+ */
+function inFlightAssistantMessage(event?: AgentSessionEvent): AssistantSessionMessage | undefined {
+  if (event?.type !== "message_start" && event?.type !== "message_update") return undefined;
+  return event.message.role === "assistant" ? event.message : undefined;
+}
+
+/**
+ * Render a user message (skill block + text) into the block, mirroring Pi.
+ * Whether a leading spacer is needed is a whole-transcript property, so the
+ * caller — which alone knows what precedes this block — supplies it.
+ */
+function addUserComponents(
+  container: Container,
+  content: string | readonly { type: string; text?: string }[],
+  markdownTheme: MarkdownTheme,
+  hasPrecedingContent: boolean,
+): void {
+  const text = userMessageText(content);
+  if (!text) return;
+  if (hasPrecedingContent) container.addChild(new Spacer(1));
+
+  const skillBlock = parseSkillBlock(text);
+  if (!skillBlock) {
+    container.addChild(new UserMessageComponent(text, markdownTheme));
+    return;
+  }
+  const skill = new SkillInvocationMessageComponent(skillBlock, markdownTheme);
+  skill.setExpanded(true);
+  container.addChild(skill);
+  if (skillBlock.userMessage) {
+    container.addChild(new Spacer(1));
+    container.addChild(new UserMessageComponent(skillBlock.userMessage, markdownTheme));
+  }
+}
+
+/** Concatenate the text blocks of a user message's content (mirrors Pi). */
+function userMessageText(content: string | readonly { type: string; text?: string }[]): string {
+  if (typeof content === "string") return content;
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text ?? "")
+    .join("");
+}