@xingular/harness 0.1.5 → 0.1.7

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

@@ -0,0 +1,145 @@
+import { createEditToolDefinition, createReadToolDefinition, type Theme, type ToolRenderers } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, visibleWidth } from '@earendil-works/pi-tui'
+import { describe, expect, it, vi } from 'vitest'
+
+import { createHarnessTheme } from './theme'
+import { harnessToolRenderers } from './tools'
+
+type Context = Parameters<NonNullable<ToolRenderers['renderCall']>>[2]
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+function context(overrides: Partial<Context> = {}): Context {
+  return {
+    args: {}, toolCallId: 'test-call', invalidate() {}, lastComponent: undefined,
+    state: {}, cwd: '/private/tmp', executionStarted: false, argsComplete: true,
+    isPartial: true, expanded: false, showImages: true, isError: false,
+    durationMs: undefined, outputPad: 1, ...overrides
+  }
+}
+function generic(name = 'wiki_recall') {
+  return harnessToolRenderers(name, () => undefined)!
+}
+function result(lines: number) {
+  return { content: [{ type: 'text' as const, text: Array.from({ length: lines }, (_, index) => `source line ${index}`).join('\n') }], details: { evidence: 'original' } }
+}
+const plain = (rows: string[]) => rows.map(stripTerminalSequences)
+
+describe('Harness tool presentation', () => {
+  it('resolves display hooks without replacing execution, schemas or the original tool', () => {
+    const execute = vi.fn()
+    const parameters = { type: 'object', properties: { query: { type: 'string' } } }
+    const definition = Object.freeze({ name: 'wiki_recall', parameters, execute, renderShell: 'default' as const })
+    const next = vi.fn(() => definition)
+    const display = harnessToolRenderers('wiki_recall', next)!
+    expect(next).toHaveBeenCalledTimes(1)
+    expect(Object.keys(display).sort()).toEqual(['renderCall', 'renderResult', 'renderShell'])
+    expect(display.renderShell).toBe('default')
+    expect(definition.parameters).toBe(parameters)
+    expect(definition.execute).toBe(execute)
+    expect(execute).not.toHaveBeenCalled()
+  })
+
+  it('respects plugin renderer hooks even when the plugin uses a built-in tool name', () => {
+    for (const name of ['read', 'edit', 'bash', 'wiki_recall']) {
+      for (const hooks of [{ renderCall: vi.fn() }, { renderResult: vi.fn() }, { renderShell: 'self' as const }]) {
+        const next = vi.fn(() => hooks)
+        expect(harnessToolRenderers(name, next)).toBe(hooks)
+        expect(next).toHaveBeenCalledTimes(1)
+      }
+    }
+  })
+
+  it('preserves Pi rich file, diff and image renderer identities', () => {
+    for (const definition of [createReadToolDefinition('/private/tmp'), createEditToolDefinition('/private/tmp')]) {
+      const resolved = harnessToolRenderers(definition.name, () => definition as unknown as ToolRenderers)
+      expect(resolved).toBe(definition)
+      expect(resolved?.renderCall).toBe(definition.renderCall)
+      expect(resolved?.renderResult).toBe(definition.renderResult)
+    }
+  })
+
+  it('shows pending, executing, completed and error state from actual rendering context', () => {
+    const hooks = generic()
+    const states = [
+      [{}, '⏳ wiki_recall'],
+      [{ executionStarted: true }, '⟳ wiki_recall'],
+      [{ isPartial: false }, '• wiki_recall'],
+      [{ isPartial: false, isError: true }, '✘ wiki_recall']
+    ] as const
+    for (const [state, expected] of states) {
+      const rows = hooks.renderCall!({}, theme, context(state)).render(80)
+      expect(plain(rows)[0]).toBe(expected)
+      if ('isError' in state && state.isError) expect(rows[0]).toContain(theme.getFgAnsi('error'))
+    }
+  })
+
+  it('reveals real nested arguments when expanded and keeps partial JSON metadata out of the display', () => {
+    const hooks = generic()
+    const args = Object.freeze({ query: 'source evidence', filter: { page: ['Introduction', 'Results'] }, __partialJson: 'transport metadata' })
+    const collapsed = plain(hooks.renderCall!(args, theme, context()).render(90)).join('\n')
+    expect(collapsed).toContain('└─ query="source evidence", filter={1 keys}')
+    expect(collapsed).not.toContain('transport metadata')
+    const expanded = plain(hooks.renderCall!(args, theme, context({ expanded: true })).render(90)).join('\n')
+    expect(expanded).toContain('Args')
+    expect(expanded).toContain('page: [2 items]')
+    expect(expanded).toContain('0: "Introduction"')
+    expect(expanded).toContain('1: "Results"')
+    expect(args.filter.page).toEqual(['Introduction', 'Results'])
+  })
+
+  it('uses the returned text verbatim while changing only the output window', () => {
+    const hooks = generic()
+    const source = result(20)
+    const snapshot = structuredClone(source)
+    for (const isPartial of [false, true]) {
+      const collapsed = plain(hooks.renderResult!(source, { expanded: false, isPartial }, theme, context()).render(80))
+      expect(collapsed).toEqual(['source line 0', 'source line 1', 'source line 2', 'source line 3', '… (16 more lines)', '[Ctrl+O: Expand]'])
+      const expanded = plain(hooks.renderResult!(source, { expanded: true, isPartial }, theme, context()).render(80))
+      expect(expanded).toHaveLength(13)
+      expect(expanded[11]).toBe('source line 11')
+      expect(expanded[12]).toBe('… (8 more lines)')
+    }
+    expect(source).toEqual(snapshot)
+  })
+
+  it('renders JSON trees and preserves mixed image payloads and result metadata', () => {
+    const hooks = generic()
+    const image = { type: 'image' as const, data: 'original-image-bytes', mimeType: 'image/png' }
+    const source = { content: [{ type: 'text' as const, text: '{"pages":[{"title":"Evidence","score":0.8}]}' }, image], details: { citation: 'ev_original' } }
+    const rows = plain(hooks.renderResult!(source, { expanded: true, isPartial: false }, theme, context()).render(80))
+    expect(rows.join('\n')).toContain('title: "Evidence"')
+    expect(rows.join('\n')).toContain('score: 0.8')
+    expect(source.content[1]).toBe(image)
+    expect(source.content[1]).toEqual(image)
+    expect(source.details.citation).toBe('ev_original')
+    expect(plain(hooks.renderResult!({ content: [image], details: undefined }, { expanded: false, isPartial: false }, theme, context()).render(80))).toEqual(['(image output)'])
+  })
+
+  it('bounds every row by terminal cells while rejecting terminal commands and retaining safe output colors', () => {
+    const hooks = generic()
+    const source = { content: [{ type: 'text' as const, text: '\x1b]2;do not rename\x07\x1b[2J\x1b[31m日本語 🧠 知識é\x1b[0m\n\tsecond\rline' }], details: undefined }
+    for (let width = 0; width < 100; width++) {
+      const call = hooks.renderCall!({ 'query\n\x07': '日本語 🧠 知識'.repeat(15) }, theme, context())
+      const output = hooks.renderResult!(source, { expanded: false, isPartial: true }, theme, context())
+      for (const component of [call, output]) {
+        for (const row of component.render(width)) {
+          expect(visibleWidth(row), `width ${width}`).toBeLessThanOrEqual(width)
+          expect(row).not.toContain('\x1b]')
+          expect(row).not.toContain('\x1b[2J')
+          expect(stripTerminalSequences(row)).not.toMatch(/[\x00-\x1f\x7f]/)
+        }
+      }
+    }
+    const colored = hooks.renderResult!(source, { expanded: true, isPartial: false }, theme, context()).render(90)
+    expect(colored[0]).toContain('\x1b[31m')
+    expect(plain(colored)[0]).toBe('日本語 🧠 知識é')
+  })
+
+  it('bounds deep and cyclic argument trees without hiding their existence', () => {
+    const cyclic: Record<string, unknown> = { count: 1 }
+    cyclic.self = cyclic
+    const rows = plain(generic().renderCall!(cyclic, theme, context({ expanded: true })).render(80))
+    expect(rows.join('\n')).toContain('[circular]')
+    const many = Object.fromEntries(Array.from({ length: 1000 }, (_, index) => [`key${index}`, index]))
+    expect(generic().renderCall!(many, theme, context({ expanded: true })).render(80).length).toBeLessThanOrEqual(205)
+  })
+})

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/transcript.test.ts

@@ -0,0 +1,25 @@
+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()
+})

package/src/terminal/tui/transcript.ts

@@ -0,0 +1,124 @@
+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…'
+
+  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
+  }
+
+  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)
+    }
+  }
+}