@xingular/harness 0.1.6 → 0.1.7

package/src/terminal/tui/dialogs.ts

@@ -0,0 +1,301 @@
+// Rounded selector chrome follows Oh My Pi 18.11.3 (MIT; see NOTICE-oh-my-pi).
+import type { ExtensionUIContext, ExtensionUIDialogOptions, KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
+import { Editor, Input, SelectList, fuzzyFilter, matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type Focusable, type OverlayHandle, type OverlayOptions, type SelectListTheme, type TUI } from '@earendil-works/pi-tui'
+
+type DisposableComponent = Component & { dispose?(): void }
+export function selectTheme(theme: Theme): SelectListTheme {
+  return {
+    selectedPrefix: text => theme.fg('accent', text), selectedText: text => theme.fg('accent', text.replace(/^→/, '❯')),
+    description: text => theme.fg('muted', text), scrollInfo: text => theme.fg('dim', text),
+    noMatch: text => theme.fg('warning', text.replace('commands', 'options'))
+  }
+}
+/** Input keeps the original value; only its rendered cells are masked. */
+export class SecretInput extends Input {
+  override render(width: number): string[] {
+    const lines = super.render(width)
+    if (!this.getValue()) return lines
+    const segments = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    return lines.map(line => line.split(/(\x1b(?:\[[0-9;?]*[ -/]*[@-~]|_[^\x07]*\x07))/g).map((part, index) => index % 2
+      ? part
+      : [...segments.segment(part)].map(item => '•'.repeat(visibleWidth(item.segment))).join('')).join(''))
+  }
+}
+
+function safe(text: string): string {
+  return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f]/g, ' ')
+}
+
+/** OMP hook-selector.ts uses type-to-search once its options exceed the list window. */
+export class SearchableSelect implements Component, Focusable {
+  private search = new Input({ prompt: '' })
+  private list: SelectList
+  private query = ''
+  private limit = 0
+  private items: { value: string; label: string }[]
+  private filtered: { value: string; label: string }[] = []
+  private focusedValue = false
+  private currentTheme: Theme | undefined
+  constructor(options: string[], private readonly tui: TUI, private readonly theme: () => Theme, private readonly select: (index: number) => void, private readonly cancel: () => void) {
+    this.items = options.map((option, index) => ({ value: String(index), label: safe(option) }))
+    this.list = new SelectList([], 1, selectTheme(theme()))
+    this.rebuild()
+  }
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value; this.search.focused = value && this.searchEnabled() }
+  private searchEnabled(): boolean { return this.items.length > this.limit || this.query.length > 0 }
+  private rebuild(): void {
+    const selected = this.list.getSelectedItem()?.value
+    this.limit = Math.min(12, Math.max(1, Math.floor(this.tui.terminal.rows * 0.8) - 7))
+    this.currentTheme = this.theme()
+    this.filtered = fuzzyFilter(this.items, this.query, item => item.label)
+    this.list = new SelectList(this.filtered, this.limit, selectTheme(this.currentTheme))
+    if (selected) {
+      const index = this.filtered.findIndex(item => item.value === selected)
+      if (index >= 0) this.list.setSelectedIndex(index)
+    }
+    this.list.onSelect = item => this.select(Number(item.value))
+    this.list.onCancel = this.cancel
+    this.search.focused = this.focusedValue && this.searchEnabled()
+  }
+  invalidate(): void { this.rebuild(); this.search.invalidate() }
+  handleInput(data: string): void {
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) { this.cancel(); return }
+    if (!this.query && /^[1-9]$/.test(data)) {
+      const index = this.items.findIndex(item => item.label.startsWith(`${data}. `))
+      if (index >= 0) { this.select(index); return }
+    }
+    if (matchesKey(data, 'up') || matchesKey(data, 'down') || matchesKey(data, 'enter') || matchesKey(data, 'pageUp') || matchesKey(data, 'pageDown')) {
+      this.list.handleInput(data)
+    } else if (this.searchEnabled()) {
+      this.search.handleInput(data)
+      if (this.query !== this.search.getValue()) { this.query = this.search.getValue(); this.rebuild() }
+    } else if (data === 'j' || data === 'k') this.list.handleInput(data === 'j' ? '\x1b[B' : '\x1b[A')
+  }
+  render(width: number): string[] {
+    if (this.limit !== Math.min(12, Math.max(1, Math.floor(this.tui.terminal.rows * 0.8) - 7)) || this.currentTheme !== this.theme()) this.rebuild()
+    const theme = this.theme()
+    const lines = this.list.render(Math.max(4, width)).map(line => {
+      const bounded = truncateToWidth(line, width, '')
+      return stripTerminalSequences(line).startsWith('❯')
+        ? theme.bg('selectedBg', bounded + ' '.repeat(Math.max(0, width - visibleWidth(bounded))))
+        : bounded
+    })
+    if (this.searchEnabled()) {
+      const selected = this.filtered.findIndex(item => item.value === this.list.getSelectedItem()?.value) + 1
+      const count = `(${selected}/${this.filtered.length}${this.query ? ` of ${this.items.length}` : ''})`
+      lines.push(this.query ? theme.fg('dim', `  ${count} Search: `) + (this.search.render(Math.max(2, width - count.length - 11))[0] ?? '') : theme.fg('dim', `  ${count} Type to search`))
+    }
+    return lines.map(line => truncateToWidth(line, width, ''))
+  }
+}
+
+/** An overlay owns focus; its input emits the cursor marker through this delegate. */
+export class DialogPanel implements Component, Focusable {
+  deadline?: number
+  maxRows?: () => number
+  private focusedValue = false
+  private detailOffset = 0
+  private detailRows = 0
+  private detailTotal = 0
+  constructor(readonly title: string, readonly content: Component, private readonly theme: () => Theme, readonly hint: string, private readonly message?: string) {}
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) {
+    this.focusedValue = value
+    if ('focused' in this.content) (this.content as Component & Focusable).focused = value
+  }
+  invalidate(): void { this.content.invalidate() }
+  handleInput(data: string): void {
+    if (this.detailTotal > this.detailRows && (matchesKey(data, 'pageUp') || matchesKey(data, 'pageDown'))) {
+      const delta = matchesKey(data, 'pageUp') ? -1 : 1
+      this.detailOffset = Math.max(0, Math.min(this.detailTotal - this.detailRows, this.detailOffset + delta * Math.max(1, this.detailRows)))
+      return
+    }
+    this.content.handleInput?.(data)
+  }
+  render(width: number): string[] {
+    if (width < 1) return []
+    const theme = this.theme()
+    const inner = Math.max(2, width - 4)
+    const cap = (value: string) => truncateToWidth(value, width, '')
+    const border = (value: string) => theme.fg('border', value)
+    const title = truncateToWidth(` ${safe(this.title)} `, Math.max(0, width - 4), '')
+    const top = cap(border('╭─') + theme.bold(theme.fg('accent', title)) + border('─'.repeat(Math.max(0, width - visibleWidth(title) - 3)) + '╮'))
+    const bottom = cap(border('╰' + '─'.repeat(Math.max(0, width - 2)) + '╯'))
+    const row = (line: string) => {
+      const shown = truncateToWidth(line, inner, '')
+      return cap(border('│') + ' ' + shown + ' '.repeat(Math.max(0, width - visibleWidth(shown) - 3)) + border('│'))
+    }
+    const details = this.message
+      ? wrapTextWithAnsi(stripTerminalSequences(this.message).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '').replace(/\t/g, '    '), inner)
+      : []
+    const content = this.content.render(inner)
+    const height = this.maxRows ? Math.max(3, Math.floor(this.maxRows())) : details.length + content.length + 4
+    const budget = Math.max(0, height - 3)
+    // Keep choices and the footer mounted even when an approval contains a large command or path.
+    const minContent = Math.min(content.length, Math.min(2, budget))
+    const detailBudget = Math.min(details.length, Math.max(0, budget - Math.max(minContent, Math.min(content.length, budget))))
+    this.detailRows = detailBudget
+    this.detailTotal = details.length
+    this.detailOffset = Math.max(0, Math.min(this.detailOffset, details.length - detailBudget))
+    const body = details.slice(this.detailOffset, this.detailOffset + detailBudget).map(line => theme.fg('muted', line))
+    const available = Math.max(0, budget - body.length)
+    const cursor = content.findIndex(line => line.includes('\x1b_pi:c\x07') || stripTerminalSequences(line).startsWith('❯'))
+    const first = content.length <= available ? 0 : Math.max(0, Math.min(content.length - available, cursor - Math.floor(available / 2)))
+    body.push(...content.slice(first, first + available))
+    const seconds = this.deadline === undefined ? '' : ` · ${Math.max(0, Math.ceil((this.deadline - Date.now()) / 1000))}s`
+    let footerText = this.hint + seconds
+    if (details.length > detailBudget) {
+      footerText = `PgUp/PgDn details ${this.detailOffset + 1}-${this.detailOffset + detailBudget}/${details.length} · ${footerText}`
+      if (visibleWidth(footerText) > inner) footerText = 'PgUp/PgDn details · Enter · Esc' + seconds
+    }
+    const footer = row(theme.fg('dim', footerText))
+    return [top, ...body.map(row), footer, bottom].slice(0, height)
+  }
+}
+
+export class TerminalDialogs {
+  private pending = new Set<() => void>()
+  private disposed = false
+  constructor(private readonly tui: TUI, private readonly theme: () => Theme, private readonly keybindings: KeybindingsManager, private readonly changed: () => void) {}
+
+  private show<T>(build: (done: (value: T | undefined) => void) => DialogPanel, options?: ExtensionUIDialogOptions): Promise<T | undefined> {
+    if (this.disposed || options?.signal?.aborted) return Promise.resolve(undefined)
+    return new Promise((resolve, reject) => {
+      let handle: OverlayHandle | undefined
+      let timer: ReturnType<typeof setTimeout> | undefined
+      let countdown: ReturnType<typeof setInterval> | undefined
+      let settled = false
+      let panel: DialogPanel | undefined
+      const finish = (value: T | undefined, error?: unknown) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        clearInterval(countdown)
+        options?.signal?.removeEventListener('abort', cancel)
+        this.pending.delete(cancel)
+        handle?.hide()
+        const content = panel?.content as DisposableComponent | undefined
+        try { content?.dispose?.() } catch { /* The dialog must still release focus and settle. */ }
+        this.changed()
+        if (error !== undefined) reject(error)
+        else resolve(value)
+      }
+      const done = (value: T | undefined) => finish(value)
+      const cancel = () => done(undefined)
+      this.pending.add(cancel)
+      options?.signal?.addEventListener('abort', cancel, { once: true })
+      try {
+        panel = build(done)
+        panel.maxRows = () => Math.max(3, Math.floor(this.tui.terminal.rows * 0.8))
+        if (options?.timeout !== undefined) {
+          panel.deadline = Date.now() + Math.max(0, options.timeout)
+          timer = setTimeout(cancel, Math.max(0, options.timeout))
+          countdown = setInterval(this.changed, 250)
+          countdown.unref?.()
+        }
+        handle = this.tui.showOverlay(panel, { anchor: 'bottom-center', width: '100%', maxHeight: '80%' })
+        if (settled) handle.hide()
+        this.changed()
+      } catch (error) {
+        finish(undefined, error)
+      }
+    })
+  }
+
+  select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string | undefined> {
+    return this.show<string>(done => {
+      const list = new SearchableSelect(options, this.tui, this.theme, index => done(options[index]), () => done(undefined))
+      return new DialogPanel(title, list, this.theme, '↑/↓ select · Enter confirm · Esc cancel')
+    }, opts)
+  }
+
+  async confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean> {
+    return (await this.show<boolean>(done => {
+      const list = new SelectList([{ value: 'yes', label: 'Yes' }, { value: 'no', label: 'No' }], 2, selectTheme(this.theme()))
+      list.onSelect = item => done(item.value === 'yes')
+      list.onCancel = () => done(undefined)
+      return new DialogPanel(title, list, this.theme, '↑/↓ select · Enter confirm · Esc cancel', message)
+    }, opts)) ?? false
+  }
+
+  input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions, secret = false): Promise<string | undefined> {
+    return this.show<string>(done => {
+      const InputType = secret ? SecretInput : Input
+      const input = new InputType({ prompt: secret ? '' : '> ', placeholder, placeholderStyle: text => this.theme().fg('dim', text) })
+      input.onSubmit = done
+      input.onEscape = () => done(undefined)
+      return new DialogPanel(title, input, this.theme, 'Enter submit · Esc cancel')
+    }, opts)
+  }
+
+  editor(title: string, prefill?: string): Promise<string | undefined> {
+    return this.show<string>(done => {
+      const editor = new Editor(this.tui, { borderColor: text => this.theme().fg('border', text), selectList: selectTheme(this.theme()) })
+      editor.setText(prefill ?? '')
+      editor.onSubmit = done
+      const content: Component & Focusable = {
+        get focused() { return editor.focused }, set focused(value) { editor.focused = value },
+        invalidate: () => editor.invalidate(), render: width => editor.render(Math.max(4, width)).map(line => truncateToWidth(line, width, '')),
+        handleInput: data => {
+          if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) done(undefined)
+          else editor.handleInput(data)
+        }
+      }
+      return new DialogPanel(title, content, this.theme, 'Enter submit · Shift+Enter newline · Esc cancel')
+    })
+  }
+
+  custom<T>(factory: Parameters<ExtensionUIContext['custom']>[0], options?: Parameters<ExtensionUIContext['custom']>[1]): Promise<T> {
+    if (this.disposed) return Promise.resolve(undefined as T)
+    return new Promise<T>((resolve, reject) => {
+      let handle: OverlayHandle | undefined
+      let component: DisposableComponent | undefined
+      let settled = false
+      const done = (value: unknown) => {
+        if (settled) return
+        settled = true
+        this.pending.delete(cancel)
+        handle?.hide()
+        try { component?.dispose?.() } catch { /* Cleanup cannot prevent completion. */ }
+        this.changed()
+        resolve(value as T)
+      }
+      const cancel = () => done(undefined)
+      this.pending.add(cancel)
+      Promise.resolve().then(() => factory(this.tui, this.theme(), this.keybindings, done)).then(value => {
+        component = value
+        if (settled) {
+          try { component.dispose?.() } catch { /* It never mounted. */ }
+          return
+        }
+        const defaults: OverlayOptions = { anchor: 'bottom-center', width: '100%', maxHeight: '90%' }
+        const source = options?.overlayOptions
+        const overlayOptions = typeof source === 'function'
+          ? new Proxy(defaults, { get: (target, key: keyof OverlayOptions) => source()[key] ?? target[key] })
+          : { ...defaults, ...source }
+        handle = this.tui.showOverlay(component, overlayOptions)
+        options?.onHandle?.(handle)
+        this.changed()
+      }).catch(error => {
+        if (!settled) {
+          settled = true
+          this.pending.delete(cancel)
+          handle?.hide()
+          try { component?.dispose?.() } catch { /* Cleanup cannot prevent completion. */ }
+          this.changed()
+          reject(error)
+        }
+      })
+    })
+  }
+
+  reset(): void {
+    for (const cancel of [...this.pending]) cancel()
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.reset()
+  }
+}

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

