@xingular/harness 0.1.6 → 2.0.0

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,113 @@
+import { getSelectListTheme, initTheme, type KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
+import { CURSOR_MARKER, KeybindingsManager as TuiKeybindingsManager, renderFakeCursor, stripTerminalSequences, type TUI, type TuiMouseEvent, TUI_KEYBINDINGS, visibleWidth } from '@earendil-works/pi-tui'
+import { describe, expect, it } from 'vitest'
+
+import { COMPOSER_SUGGESTIONS, type ComposerView, HarnessEditor } from './editor'
+import { createHarnessTheme } from './theme'
+
+initTheme('dark', false)
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const bandText = (width: number) => '[band]'.padEnd(width)
+function setup(view: Partial<ComposerView> = {}) {
+  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) => bandText(width),
+      theme: () => theme, placeholder: () => undefined, ...view
+    })
+  editor.focused = true
+  return editor
+}
+
+describe('Claude-style composer frame over the native Pi editor', () => {
+  it('frames the prompt between two full-width rules, with the band below', () => {
+    const editor = setup()
+    const rows = editor.render(40)
+    expect(rows).toHaveLength(4)
+    expect(stripTerminalSequences(rows[0])).toBe('─'.repeat(40))
+    expect(rows[0]).toContain('38;2;136;136;136')
+    expect(stripTerminalSequences(rows[1])).toMatch(/^❯ /)
+    expect(rows[1]).toContain(CURSOR_MARKER)
+    expect(stripTerminalSequences(rows[2])).toBe('─'.repeat(40))
+    expect(stripTerminalSequences(rows[3]).trimEnd()).toBe('[band]')
+    expect(rows.every((row) => visibleWidth(row) <= 40)).toBe(true)
+    expect(editor.getText()).toBe('')
+  })
+
+  it('shows the suggestion as a fake cursor on its first character, only while focused', () => {
+    const editor = setup({ placeholder: () => COMPOSER_SUGGESTIONS[0] })
+    const rows = editor.render(60)
+    expect(stripTerminalSequences(rows[1])).toContain('Try "fix the failing test"')
+    expect(rows[1]).toContain(CURSOR_MARKER + renderFakeCursor('T'))
+    editor.focused = false
+    const idle = editor.render(60)[1]
+    expect(idle).not.toContain(CURSOR_MARKER)
+    expect(stripTerminalSequences(idle)).toContain('Try "fix the failing test"')
+  })
+
+  it('drops the suggestion as soon as there is a draft', () => {
+    const editor = setup({ placeholder: () => 'fix the failing test' })
+    editor.handleInput('h')
+    const rows = editor.render(60)
+    expect(editor.getText()).toBe('h')
+    expect(stripTerminalSequences(rows[1])).toMatch(/^❯ h/)
+    expect(stripTerminalSequences(rows[1])).not.toContain('Try')
+  })
+
+  it('does not render a shortcuts or thinking hint row', () => {
+    const editor = setup()
+    const rows = editor.render(80).map(stripTerminalSequences)
+    expect(rows.join('\n')).not.toContain('? for shortcuts')
+    expect(rows.join('\n')).not.toContain('to change thinking effort')
+    editor.handleInput('x')
+    expect(editor.render(80).map(stripTerminalSequences).join('\n')).not.toContain('to clear')
+  })
+
+  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('lists autocomplete above the composer with matching orange dividers and accepts a selection', 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)
+    const band = rows.findIndex((row) => stripTerminalSequences(row).startsWith('[band]'))
+    const completion = rows.findIndex((row) => stripTerminalSequences(row).includes('/accounts'))
+    const composerDivider = rows.findIndex((row, index) => index > completion && stripTerminalSequences(row) === '─'.repeat(50))
+    expect(rows[0]).toContain('38;2;255;179;71')
+    expect(rows[composerDivider]).toContain('38;2;136;136;136')
+    expect(completion).toBeGreaterThan(0)
+    expect(composerDivider).toBeGreaterThan(completion)
+    expect(band).toBeGreaterThan(composerDivider)
+    expect(rows.every((row) => visibleWidth(row) <= 50)).toBe(true)
+    editor.handleInput('\t')
+    expect(editor.getText()).toContain('/accounts')
+  })
+
+  it('does not hand the band row to the editor as its own', () => {
+    const editor = setup()
+    editor.render(40)
+    const at = (y: number) => ({ x: 5, y, width: 40, height: 5 }) as TuiMouseEvent
+    expect(editor.handleMouse(at(3))).toBeUndefined()
+  })
+})

package/src/terminal/tui/editor.ts

