@xingular/harness 0.1.6 → 2.0.0

package/src/terminal/tui/tools.ts

@@ -0,0 +1,142 @@
+/**
+ * Presentation adapted from @oh-my-pi/pi-tui 18.11.3 tools/default-renderer.ts
+ * and tools/json-tree.ts (MIT, Mario Zechner, Can Bölük and Stencil Labs, Inc.).
+ * See NOTICE.md for the upstream license. Execution remains owned by Pi.
+ */
+import type { Theme, ToolRenderers } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, truncateToWidth, type Component } from '@earendil-works/pi-tui'
+
+type CallContext = Parameters<NonNullable<ToolRenderers['renderCall']>>[2]
+
+const hiddenArgs = new Set(['__partialJson'])
+
+/** Permit color and emphasis, but never replay terminal commands from a tool result. */
+function outputText(value: string): string {
+  return value.split(/(\x1b\[[0-9;:]*m)/g).map((part, index) => index % 2
+    ? part
+    : stripTerminalSequences(part).replace(/\t/g, '    ').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '')).join('')
+}
+
+function label(value: string): string {
+  return stripTerminalSequences(value).replace(/[\x00-\x1f\x7f]/g, ' ')
+}
+
+function scalar(value: unknown, width: number): string {
+  const text = typeof value === 'string'
+    ? JSON.stringify(stripTerminalSequences(value))
+    : value === null ? 'null'
+      : Array.isArray(value) ? `[${value.length} items]`
+        : typeof value === 'object' ? `{${Object.keys(value).length} keys}`
+          : String(value)
+  return truncateToWidth(text, Math.max(0, width))
+}
+
+function entries(value: unknown): [string, unknown][] {
+  return value && typeof value === 'object'
+    ? Object.entries(value).filter(([key]) => !hiddenArgs.has(key))
+    : []
+}
+
+function argsInline(args: unknown, width: number): string {
+  return truncateToWidth(entries(args).map(([key, value]) => `${label(key)}=${scalar(value, 24)}`).join(', '), width)
+}
+
+/** Bounded depth and row budgets keep large structured results responsive. */
+function tree(value: unknown, expanded: boolean, theme: Theme, width: number): string[] {
+  const maxDepth = expanded ? 6 : 2
+  const maxLines = expanded ? 200 : 6
+  const maxScalar = expanded ? 2000 : 60
+  const lines: string[] = []
+  const ancestors = new Set<object>()
+  let clipped = false
+  function visit(item: unknown, indent: string, key: string | undefined, last: boolean, depth: number): void {
+    if (lines.length >= maxLines) { clipped = true; return }
+    const branch = last ? '└─' : '├─'
+    const keyText = key === undefined ? '' : `${label(key)}: `
+    const compound = item !== null && typeof item === 'object'
+    const repeated = compound && ancestors.has(item)
+    const row = `${indent}${theme.fg('dim', branch)} ${keyText}${scalar(item, maxScalar)}${repeated ? ' [circular]' : ''}`
+    lines.push(truncateToWidth(theme.fg('toolOutput', row), width))
+    if (!compound || repeated || depth >= maxDepth) return
+    const children = entries(item)
+    ancestors.add(item)
+    for (let index = 0; index < children.length; index++) {
+      if (lines.length >= maxLines) { clipped = true; break }
+      const [childKey, child] = children[index]
+      visit(child, indent + (last ? '   ' : '│  '), childKey, index === children.length - 1, depth + 1)
+    }
+    ancestors.delete(item)
+  }
+  const roots = entries(value)
+  if (roots.length) {
+    for (let index = 0; index < roots.length; index++) {
+      if (lines.length >= maxLines) { clipped = true; break }
+      const [key, item] = roots[index]
+      visit(item, '', key, index === roots.length - 1, 0)
+    }
+  } else visit(value, '', undefined, true, 0)
+  if (clipped) lines.push(theme.fg('dim', truncateToWidth('…', width)))
+  return lines
+}
+
+function status(context: CallContext, theme: Theme): string {
+  if (context.isPartial) return context.executionStarted ? theme.fg('accent', '⟳') : theme.fg('muted', '⏳')
+  return context.isError ? theme.fg('error', '✘') : theme.fg('success', '•')
+}
+
+function widthComponent(render: (width: number) => string[]): Component {
+  return {
+    invalidate() {},
+    render(width) {
+      const columns = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0
+      if (columns === 0) return []
+      return render(columns).map(line => truncateToWidth(line, columns))
+    }
+  }
+}
+
+/**
+ * A resolver supplies display hooks only. Existing renderers include richer file,
+ * diff, image and plugin-specific evidence; next() is authoritative for them.
+ * Pi owns its default Box(1, 1), lifecycle background and image rendering.
+ */
+export function harnessToolRenderers(toolName: string, next: () => ToolRenderers | undefined): ToolRenderers | undefined {
+  const downstream = next()
+  if (downstream?.renderCall || downstream?.renderResult || downstream?.renderShell === 'self') return downstream
+  return {
+    renderShell: 'default',
+    renderCall(args, theme, context) {
+      return widthComponent(width => {
+        const lines = [`${status(context, theme)} ${theme.fg('accent', label(toolName))}`]
+        if (context.expanded && args !== undefined) {
+          lines.push('', theme.fg('dim', 'Args'), ...tree(args, true, theme, width), '')
+        } else {
+          const summary = argsInline(args, Math.max(0, width - 5))
+          if (summary) lines.push(` ${theme.fg('dim', `└─ ${summary}`)}`)
+        }
+        return lines
+      })
+    },
+    renderResult(result, options, theme) {
+      return widthComponent(width => {
+        const content = result.content.filter(part => part.type === 'text').map(part => part.text).join('\n').trimEnd()
+        if (!content) return [theme.fg('dim', result.content.some(part => part.type === 'image') ? '(image output)' : '(no output)')]
+        if (/^[\[{]/.test(content)) {
+          try {
+            const lines = tree(JSON.parse(content), options.expanded, theme, width)
+            if (!options.expanded) lines.push(theme.fg('dim', '[Ctrl+O: Expand]'))
+            return lines
+          } catch {
+            // A text result starting with '[' is still a text result when it is not JSON.
+          }
+        }
+        const source = outputText(content).split('\n')
+        const cap = options.expanded ? 12 : 4
+        const shown = source.slice(0, cap).map(line => theme.fg('toolOutput', line))
+        if (source.length > cap) shown.push(theme.fg('dim', `… (${source.length - cap} more lines)`))
+        if (!options.expanded) shown.push(theme.fg('dim', '[Ctrl+O: Expand]'))
+        return shown
+      })
+    }
+  }
+}

package/src/terminal/tui/trajectoryPanel.test.ts

@@ -0,0 +1,99 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, visibleWidth, type TUI } from '@earendil-works/pi-tui'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { RunEvent } from '../../sessions/contracts'
+import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
+import { TrajectoryPanel } from './trajectoryPanel'
+import { createHarnessTheme } from './theme'
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const run = (id: string, status = 'completed'): TerminalTrajectoryRun => ({
+  id, mode: 'code', goal: `Goal for ${id}`, startedAt: '2026-10-18T00:00:00.000Z', endedAt: status === 'running' ? null : '2026-10-18T00:00:02.000Z', status
+})
+const event = (sequence: number, type: string, payload: unknown): RunEvent => ({
+  id: `event-${sequence}`, runId: 'run-1', sessionId: 'terminal-1', sequence,
+  timestamp: `2026-10-18T00:00:0${sequence}.000Z`, type: type as RunEvent['type'], payload
+})
+function setup(options: { runs?: TerminalTrajectoryRun[]; snapshot?: TerminalTrajectorySnapshot; read?: (runId: string, afterSequence?: number) => Promise<TerminalTrajectorySnapshot>; rows?: number } = {}) {
+  const events = [
+    event(0, 'context.snapshot', { systemPrompt: 'prompt', tools: [{ name: 'read' }] }),
+    event(1, 'tool.started', { toolCallId: 'tool-1', name: 'read', input: '{"path":"README.md"}' }),
+    event(2, 'tool.completed', { toolCallId: 'tool-1', name: 'read', output: 'file contents', ok: true })
+  ]
+  const runs = options.runs ?? [run('run-1')]
+  const initial = options.snapshot ?? { run: runs[0]!, events }
+  const read = options.read ?? vi.fn(async () => initial)
+  const copy = vi.fn(async (_text: string) => {})
+  const changed = vi.fn()
+  const notify = vi.fn()
+  const close = vi.fn()
+  const panel = new TrajectoryPanel({
+    tui: { terminal: { rows: options.rows ?? 28 } } as unknown as TUI,
+    theme, runs, initialIndex: 0, initial, read, copy, changed, notify, close
+  })
+  return { panel, events, runs, read, copy, changed, notify, close }
+}
+
+afterEach(() => vi.useRealTimers())
+
+describe('the terminal Trajectory panel', () => {
+  it('shows run usage, a selectable event ledger, and the selected event payload', () => {
+    const { panel } = setup()
+    const text = panel.render(100).map(stripTerminalSequences).join('\n')
+    expect(text).toContain('Run 1/1 · run-1 · completed')
+    expect(text).toContain('context.snapshot')
+    expect(text).toContain('tool.completed')
+    expect(text).toContain('file contents')
+    expect(panel.selectedEvent?.sequence).toBe(2)
+
+    panel.handleInput('\x1b[A')
+    expect(panel.selectedEvent?.sequence).toBe(1)
+    expect(panel.render(100).map(stripTerminalSequences).join('\n')).toContain('README.md')
+  })
+
+  it('moves between runs, closes, and copies the selected event', async () => {
+    const first = run('run-1')
+    const second = run('run-2')
+    const secondSnapshot = { run: second, events: [event(0, 'message.completed', { role: 'assistant', text: 'Second run' })] }
+    const { panel, read, copy, close } = setup({ runs: [first, second], read: vi.fn(async (id) => id === 'run-2' ? secondSnapshot : { run: first, events: [] }) })
+    panel.handleInput('\x1b[D')
+    await vi.waitFor(() => expect(panel.selectedRunId).toBe('run-2'))
+    expect(read).toHaveBeenCalledWith('run-2')
+    expect(panel.selectedEvent?.type).toBe('message.completed')
+    panel.handleInput('c')
+    await vi.waitFor(() => expect(copy).toHaveBeenCalledOnce())
+    expect(JSON.parse(copy.mock.calls[0]![0])).toMatchObject({ type: 'message.completed', sequence: 0 })
+    panel.handleInput('\x1b')
+    expect(close).toHaveBeenCalledOnce()
+    panel.dispose()
+  })
+
+  it('refreshes active runs and stops polling when disposed', async () => {
+    vi.useFakeTimers()
+    const active = run('run-1', 'running')
+    const completed = run('run-1')
+    const initial = { run: active, events: [event(0, 'started', {})] }
+    const updated = { run: completed, events: [event(1, 'completed', {})] }
+    const read = vi.fn(async (_id: string, afterSequence?: number) => afterSequence === 0 ? updated : initial)
+    const { panel } = setup({ snapshot: initial, read })
+    await vi.advanceTimersByTimeAsync(2_000)
+    expect(read).toHaveBeenCalledWith('run-1', 0)
+    expect(panel.render(100).map(stripTerminalSequences).join('\n')).toContain('completed')
+    const calls = read.mock.calls.length
+    panel.dispose()
+    await vi.advanceTimersByTimeAsync(4_000)
+    expect(read).toHaveBeenCalledTimes(calls)
+  })
+
+  it('bounds output to narrow terminals and handles runs without recorded events', () => {
+    const { panel } = setup({ snapshot: { run: run('run-1'), events: [] }, rows: 10 })
+    const rows = panel.render(24)
+    expect(rows.length).toBeLessThanOrEqual(5)
+    for (const row of rows) expect(visibleWidth(row)).toBeLessThanOrEqual(24)
+    expect(rows.map(stripTerminalSequences).join('\n')).toContain('No recorded events')
+    panel.handleInput('\x1b[B')
+    expect(panel.selectedEvent).toBeUndefined()
+    panel.dispose()
+  })
+})

package/src/terminal/tui/trajectoryPanel.ts

@@ -0,0 +1,226 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { matchesKey, stripTerminalSequences, truncateToWidth, wrapTextWithAnsi, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui'
+
+import type { RunEvent } from '../../sessions/contracts'
+import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
+
+const ACTIVE = new Set(['queued', 'running', 'waiting_for_approval', 'waiting_for_input'])
+type Payload = Record<string, unknown>
+
+const payloadOf = (event: RunEvent): Payload => event.payload && typeof event.payload === 'object' ? event.payload as Payload : {}
+const stringOf = (value: unknown): string | undefined => typeof value === 'string' ? value : undefined
+const numberOf = (value: unknown): number | undefined => typeof value === 'number' && Number.isFinite(value) ? value : undefined
+
+function safe(value: string): string {
+  return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ')
+}
+
+function timeOf(value: string): string {
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? new Date(parsed).toLocaleTimeString() : value
+}
+
+function eventDescription(event: RunEvent): string {
+  const payload = payloadOf(event)
+  switch (event.type) {
+    case 'message.completed':
+    case 'message.delta':
+      return `${stringOf(payload.role) ?? 'message'}: ${stringOf(payload.text)?.replace(/\s+/g, ' ').slice(0, 90) ?? ''}`
+    case 'tool.started':
+    case 'tool.completed':
+      return `${stringOf(payload.name) ?? 'tool'}${stringOf(payload.summary) ? ` · ${stringOf(payload.summary)}` : ''}`
+    case 'usage.updated': {
+      const request = payload.request && typeof payload.request === 'object' ? payload.request as Payload : {}
+      return `${stringOf(request.model) ?? stringOf(payload.model) ?? 'model'} · request ${numberOf(request.index) ?? numberOf(payload.requests) ?? '?'} · ${numberOf(request.durationMs) ?? 0} ms`
+    }
+    case 'status.changed':
+      return stringOf(payload.status) ?? 'status update'
+    case 'retry.started':
+    case 'retry.ended':
+      return `attempt ${numberOf(payload.attempt) ?? 1}${stringOf(payload.error) ? ` · ${stringOf(payload.error)}` : ''}`
+    case 'compaction.started':
+    case 'compaction.ended':
+      return stringOf(payload.reason) ?? 'context compaction'
+    case 'extension.notice':
+      return stringOf(payload.text) ?? 'extension notice'
+    case 'context.snapshot':
+      return 'Recorded prompt and tool definitions'
+    case 'failed':
+      return stringOf(payload.message) ?? stringOf(payload.code) ?? 'run failed'
+    default:
+      return stringOf(payload.text) ?? stringOf(payload.name) ?? ''
+  }
+}
+
+function usageLine(events: readonly RunEvent[]): string {
+  const event = [...events].reverse().find(item => item.type === 'usage.updated')
+  if (!event) return 'Usage not recorded'
+  const payload = payloadOf(event)
+  const tokens = (name: string) => numberOf(payload[name])?.toLocaleString() ?? '—'
+  const cost = numberOf(payload.costUsd)
+  const requests = numberOf(payload.requests)
+  return `Input ${tokens('inputTokens')} · Output ${tokens('outputTokens')} · Cache read ${tokens('cacheReadTokens')} · ${requests ?? 0} requests · ${cost === undefined ? 'cost —' : `$${cost.toFixed(4)}`}`
+}
+
+function durationLine(run: TerminalTrajectoryRun): string {
+  const start = Date.parse(run.startedAt)
+  const end = run.endedAt ? Date.parse(run.endedAt) : Date.now()
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return run.startedAt
+  return `${((Math.max(0, end - start)) / 1000).toFixed(1)} s · ${timeOf(run.startedAt)}`
+}
+
+export interface TrajectoryPanelOptions {
+  tui: TUI
+  theme: Theme
+  runs: TerminalTrajectoryRun[]
+  initialIndex: number
+  initial: TerminalTrajectorySnapshot
+  read(runId: string, afterSequence?: number): Promise<TerminalTrajectorySnapshot>
+  copy(text: string): Promise<void>
+  close(): void
+  changed(): void
+  notify(message: string, type?: string): void
+}
+
+/** Read-only view of saved run evidence, scoped by its source before it reaches this component. */
+export class TrajectoryPanel implements Component, Focusable {
+  private runIndex: number
+  private run: TerminalTrajectoryRun
+  private events: RunEvent[]
+  private selected = 0
+  private detailOffset = 0
+  private focusedValue = false
+  private loading = false
+  private disposed = false
+  private timer: ReturnType<typeof setInterval>
+  private error?: string
+
+  constructor(private readonly options: TrajectoryPanelOptions) {
+    this.runIndex = Math.max(0, Math.min(options.runs.length - 1, options.initialIndex))
+    this.run = options.initial.run
+    this.events = options.initial.events.slice().sort((left, right) => left.sequence - right.sequence)
+    this.selected = Math.max(0, this.events.length - 1)
+    this.timer = setInterval(() => { void this.refresh() }, 2_000)
+    this.timer.unref?.()
+  }
+
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value }
+  get selectedRunId(): string { return this.run.id }
+  get selectedEvent(): RunEvent | undefined { return this.events[this.selected] }
+
+  invalidate(): void { this.options.changed() }
+
+  private async refresh(): Promise<void> {
+    if (this.disposed || this.loading || !ACTIVE.has(this.run.status)) return
+    this.loading = true
+    const lastSequence = this.events.at(-1)?.sequence
+    const followedLatest = this.selected === this.events.length - 1
+    try {
+      const snapshot = await this.options.read(this.run.id, lastSequence)
+      if (this.disposed) return
+      this.run = snapshot.run
+      if (lastSequence === undefined) this.events = snapshot.events.slice().sort((left, right) => left.sequence - right.sequence)
+      else {
+        const existing = new Set(this.events.map(event => event.sequence))
+        this.events = [...this.events, ...snapshot.events.filter(event => !existing.has(event.sequence))].sort((left, right) => left.sequence - right.sequence)
+      }
+      if (followedLatest && this.events.length) this.selected = this.events.length - 1
+      this.error = undefined
+    } catch (error) {
+      if (!this.disposed) this.error = error instanceof Error ? error.message : String(error)
+    } finally {
+      this.loading = false
+      if (!this.disposed) this.options.changed()
+    }
+  }
+
+  private async changeRun(direction: -1 | 1): Promise<void> {
+    const next = this.runIndex + direction
+    if (next < 0 || next >= this.options.runs.length || this.loading) return
+    this.runIndex = next
+    this.run = this.options.runs[next]!
+    this.events = []
+    this.selected = 0
+    this.detailOffset = 0
+    this.error = undefined
+    this.options.changed()
+    this.loading = true
+    try {
+      const snapshot = await this.options.read(this.run.id)
+      if (this.disposed || this.run.id !== snapshot.run.id) return
+      this.run = snapshot.run
+      this.events = snapshot.events.slice().sort((left, right) => left.sequence - right.sequence)
+      this.selected = Math.max(0, this.events.length - 1)
+    } catch (error) {
+      if (!this.disposed) this.error = error instanceof Error ? error.message : String(error)
+    } finally {
+      this.loading = false
+      if (!this.disposed) this.options.changed()
+    }
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) { this.options.close(); return }
+    if (matchesKey(data, 'left')) { void this.changeRun(1); return }
+    if (matchesKey(data, 'right')) { void this.changeRun(-1); return }
+    if (matchesKey(data, 'up')) { this.selected = Math.max(0, this.selected - 1); this.detailOffset = 0; this.options.changed(); return }
+    if (matchesKey(data, 'down')) { this.selected = this.events.length ? Math.min(this.events.length - 1, this.selected + 1) : 0; this.detailOffset = 0; this.options.changed(); return }
+    if (matchesKey(data, 'pageUp')) { this.detailOffset = Math.max(0, this.detailOffset - 8); this.options.changed(); return }
+    if (matchesKey(data, 'pageDown')) { this.detailOffset += 8; this.options.changed(); return }
+    if (data.toLowerCase() === 'c' && this.selectedEvent) {
+      const text = JSON.stringify(this.selectedEvent, null, 2)
+      void this.options.copy(text).then(() => this.options.notify('Copied selected trajectory event')).catch(error => this.options.notify(String(error), 'error'))
+    }
+  }
+
+  render(width: number): string[] {
+    width = Math.max(0, Math.trunc(width))
+    const bodyRows = Math.max(0, Math.floor(this.options.tui.terminal.rows * 0.8) - 3)
+    if (!width || !bodyRows) return []
+    const { theme } = this.options
+    const runPosition = `${this.runIndex + 1}/${this.options.runs.length}`
+    const modelEvent = [...this.events].reverse().find(event => event.type === 'usage.updated')
+    const usage = modelEvent ? payloadOf(modelEvent) : {}
+    const model = stringOf(usage.model) ?? 'model unavailable'
+    const lines = [theme.bold(theme.fg('accent', `Run ${runPosition} · ${this.run.id} · ${this.run.status}${this.loading ? ' · loading' : ''}`))]
+    if (bodyRows >= 9) {
+      lines.push(theme.fg('muted', `${model} · ${durationLine(this.run)} · ${this.run.mode}`))
+      lines.push(theme.fg('muted', usageLine(this.events)))
+      lines.push(this.run.goal ? theme.fg('dim', `Prompt: ${this.run.goal.replace(/\s+/g, ' ').slice(0, 140)}`) : theme.fg('dim', 'Prompt text unavailable'))
+    } else if (bodyRows >= 6) {
+      lines.push(theme.fg('muted', `${model} · ${durationLine(this.run)}`))
+    }
+
+    lines.push(theme.bold('Events'))
+    if (this.error) lines.push(theme.fg('error', `Read error: ${this.error}`))
+    if (!this.events.length) lines.push(theme.fg('dim', this.loading ? 'Loading recorded events…' : 'No recorded events'))
+    const structural = lines.length + 2
+    const available = Math.max(0, bodyRows - structural - 1)
+    const ledgerBudget = this.events.length ? Math.min(this.events.length, Math.max(1, Math.floor(available * 0.4))) : 0
+    const detailBudget = Math.max(0, available - ledgerBudget)
+    const firstEvent = Math.max(0, Math.min(this.events.length - ledgerBudget, this.selected - Math.floor(ledgerBudget / 2)))
+    for (let offset = 0; offset < ledgerBudget; offset++) {
+      const index = firstEvent + offset
+      const event = this.events[index]!
+      const prefix = index === this.selected ? '❯' : ' '
+      const label = `${prefix} ${timeOf(event.timestamp)}  ${event.type}  ${eventDescription(event)}`
+      lines.push(index === this.selected ? theme.bg('selectedBg', theme.fg('text', label)) : theme.fg('muted', label))
+    }
+
+    const selected = this.selectedEvent
+    lines.push(theme.bold(selected ? `Selected event · ${selected.type} · #${selected.sequence}` : 'Selected event'))
+    if (selected) {
+      const details = wrapTextWithAnsi(safe(JSON.stringify({ payload: selected.payload, type: selected.type, sequence: selected.sequence, timestamp: selected.timestamp }, null, 2)), width)
+      const maxOffset = Math.max(0, details.length - detailBudget)
+      this.detailOffset = Math.min(this.detailOffset, maxOffset)
+      lines.push(...details.slice(this.detailOffset, this.detailOffset + detailBudget).map(line => theme.fg('dim', line)))
+    }
+    return lines.slice(0, bodyRows).map(line => truncateToWidth(line, width, ''))
+  }
+
+  dispose(): void {
+    this.disposed = true
+    clearInterval(this.timer)
+  }
+}