@@ -0,0 +1,84 @@
+import { getSelectListTheme, initTheme, type KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
+import { CURSOR_MARKER, KeybindingsManager as TuiKeybindingsManager, stripTerminalSequences, type TUI, TUI_KEYBINDINGS, visibleWidth } from '@earendil-works/pi-tui'
+import { describe, expect, it } from 'vitest'
+
+import { HarnessEditor } from './editor'
+import { createHarnessTheme } from './theme'
+
+initTheme('dark', false)
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+function setup() {
+  const editor = new HarnessEditor({ terminal: { rows: 30 }, requestRender() {} } as unknown as TUI,
+    { borderColor: (text) => text, selectList: getSelectListTheme() }, new TuiKeybindingsManager(TUI_KEYBINDINGS) as KeybindingsManager, {
+      band: (width, above, below) => `${above}:${below}`.padEnd(width, '─'),
+      theme: () => theme, showHint: () => true, thinkingKey: '⇧⇥'
+    })
+  editor.focused = true
+  return editor
+}
+
+describe('band composer over the native Pi editor', () => {
+  it('uses exactly a band and a curved prompt row, preserving the real cursor beside the hint', () => {
+    const editor = setup()
+    const rows = editor.render(80)
+    expect(rows).toHaveLength(2)
+    expect(stripTerminalSequences(rows[1])).toMatch(/^╰─ .*⇧⇥ to change thinking effort$/)
+    expect(rows[1]).toContain(CURSOR_MARKER)
+    expect(rows.every((row) => visibleWidth(row) <= 80)).toBe(true)
+    expect(editor.getText()).toBe('')
+  })
+
+  it('closes the fake cursor before the hint, so the rest of the row is not reverse video', () => {
+    const editor = setup()
+    // Mirrors pi-tui's resolveFakeCursors: the cursor opens reverse video and its end marker closes it.
+    const resolved = editor.render(80)[1].replace(/\x1b_pi:fc\x07/g, '\x1b[7m').replace(/\x1b_pi:\/fc\x07/g, '\x1b[27m')
+    const reverseOn = resolved.indexOf('\x1b[7m')
+    const reverseOff = resolved.indexOf('\x1b[27m')
+    expect(reverseOn).toBeGreaterThan(-1)
+    expect(reverseOff).toBeGreaterThan(reverseOn)
+    expect(reverseOff).toBeLessThan(resolved.indexOf('⇧⇥'))
+  })
+
+  it('closes the cursor cell so the hint is not painted in reverse video', () => {
+    const editor = setup()
+    // Why: pi-tui paints its fake cursor as reverse video when it resolves a frame.
+    const prompt = editor.render(80)[1].replace(/\x1b_pi:fc\x07/g, '\x1b[7m').replace(/\x1b_pi:\/fc\x07/g, '\x1b[27m')
+    expect(prompt.split('\x1b[7m')).toHaveLength(prompt.split('\x1b[27m').length)
+    expect(prompt.indexOf('to change')).toBeGreaterThan(prompt.lastIndexOf('\x1b[27m'))
+  })
+
+  it('preserves editing, multiline wrapping, history, and cursor markers across resizes', () => {
+    const editor = setup()
+    const draft = 'Read 日本語 and compare the result'.repeat(3) + '\nSecond line'
+    editor.setText(draft)
+    for (const width of [120, 40, 10, 3, 1, 80]) {
+      const rows = editor.render(width)
+      expect(rows.every((row) => visibleWidth(row) <= width), `width ${width}`).toBe(true)
+      expect(rows.join('')).not.toContain('\u0000')
+      expect(rows.join('')).toContain(CURSOR_MARKER)
+      expect(editor.getText()).toBe(draft)
+    }
+    editor.setText('')
+    editor.handleInput('hello')
+    expect(editor.getText()).toBe('hello')
+    editor.addToHistory('previous prompt')
+    editor.setText('')
+    editor.handleInput('\x1b[A')
+    expect(editor.getText()).toBe('previous prompt')
+  })
+
+  it('retains autocomplete rows and selection without mistaking them for the removed bottom border', async () => {
+    const editor = setup()
+    editor.setAutocompleteProvider({
+      getSuggestions: async () => ({ items: [{ value: '/accounts', label: '/accounts' }, { value: '/plugins', label: '/plugins' }], prefix: '/' }),
+      applyCompletion: (lines, line, _col, item) => ({ lines: lines.map((value, index) => index === line ? item.value : value), cursorLine: line, cursorCol: item.value.length })
+    })
+    editor.handleInput('/')
+    await new Promise((resolve) => setTimeout(resolve, 30))
+    const rows = editor.render(50)
+    expect(rows.some((row) => stripTerminalSequences(row).includes('/accounts'))).toBe(true)
+    expect(rows.every((row) => visibleWidth(row) <= 50)).toBe(true)
+    editor.handleInput('\t')
+    expect(editor.getText()).toContain('/accounts')
+  })
+})

package/src/terminal/tui/editor.ts

@@ -0,0 +1,79 @@
+// Harness owns composer geometry and actions; Pi provides the editing primitive.
+import { CustomEditor, type KeybindingsManager, type Theme } from '@earendil-works/pi-coding-agent'
+import { CURSOR_MARKER, type EditorTheme, type TUI, type TuiMouseEvent, sliceByColumn, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
+
+const BOTTOM = '\u0000harness-composer-bottom'
+
+export interface ComposerView {
+  band(width: number, hiddenAbove: number, hiddenBelow: number): string
+  theme(): Theme
+  showHint(): boolean
+  thinkingKey: string
+}
+
+export class HarnessEditor extends CustomEditor {
+  private hiddenAbove = 0
+  private hiddenBelow = 0
+  private contentRows = 1
+  private gutterWidth = 3
+
+  constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, private readonly view: ComposerView) {
+    super(tui, theme, keybindings, { paddingX: 0 })
+  }
+
+  override setPaddingX(_padding: number): void {
+    super.setPaddingX(0)
+  }
+
+  protected override renderTopBorder(_width: number, hiddenLineCount: number): string {
+    this.hiddenAbove = hiddenLineCount
+    return ''
+  }
+
+  protected override renderBottomBorder(_width: number, hiddenLineCount: number): string {
+    this.hiddenBelow = hiddenLineCount
+    return BOTTOM
+  }
+
+  override render(width: number): string[] {
+    if (width < 1) return []
+    this.gutterWidth = Math.min(3, Math.max(0, width - 1))
+    const innerWidth = Math.max(1, width - this.gutterWidth)
+    // Pi 1.2 cannot lay out a two-cell grapheme in a one-cell text area.
+    // Lay out safely, then clip the presentation without changing the draft.
+    const rows = super.render(Math.max(3, innerWidth))
+    const bottom = rows.indexOf(BOTTOM)
+    const content = rows.slice(1, bottom)
+    this.contentRows = content.length
+    const theme = this.view.theme()
+    const prompt = content.map((line, index) => {
+      const cue = index === 0 ? '╰─ '.slice(0, this.gutterWidth) : ' '.repeat(this.gutterWidth)
+      let text = line
+      if (index === 0 && this.getText() === '' && this.view.showHint()) {
+        const hint = theme.fg('accent', this.view.thinkingKey) + ' ' + theme.italic(theme.fg('dim', 'to change thinking effort'))
+        // Why: a one-cell slice cuts off the fake cursor's closing marker, so pi-tui
+        // paints the rest of the row in reverse video. Two cells keep the marker.
+        const prefix = sliceByColumn(line, 0, 2)
+        const gap = innerWidth - visibleWidth(prefix) - visibleWidth(hint)
+        if (gap >= 1) text = prefix + ' '.repeat(gap) + hint
+      }
+      return theme.fg('borderMuted', cue) + text
+    })
+    const completions = rows.slice(bottom + 1).map((line) => ' '.repeat(this.gutterWidth) + line)
+    const result = [this.view.band(width, this.hiddenAbove, this.hiddenBelow), ...prompt, ...completions].map((line) => truncateToWidth(line, width, ''))
+    if (this.focused && !result.some((line) => line.includes(CURSOR_MARKER))) {
+      const index = Math.max(1, Math.min(result.length - 1, prompt.length))
+      result[index] = truncateToWidth(result[index], Math.max(0, width - 1), '') + CURSOR_MARKER + ' '
+    }
+    return result
+  }
+
+  override handleMouse(event: TuiMouseEvent) {
+    return super.handleMouse({
+      ...event,
+      x: event.x - this.gutterWidth,
+      y: event.y > this.contentRows ? event.y + 1 : event.y,
+      width: Math.max(1, event.width - this.gutterWidth)
+    })
+  }
+}

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

@@ -0,0 +1,22 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import { terminalKeybindings } from './keybindings'
+
+it('reloads edited isolated keybindings on the existing public manager', () => {
+  const root = mkdtempSync(join(tmpdir(), 'harness-keybindings-'))
+  try {
+    const file = join(root, 'keybindings.json')
+    writeFileSync(file, JSON.stringify({ 'app.model.select': 'ctrl+k' }))
+    const manager = terminalKeybindings(root)
+    expect(manager.matches('\x0b', 'app.model.select')).toBe(true)
+    writeFileSync(file, JSON.stringify({ 'app.model.select': 'ctrl+y' }))
+    manager.reload()
+    expect(manager.matches('\x0b', 'app.model.select')).toBe(false)
+    expect(manager.matches('\x19', 'app.model.select')).toBe(true)
+    writeFileSync(file, '{}')
+    manager.reload()
+    expect(manager.matches('\x0c', 'app.model.select')).toBe(true)
+  } finally { rmSync(root, { recursive: true, force: true }) }
+})

package/src/terminal/tui/keybindings.ts

@@ -0,0 +1,50 @@
+import type { KeybindingsManager as PiKeybindingsManager } from '@earendil-works/pi-coding-agent'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { KeybindingsManager, TUI_KEYBINDINGS, type KeybindingDefinitions, type KeybindingsConfig } from '@earendil-works/pi-tui'
+
+// Harness owns application actions. Editing and selection retain Pi's reusable bindings.
+const actions: Record<string, string | string[]> = {
+  'app.interrupt': 'escape', 'app.clear': 'ctrl+c', 'app.exit': 'ctrl+d',
+  'app.suspend': process.platform === 'win32' ? [] : 'ctrl+z',
+  'app.thinking.cycle': 'shift+tab', 'app.thinking.save': 'ctrl+s',
+  'app.model.cycleForward': 'ctrl+p', 'app.model.cycleBackward': 'alt+p',
+  'app.model.select': 'ctrl+l', 'app.tools.expand': 'ctrl+o', 'app.thinking.toggle': 'ctrl+t',
+  'app.editor.external': 'ctrl+g', 'app.message.copy': 'ctrl+x',
+  'app.message.followUp': 'alt+enter', 'app.message.dequeue': 'alt+up',
+  'app.clipboard.pasteImage': process.platform === 'darwin' ? 'alt+v' : 'ctrl+v',
+  'app.session.toggleNamedFilter': 'ctrl+n', 'app.session.togglePath': 'ctrl+p',
+  'app.session.toggleSort': 'ctrl+s', 'app.session.rename': 'ctrl+r',
+  'app.session.delete': 'ctrl+d', 'app.session.deleteNoninvasive': 'ctrl+backspace',
+  'app.tree.foldOrUp': ['alt+left', 'ctrl+left'], 'app.tree.unfoldOrDown': ['alt+right', 'ctrl+right'],
+  'app.tree.editLabel': 'shift+l', 'app.tree.toggleLabelTimestamp': 'shift+t',
+  'app.tree.filter.default': 'ctrl+d', 'app.tree.filter.noTools': 'ctrl+t',
+  'app.tree.filter.userOnly': 'ctrl+u', 'app.tree.filter.labeledOnly': 'ctrl+l',
+  'app.tree.filter.all': 'ctrl+a', 'app.tree.filter.cycleForward': 'ctrl+o',
+  'app.tree.filter.cycleBackward': 'ctrl+shift+o', 'app.models.save': 'ctrl+s',
+  'app.models.enableAll': 'ctrl+a', 'app.models.clearAll': 'ctrl+x',
+  'app.models.toggleProvider': 'ctrl+p', 'app.models.reorderUp': 'alt+up', 'app.models.reorderDown': 'alt+down',
+  'app.session.new': [], 'app.session.tree': [], 'app.session.fork': [], 'app.session.resume': []
+}
+export const HARNESS_KEYBINDINGS: KeybindingDefinitions = {
+  ...TUI_KEYBINDINGS,
+  ...Object.fromEntries(Object.entries(actions).map(([name, keys]) => [name, { defaultKeys: keys, description: name.replace(/^app\./, '').replaceAll('.', ' ') }])) as KeybindingDefinitions
+}
+
+function readBindings(agentDir: string): KeybindingsConfig {
+  let bindings: KeybindingsConfig = {}
+  try {
+    const source = JSON.parse(readFileSync(join(agentDir, 'keybindings.json'), 'utf8'))
+    if (source && typeof source === 'object' && !Array.isArray(source)) {
+      bindings = Object.fromEntries(Object.entries(source).filter(([, value]) => typeof value === 'string' || Array.isArray(value) && value.every(key => typeof key === 'string'))) as KeybindingsConfig
+    }
+  } catch { /* A missing keybindings file uses the application defaults. */ }
+  return bindings
+}
+
+export function terminalKeybindings(agentDir: string): PiKeybindingsManager {
+  const manager = new KeybindingsManager(HARNESS_KEYBINDINGS, readBindings(agentDir))
+  // CustomEditor and selector factories type their manager as Pi's private subclass.
+  // They consume the public base plus getEffectiveConfig; Harness owns the definitions.
+  return Object.assign(manager, { getEffectiveConfig: () => manager.getResolvedBindings(), reload() { manager.setUserBindings(readBindings(agentDir)) } }) as unknown as PiKeybindingsManager
+}

package/src/terminal/tui/piAdapter.ts

@@ -0,0 +1,62 @@
+// Pi 1.2.0 omits CLI builtins, rich builtin renderers, clipboard reads and the global theme setter
+// from its public exports. Keep those version-sensitive presentation hooks here; session/runtime
+// work uses public APIs. Clipboard helpers are only called for an explicit user paste.
+import { getPackageDir, VERSION, type InlineExtension, type Theme, type ToolRenderers } from '@earendil-works/pi-coding-agent'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export interface PiAdapter {
+  builtins: InlineExtension[]
+  setTheme(theme: Theme): void
+  withBuiltInRenderers(toolName: string, definition: ToolRenderers | undefined): ToolRenderers | undefined
+  readClipboardText(): Promise<string | null>
+  readClipboardFilePaths(): Promise<string[] | null>
+  readClipboardImage(): Promise<{ bytes: Uint8Array; mimeType: string } | null>
+  extensionForImageMimeType(mimeType: string): string | null
+}
+
+let adapter: PiAdapter | undefined
+let loading: Promise<PiAdapter> | undefined
+
+export function assertPiAdapterVersion(version: string): void {
+  if (version !== '1.2.0') throw new Error(`The Harness terminal adapter requires Pi 1.2.0; found ${version}. Install the Harness package's pinned dependencies.`)
+}
+
+export function loadPiAdapter(): Promise<PiAdapter> {
+  loading ??= (async () => {
+    assertPiAdapterVersion(VERSION)
+    const root = getPackageDir()
+    const [extensions, theme, renderers, clipboard, images] = await Promise.all([
+      import(pathToFileURL(join(root, 'dist/extensions/index.js')).href),
+      import(pathToFileURL(join(root, 'dist/modes/interactive/theme/theme.js')).href),
+      import(pathToFileURL(join(root, 'dist/core/tools/renderers/index.js')).href),
+      import(pathToFileURL(join(root, 'dist/utils/clipboard.js')).href),
+      import(pathToFileURL(join(root, 'dist/utils/clipboard-image.js')).href)
+    ])
+    if (!Array.isArray(extensions.builtInExtensions) || typeof theme.setThemeInstance !== 'function' || typeof renderers.withBuiltInRenderers !== 'function' || typeof clipboard.readClipboardText !== 'function' || typeof clipboard.readClipboardFilePaths !== 'function' || typeof images.readClipboardImage !== 'function' || typeof images.extensionForImageMimeType !== 'function') {
+      throw new Error('The pinned Pi terminal adapter no longer exposes its required builtin or theme hooks.')
+    }
+    adapter = {
+      builtins: extensions.builtInExtensions as InlineExtension[],
+      setTheme: theme.setThemeInstance,
+      withBuiltInRenderers: renderers.withBuiltInRenderers,
+      readClipboardText: clipboard.readClipboardText,
+      readClipboardFilePaths: clipboard.readClipboardFilePaths,
+      readClipboardImage: images.readClipboardImage,
+      extensionForImageMimeType: images.extensionForImageMimeType
+    }
+    return adapter
+  })()
+  return loading
+}
+
+/** Initialize once with loadPiAdapter() before rendering native rich tool components. */
+export function setPiTheme(theme: Theme): void {
+  if (!adapter) throw new Error('Initialize the Pi terminal adapter before setting its theme.')
+  adapter.setTheme(theme)
+}
+
+export function withBuiltInRenderers(toolName: string, definition: ToolRenderers | undefined): ToolRenderers | undefined {
+  if (!adapter) throw new Error('Initialize the Pi terminal adapter before resolving builtin renderers.')
+  return adapter.withBuiltInRenderers(toolName, definition)
+}