@@ -0,0 +1,109 @@
+// 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, parseColor, renderFakeCursor, truncateToWidth } from '@earendil-works/pi-tui'
+
+import { autocompleteRuleColor, composerRuleColor } from './theme'
+
+const BOTTOM = '\u0000harness-composer-bottom'
+
+// Generic on purpose: the placeholder names no file, project or product.
+export const COMPOSER_SUGGESTIONS = [
+  'fix the failing test',
+  'explain how this project is laid out',
+  'find where the configuration is loaded',
+  'summarize what changed since the last commit',
+  'write a test for the next change'
+]
+
+export interface ComposerView {
+  band(width: number, hiddenAbove: number, hiddenBelow: number): string
+  theme(): Theme
+  placeholder(): string | undefined
+}
+
+export class HarnessEditor extends CustomEditor {
+  private hiddenAbove = 0
+  private hiddenBelow = 0
+  private contentRows = 1
+  private completionRows = 0
+  private gutterWidth = 2
+
+  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(2, 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 placeholder = this.getText() === '' ? this.view.placeholder() : undefined
+    const prompt = content.map((line, index) => {
+      const cue = theme.fg('dim', index === 0 ? '❯ '.slice(0, this.gutterWidth) : ' '.repeat(this.gutterWidth))
+      if (index === 0 && placeholder) return cue + this.placeholderRow(placeholder, innerWidth, theme)
+      return cue + line
+    })
+    const completions = rows.slice(bottom + 1).map((line) => ' '.repeat(this.gutterWidth) + line)
+    this.completionRows = completions.length
+    const completionDivider = completions.length > 0 ? [this.rule(width, theme, autocompleteRuleColor(theme))] : []
+    const result = [
+      ...completionDivider, ...completions,
+      this.rule(width, theme), ...prompt, this.rule(width, theme), this.view.band(width, this.hiddenAbove, this.hiddenBelow)
+    ].map((line) => truncateToWidth(line, width, ''))
+    if (this.focused && !result.some((line) => line.includes(CURSOR_MARKER))) {
+      const composerOffset = completions.length > 0 ? completions.length + 1 : 0
+      const index = composerOffset + Math.max(1, Math.min(result.length - composerOffset - 1, prompt.length))
+      result[index] = truncateToWidth(result[index], Math.max(0, width - 1), '') + CURSOR_MARKER + ' '
+    }
+    return result
+  }
+
+  private rule(width: number, theme: Theme, color = composerRuleColor(theme)): string {
+    return theme.style('─'.repeat(width), { fg: parseColor(color) })
+  }
+
+  private placeholderRow(suggestion: string, innerWidth: number, theme: Theme): string {
+    const text = truncateToWidth(`Try "${suggestion}"`, innerWidth, '')
+    if (!this.focused) return theme.fg('dim', text)
+    // The first character is the fake cursor, so an empty prompt reads as the caret it will type into.
+    const [first = '', ...rest] = Array.from(text)
+    return CURSOR_MARKER + renderFakeCursor(first) + theme.fg('dim', rest.join(''))
+  }
+
+  override handleMouse(event: TuiMouseEvent) {
+    // Pi sees its own rows; the suggestion divider and status band are presentation rows.
+    const composerOffset = this.completionRows > 0 ? this.completionRows + 1 : 0
+    const band = composerOffset + this.contentRows + 2
+    if (event.y === band) return undefined
+    if (this.completionRows > 0 && event.y === 0) return undefined
+    const y = this.completionRows > 0 && event.y <= this.completionRows
+      ? this.contentRows + 1 + event.y
+      : event.y - composerOffset
+    return super.handleMouse({
+      ...event,
+      x: event.x - this.gutterWidth,
+      y,
+      width: Math.max(1, event.width - this.gutterWidth)
+    })
+  }
+}

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

@@ -0,0 +1,30 @@
+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('steps thinking effort on shift arrows and gives shift+tab to plan mode', () => {
+  const manager = terminalKeybindings('/unused/isolated-account')
+  expect(manager.matches('\x1b[1;2A', 'app.thinking.increase')).toBe(true)
+  expect(manager.matches('\x1b[1;2B', 'app.thinking.decrease')).toBe(true)
+  expect(manager.matches('\x1b[Z', 'app.plan.toggle')).toBe(true)
+  expect(manager.matches('\x1b[Z', 'app.thinking.cycle')).toBe(false)
+})
+
+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,59 @@
+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'
+
+declare module '@earendil-works/pi-tui' {
+  interface Keybindings {
+    'app.thinking.increase': true
+    'app.thinking.decrease': true
+    'app.plan.toggle': true
+  }
+}
+
+// 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': [], 'app.thinking.save': 'ctrl+s', 'app.plan.toggle': 'shift+tab',
+  'app.thinking.increase': 'shift+up', 'app.thinking.decrease': 'shift+down',
+  '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
+}