package/src/terminal/tui/transcript.test.ts

@@ -0,0 +1,39 @@
+import type { AgentSession, Theme } from '@earendil-works/pi-coding-agent'
+import type { TUI } from '@earendil-works/pi-tui'
+import { expect, it, vi } from 'vitest'
+import { TerminalTranscript } from './transcript'
+import { createHarnessTheme } from './theme'
+
+it('detaches all custom transcript components before their session is invalidated', () => {
+  const first = { render: () => ['first'], invalidate() {}, dispose: vi.fn(() => { throw new Error('plugin cleanup failed') }) }
+  const second = { render: () => ['second'], invalidate() {}, dispose: vi.fn() }
+  const session = {
+    settingsManager: { getHideThinkingBlock: () => false },
+    sessionManager: { buildSessionProjection: () => ({ entries: [first, second].map((_, index) => ({ sourceEntry: { type: 'custom', customType: String(index) }, messages: [] })) }) },
+    extensionRunner: { getEntryRenderer: (name: string) => () => [first, second][Number(name)] }
+  } as unknown as AgentSession
+  const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+  const transcript = new TerminalTranscript({} as TUI, () => theme, () => undefined)
+  transcript.bind(session)
+  expect(transcript.render(80)).toEqual(['first', 'second'])
+  transcript.clearSession()
+  expect(first.dispose).toHaveBeenCalledOnce()
+  expect(second.dispose).toHaveBeenCalledOnce()
+  expect(transcript.render(80)).toEqual([])
+  transcript.clearSession()
+  expect(second.dispose).toHaveBeenCalledOnce()
+})
+
+it('keeps notices in the conversation order and drops them with the session', () => {
+  const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+  const transcript = new TerminalTranscript({} as TUI, () => theme, () => undefined)
+  transcript.notice('Plan mode: only read-only tools are available.', 'info')
+  transcript.notice('Plan mode could not start.', 'error')
+  transcript.notice('Plan mode could not start.', 'error')
+  const lines = transcript.render(80).map(line => line.replace(/\x1b\[[0-9;]*m/g, '').trim()).filter(Boolean)
+  expect(lines).toEqual(['Plan mode: only read-only tools are available.', 'Plan mode could not start.'])
+  transcript.notice('Plan mode: only read-only tools are available.', 'info')
+  expect(transcript.render(80).map(line => line.replace(/\x1b\[[0-9;]*m/g, '').trim()).filter(Boolean)).toHaveLength(3)
+  transcript.clearSession()
+  expect(transcript.render(80)).toEqual([])
+})

package/src/terminal/tui/transcript.ts

@@ -0,0 +1,135 @@
+import { AssistantMessageComponent, BranchSummaryMessageComponent, CompactionSummaryMessageComponent, CustomMessageComponent, ToolExecutionComponent, UserMessageComponent, getMarkdownTheme, type AgentSession, type AgentSessionEvent, type Theme, type ToolRenderers } from '@earendil-works/pi-coding-agent'
+import { Container, Text, type Component, type TUI } from '@earendil-works/pi-tui'
+import { harnessToolRenderers } from './tools'
+import type { AgentMessage } from '@earendil-works/pi-agent-core'
+
+type BuiltinRenderers = (name: string, definition: ToolRenderers | undefined) => ToolRenderers | undefined
+
+/** A projection of SDK history/events. This module never executes tools or writes run records. */
+export class TerminalTranscript extends Container {
+  private tools = new Map<string, ToolExecutionComponent>()
+  private assistant?: AssistantMessageComponent
+  private session?: AgentSession
+  private hideThinking = false
+  private expanded = false
+  private hiddenLabel = 'Thinking…'
+  private lastNotice?: { component: Component; text: string; type: string }
+
+  constructor(private readonly tui: TUI, private readonly theme: () => Theme, private readonly builtinRenderers: BuiltinRenderers) { super() }
+
+  clearSession(): void {
+    for (const component of this.children) {
+      try { (component as Component & { dispose?(): void }).dispose?.() } catch { /* Detach every component even when a plugin's cleanup fails. */ }
+    }
+    this.clear()
+    this.tools.clear()
+    this.assistant = undefined
+    this.session = undefined
+  }
+
+  /** A line of terminal feedback, such as a mode change or an error. It sits in the conversation where it happened, not in the session. */
+  notice(text: string, type: string): void {
+    // A failure that repeats with nothing after it, such as a draft that cannot be saved on each keystroke, is shown once.
+    const last = this.lastNotice
+    if (last && last.text === text && last.type === type && this.children.at(-1) === last.component) return
+    const component = new Text(this.theme().fg(type === 'error' ? 'error' : type === 'warning' ? 'warning' : 'muted', text), 1, 1)
+    this.addChild(component)
+    this.lastNotice = { component, text, type }
+  }
+
+  bind(session: AgentSession): void {
+    this.clearSession()
+    this.session = session
+    this.hideThinking = session.settingsManager.getHideThinkingBlock()
+    for (const projected of session.sessionManager.buildSessionProjection().entries) {
+      if (projected.sourceEntry.type === 'custom') {
+        const entry = projected.sourceEntry
+        const component = session.extensionRunner.getEntryRenderer(entry.customType)?.(entry, { expanded: this.expanded }, this.theme())
+        if (component) this.addChild(component)
+      }
+      for (const message of projected.messages) this.message(message, false)
+    }
+  }
+
+  setExpanded(expanded: boolean): void {
+    this.expanded = expanded
+    for (const component of this.children) {
+      if ('setExpanded' in component) (component as Component & { setExpanded(value: boolean): void }).setExpanded(expanded)
+    }
+  }
+
+  setThinking(hidden: boolean, label = this.hiddenLabel): void {
+    if (this.hideThinking === hidden && this.hiddenLabel === label) return
+    this.hideThinking = hidden
+    this.hiddenLabel = label
+    for (const component of this.children) if (component instanceof AssistantMessageComponent) {
+      component.setHideThinkingBlock(hidden)
+      component.setHiddenThinkingLabel(label)
+    }
+  }
+
+  private tool(id: string, name: string, args: unknown): ToolExecutionComponent {
+    let component = this.tools.get(id)
+    if (!component) {
+      const session = this.session!
+      const renderer = harnessToolRenderers(name, () => session.extensionRunner.resolveToolRenderers(name, () => this.builtinRenderers(name, session.getToolDefinition(name))))
+      component = new ToolExecutionComponent(name, id, args, {
+        showImages: session.settingsManager.getShowImages(), imageWidthCells: session.settingsManager.getImageWidthCells(), outputPad: 1
+      }, renderer, this.tui, session.sessionManager.getCwd())
+      component.setExpanded(this.expanded)
+      this.tools.set(id, component)
+      this.addChild(component)
+    } else component.updateArgs(args)
+    return component
+  }
+
+  private message(message: AgentMessage, streaming: boolean): void {
+    const session = this.session!
+    const transformers = session.extensionRunner.getMarkdownTransformers()
+    if (message.role === 'user') {
+      const text = typeof message.content === 'string' ? message.content : message.content.filter(part => part.type === 'text').map(part => part.text).join('\n')
+      const images = typeof message.content === 'string' ? 0 : message.content.filter(part => part.type === 'image').length
+      const content = [text, images ? `[${images} attached image${images === 1 ? '' : 's'}]` : ''].filter(Boolean).join('\n')
+      if (content) this.addChild(new UserMessageComponent(content, getMarkdownTheme(), 1, transformers))
+    } else if (message.role === 'assistant') {
+      const assistant = new AssistantMessageComponent(message, this.hideThinking, getMarkdownTheme(), this.hiddenLabel, 1, transformers)
+      assistant.updateContent(message, streaming)
+      this.addChild(assistant)
+      this.assistant = streaming ? assistant : undefined
+      for (const part of message.content) if (part.type === 'toolCall') {
+        const component = this.tool(part.id, part.name, part.arguments)
+        if (!streaming) component.setArgsComplete()
+        if (message.stopReason === 'error' || message.stopReason === 'aborted') component.updateResult({ content: [{ type: 'text', text: message.errorMessage ?? 'Operation aborted' }], isError: true })
+      }
+    } else if (message.role === 'toolResult') {
+      this.tools.get(message.toolCallId)?.updateResult(message)
+    } else if (message.role === 'custom') {
+      if (message.display) this.addChild(new CustomMessageComponent(message, session.extensionRunner.getMessageRenderer(message.customType), getMarkdownTheme(), 1))
+    } else if (message.role === 'compactionSummary') this.addChild(new CompactionSummaryMessageComponent(message, getMarkdownTheme(), 1))
+    else if (message.role === 'branchSummary') this.addChild(new BranchSummaryMessageComponent(message, getMarkdownTheme(), 1))
+    else if (message.role === 'bashExecution') {
+      this.addChild(new Text(this.theme().fg('muted', `$ ${message.command}\n${message.output}`), 1, 1))
+    }
+  }
+
+  accept(event: AgentSessionEvent): void {
+    if (event.type === 'message_start') this.message(event.message, event.message.role === 'assistant')
+    else if (event.type === 'message_update' && event.message.role === 'assistant') {
+      if (!this.assistant) this.message(event.message, true)
+      else this.assistant.updateContent(event.message, true)
+      for (const part of event.message.content) if (part.type === 'toolCall') this.tool(part.id, part.name, part.arguments)
+    } else if (event.type === 'message_end') {
+      if (event.message.role === 'assistant') {
+        this.assistant?.updateContent(event.message, false)
+        this.assistant = undefined
+        for (const part of event.message.content) if (part.type === 'toolCall') this.tool(part.id, part.name, part.arguments).setArgsComplete()
+      } else if (event.message.role === 'toolResult') this.tools.get(event.message.toolCallId)?.updateResult(event.message)
+    } else if (event.type === 'tool_execution_start') this.tool(event.toolCallId, event.toolName, event.args).markExecutionStarted()
+    else if (event.type === 'tool_execution_update') this.tool(event.toolCallId, event.toolName, event.args).updateResult({ ...event.partialResult, isError: false }, true)
+    else if (event.type === 'tool_execution_end') this.tools.get(event.toolCallId)?.updateResult({ ...event.result, isError: event.isError, durationMs: event.durationMs })
+    else if (event.type === 'entry_appended' && event.entry.type === 'custom') {
+      const component = this.session!.extensionRunner.getEntryRenderer(event.entry.customType)?.(event.entry, { expanded: this.expanded }, this.theme())
+      if (component) this.addChild(component)
+    }
+  }
+}