@herbertgao/pi-subagents 0.16.1 → 0.17.0

package/src/ui/conversation-viewer.ts

@@ -5,10 +5,16 @@
  * Subscribes to session events for real-time streaming updates.
  */
 
-import type { AgentSession } from "@earendil-works/pi-coding-agent"
+import {
+  type AgentSession,
+  getMarkdownTheme,
+} from "@earendil-works/pi-coding-agent"
 import {
   type Component,
   Input,
+  Markdown,
+  type MarkdownOptions,
+  type MarkdownTheme,
   matchesKey,
   type TUI,
   truncateToWidth,
@@ -17,7 +23,7 @@ import {
 } from "@earendil-works/pi-tui"
 import { renderAgentName } from "../agent-color.js"
 import { extractText } from "../context.js"
-import type { AgentRecord } from "../types.js"
+import type { AgentRecord, ViewerMarkdownMode } from "../types.js"
 import {
   getLifetimeCost,
   getLifetimeTotal,
@@ -46,6 +52,114 @@ const MIN_VIEWPORT = 3
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export const VIEWPORT_HEIGHT_PCT = 70
 
+/**
+ * Cap on a single tool result or bash output before the viewer elides the rest.
+ *
+ * The cap is not cosmetic — it bounds render cost. `buildContentLines()` runs on
+ * every render *and* on every scroll key (`handleInput` calls it to compute
+ * `maxScroll`), so an uncapped 200 KB result costs ~6 ms per keystroke to parse
+ * as Markdown, against ~0.5 ms once capped and effectively nothing on a cache
+ * hit (best of 5, width 76). 16 KB is roughly a screenful at every terminal size
+ * and still ~30x the 500 characters this replaces, which was small enough to cut
+ * most real results mid-sentence.
+ */
+export const RESULT_MAX_CHARS = 16_000
+
+/** Cycle order for the viewer's `m` key. */
+const MARKDOWN_MODES: readonly ViewerMarkdownMode[] = [
+  "off",
+  "assistant",
+  "all",
+]
+
+/** Footer labels — short, because the idle footer is already full at 80 columns. */
+const MARKDOWN_MODE_LABELS: Record<ViewerMarkdownMode, string> = {
+  off: "raw",
+  assistant: "md",
+  all: "md+",
+}
+
+/**
+ * Both options keep the renderer from *rewriting* source that only looks like
+ * Markdown: without them `3) a / 7) b / 9) c` comes back renumbered `3. 4. 5.`
+ * and backslash escapes are normalized away. Neither is a safe edit to make to
+ * a tool's output, and both are cheap to switch off.
+ */
+const MARKDOWN_OPTIONS: MarkdownOptions = {
+  preserveOrderedListMarkers: true,
+  preserveBackslashEscapes: true,
+}
+
+/**
+ * Pi's own Markdown theme when this process has one, else a theme built from the
+ * viewer's `Theme`.
+ *
+ * Preferring pi's is what buys syntax-highlighted code fences (it carries a
+ * `highlightCode`), and it keeps this surface consistent with the notification
+ * renderer, which uses the same source. It has to be *probed* rather than
+ * try/caught around the call: `getMarkdownTheme()` returns arrow functions that
+ * read pi's global theme lazily, so an uninitialized theme throws inside
+ * `render()` — long after this returns — and takes the overlay with it. That is
+ * the case in tests and any embedded session that never called `initTheme()`.
+ */
+function resolveMarkdownTheme(th: Theme): MarkdownTheme {
+  try {
+    const piTheme = getMarkdownTheme()
+    piTheme.heading("probe")
+    return piTheme
+  } catch {
+    return fallbackMarkdownTheme(th)
+  }
+}
+
+/**
+ * `Theme` carries only `fg` and `bold`, so the three remaining styles are
+ * written as raw SGR. Rendering them as plain text instead would silently drop
+ * `*emphasis*`'s markers with nothing in their place, turning a formatting
+ * change into a content change.
+ */
+function fallbackMarkdownTheme(th: Theme): MarkdownTheme {
+  const sgr = (on: number, off: number) => (text: string) =>
+    `\x1b[${on}m${text}\x1b[${off}m`
+  return {
+    heading: (text) => th.bold(th.fg("accent", text)),
+    link: (text) => th.fg("accent", text),
+    linkUrl: (text) => th.fg("muted", text),
+    code: (text) => th.fg("muted", text),
+    codeBlock: (text) => th.fg("muted", text),
+    codeBlockBorder: (text) => th.fg("dim", text),
+    quote: (text) => th.fg("muted", text),
+    quoteBorder: (text) => th.fg("dim", text),
+    hr: (text) => th.fg("dim", text),
+    listBullet: (text) => th.fg("accent", text),
+    bold: (text) => th.bold(text),
+    italic: sgr(3, 23),
+    underline: sgr(4, 24),
+    strikethrough: sgr(9, 29),
+  }
+}
+
+/**
+ * Cap `text` at `RESULT_MAX_CHARS`, reporting the elision separately rather than
+ * appending it.
+ *
+ * Separately because the notice is the viewer's chrome, not the tool's output.
+ * Appended into the string it becomes content: a cut landing inside a fenced
+ * code block — likely, on exactly the large `ctx_execute` results this is for —
+ * renders the notice as a line of source inside the fence.
+ */
+function capResult(text: string): { text: string; elided: number } {
+  if (text.length <= RESULT_MAX_CHARS) return { text, elided: 0 }
+  return {
+    text: text.slice(0, RESULT_MAX_CHARS),
+    elided: text.length - RESULT_MAX_CHARS,
+  }
+}
+
+function truncationNote(elided: number): string {
+  return `... (truncated, ${elided} more character${elided === 1 ? "" : "s"})`
+}
+
 export class ConversationViewer implements Component {
   private scrollOffset = 0
   private autoScroll = true
@@ -57,6 +171,20 @@ export class ConversationViewer implements Component {
   private keys: ViewerKeys
   /** Steering composer — present while the user is typing a message to the agent. */
   private composer: Input | undefined
+  /** Resolved once: pi's Markdown theme is fixed for the life of the process. */
+  private readonly markdownTheme: MarkdownTheme
+  /** Set by the `m` key. Wins over the setting so `m` works without a persist hook. */
+  private markdownModeOverride: ViewerMarkdownMode | undefined
+  /**
+   * One `Markdown` per message, so its own text/width cache does the work. A
+   * fresh instance per render would re-parse the whole transcript on every
+   * keystroke — the component caches, but only across calls to the same object.
+   * Weak so a compacted-away message doesn't pin its render.
+   */
+  private readonly markdownCache = new WeakMap<
+    object,
+    { md: Markdown; text: string; failed?: boolean }
+  >()
 
   constructor(
     private tui: TUI,
@@ -77,7 +205,19 @@ export class ConversationViewer implements Component {
      * cannot change while it is on screen.
      */
     private showCost = false,
+    /**
+     * The current `viewerMarkdown` setting. Read live rather than captured,
+     * unlike `showCost`: `m` changes it while the overlay is on screen.
+     * Omitted → `assistant`.
+     */
+    private viewerMarkdown?: () => ViewerMarkdownMode,
+    /**
+     * Persist a mode chosen with `m`, so the key and `/agents → Settings` mean
+     * the same thing. Omitted → `m` still cycles, viewer-locally.
+     */
+    private onMarkdownMode?: (mode: ViewerMarkdownMode) => void,
   ) {
+    this.markdownTheme = resolveMarkdownTheme(theme)
     this.keys = createViewerKeys(keybindings)
     this.unsubscribe = session.subscribe(() => {
       if (this.closed) return
@@ -127,6 +267,22 @@ export class ConversationViewer implements Component {
       }
       return
     }
+
+    // Cycle raw → assistant-only → everything. The escape hatch that makes
+    // Markdown rendering safe to default on: a result the renderer reshapes
+    // (a diff, an indented log, a `#`-commented script) is one key from verbatim.
+    if (matchesKey(data, "m")) {
+      this.stopArmed = false
+      const next =
+        MARKDOWN_MODES[
+          (MARKDOWN_MODES.indexOf(this.markdownMode()) + 1) %
+            MARKDOWN_MODES.length
+        ]
+      this.markdownModeOverride = next
+      this.onMarkdownMode?.(next)
+      this.tui.requestRender()
+      return
+    }
     if (this.stopArmed) this.stopArmed = false
 
     const totalLines = this.buildContentLines(this.lastInnerW).length
@@ -268,6 +424,12 @@ export class ConversationViewer implements Component {
             : th.fg("dim", "x stop"),
         )
       }
+      // Abbreviated (`raw`/`md`/`md+`) because the idle footer is already full
+      // at 80 columns with steer + stop present, and this group has no
+      // degradation step below "drop the line-count readout".
+      actions.push(
+        th.fg("dim", `m ${MARKDOWN_MODE_LABELS[this.markdownMode()]}`),
+      )
       const footerRight = th.fg(
         "dim",
         "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close",
@@ -305,6 +467,67 @@ export class ConversationViewer implements Component {
     )
   }
 
+  /** The mode in force: an `m` press, else the setting, else the default. */
+  private markdownMode(): ViewerMarkdownMode {
+    return this.markdownModeOverride ?? this.viewerMarkdown?.() ?? "assistant"
+  }
+
+  /** Wrap `text` literally — the pre-Markdown path, and the fallback from it. */
+  private rawLines(text: string, width: number, dim: boolean): string[] {
+    const lines = wrapTextWithAnsi(text, width)
+    return dim ? lines.map((l) => this.theme.fg("dim", l)) : lines
+  }
+
+  /** Render `text` as Markdown, reusing this message's component instance. */
+  private markdownLines(
+    msg: AgentSession["messages"][number],
+    text: string,
+    width: number,
+    dim: boolean,
+  ): string[] {
+    let entry = this.markdownCache.get(msg)
+    if (!entry) {
+      entry = {
+        md: new Markdown(
+          text,
+          0,
+          0,
+          this.markdownTheme,
+          // Keeps result prose visually receded, the way the raw path's
+          // per-line `fg("dim", …)` did. Fenced code is the exception and is
+          // left alone deliberately: pi's theme highlights it with its own
+          // colors, which this would otherwise flatten.
+          dim ? { color: (t: string) => this.theme.fg("dim", t) } : undefined,
+          MARKDOWN_OPTIONS,
+        ),
+        text,
+      }
+      this.markdownCache.set(msg, entry)
+    } else if (entry.text !== text) {
+      // Streaming: the message object is stable, its text grows. A failed
+      // prefix remains unsafe after append-only deltas, so retry only when the
+      // content was replaced or truncated.
+      const shouldRetry = !text.startsWith(entry.text)
+      entry.md.setText(text)
+      entry.text = text
+      if (shouldRetry) entry.failed = false
+    }
+    if (entry.failed) return this.rawLines(text, width, dim)
+
+    try {
+      return entry.md.render(width)
+    } catch {
+      // The parser is recursive and this is arbitrary tool output: ~54 nested
+      // blockquotes overflow the stack, and no amount of fuzzing proves that is
+      // the only such input. `render()` is on the TUI's critical path, so a
+      // throw here takes the overlay down for content the literal path shows
+      // fine — degrade to that instead, and remember, since the throw would
+      // otherwise repeat on every render and every scroll key.
+      entry.failed = true
+      return this.rawLines(text, width, dim)
+    }
+  }
+
   /** Steerable only when a steer handler exists and the agent is still active. */
   private canSteer(): boolean {
     return (
@@ -364,8 +587,14 @@ export class ConversationViewer implements Component {
   }
 
   private invocationLine(): string | undefined {
-    const { modelName, tags } = buildInvocationTags(this.record.invocation)
-    const parts = modelName ? [modelName, ...tags] : tags
+    // Canonical id here, short label everywhere else: this overlay is opened to
+    // inspect one agent and has the width for it, and two providers can serve
+    // models whose short names read alike.
+    const { modelName, modelId, tags } = buildInvocationTags(
+      this.record.invocation,
+    )
+    const model = modelId ?? modelName
+    const parts = model ? [model, ...tags] : tags
     if (parts.length === 0) return undefined
     return this.theme.fg("dim", `  ↳ ${parts.join(" · ")}`)
   }
@@ -382,6 +611,7 @@ export class ConversationViewer implements Component {
       return lines
     }
 
+    const mode = this.markdownMode()
     let needsSeparator = false
     for (const msg of messages) {
       if (msg.role === "user") {
@@ -407,12 +637,12 @@ export class ConversationViewer implements Component {
         if (needsSeparator) lines.push(th.fg("dim", "───"))
         lines.push(th.bold("[Assistant]"))
         if (textParts.length > 0) {
-          for (const line of wrapTextWithAnsi(
-            textParts.join("\n").trim(),
-            width,
-          )) {
-            lines.push(line)
-          }
+          const text = textParts.join("\n").trim()
+          lines.push(
+            ...(mode === "off"
+              ? this.rawLines(text, width, false)
+              : this.markdownLines(msg, text, width, false)),
+          )
         }
         for (const name of toolCalls) {
           lines.push(
@@ -420,15 +650,19 @@ export class ConversationViewer implements Component {
           )
         }
       } else if (msg.role === "toolResult") {
-        const text = extractText(msg.content)
-        const truncated =
-          text.length > 500 ? text.slice(0, 500) + "... (truncated)" : text
-        if (!truncated.trim()) continue
+        const { text, elided } = capResult(extractText(msg.content).trim())
+        if (!text) continue
         if (needsSeparator) lines.push(th.fg("dim", "───"))
         lines.push(th.fg("dim", "[Result]"))
-        for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
-          lines.push(th.fg("dim", line))
-        }
+        lines.push(
+          ...(mode === "all"
+            ? this.markdownLines(msg, text, width, true)
+            : this.rawLines(text, width, true)),
+        )
+        if (elided)
+          lines.push(
+            truncateToWidth(th.fg("dim", truncationNote(elided)), width),
+          )
       } else if ((msg as any).role === "bashExecution") {
         const bash = msg as any
         if (needsSeparator) lines.push(th.fg("dim", "───"))
@@ -436,13 +670,14 @@ export class ConversationViewer implements Component {
           truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width),
         )
         if (bash.output?.trim()) {
-          const out =
-            bash.output.length > 500
-              ? bash.output.slice(0, 500) + "... (truncated)"
-              : bash.output
-          for (const line of wrapTextWithAnsi(out.trim(), width)) {
-            lines.push(th.fg("dim", line))
-          }
+          // Same cap as a tool result, never Markdown: command output is the one
+          // thing here that is definitionally not authored as Markdown.
+          const { text, elided } = capResult(bash.output.trim())
+          lines.push(...this.rawLines(text, width, true))
+          if (elided)
+            lines.push(
+              truncateToWidth(th.fg("dim", truncationNote(elided)), width),
+            )
         }
       } else {
         continue