@xingular/harness 0.1.6 → 2.0.0

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

@@ -0,0 +1,71 @@
+import type { AutocompleteProvider } from '@earendil-works/pi-tui'
+import { describe, expect, it } from 'vitest'
+
+import { expandSkillInvocation, skillCompletions, type SkillEntry } from './skillInvocation'
+
+const skills: SkillEntry[] = [
+  { name: 'review', description: 'Review a change' },
+  { name: 'refactor', description: 'Refactor a module' },
+  { name: 'deploy', description: 'Ship a build' }
+]
+const names = new Set(skills.map((skill) => skill.name))
+const signal = new AbortController().signal
+
+const base: AutocompleteProvider = {
+  getSuggestions: async () => ({ items: [{ value: 'accounts', label: 'accounts' }], prefix: '/a' }),
+  applyCompletion: (lines) => ({ lines, cursorLine: 0, cursorCol: 0 })
+}
+
+describe('invoking a skill with $name', () => {
+  it('rewrites a leading $name of a loaded skill into the form Pi expands', () => {
+    expect(expandSkillInvocation('$review the module', names)).toBe('/skill:review the module')
+    expect(expandSkillInvocation('  $deploy', names)).toBe('/skill:deploy')
+  })
+
+  it('leaves text alone when the name is not a loaded skill, or the $ is not a skill', () => {
+    expect(expandSkillInvocation('$unknown the module', names)).toBe('$unknown the module')
+    expect(expandSkillInvocation('It costs $5 today', names)).toBe('It costs $5 today')
+    expect(expandSkillInvocation('$5 budget', names)).toBe('$5 budget')
+    expect(expandSkillInvocation('/review module', names)).toBe('/review module')
+  })
+})
+
+describe('the $ completions', () => {
+  it('offers the skills that start with what has been typed after a word-start $', async () => {
+    const provider = skillCompletions(base, () => skills)
+    const suggestions = await provider.getSuggestions(['look at $rev'], 0, 12, { signal })
+    expect(suggestions).toEqual({
+      items: [{ value: 'review', label: '$review', description: 'Review a change' }],
+      prefix: '$rev'
+    })
+  })
+
+  it('offers every skill at a bare $, and nothing when no skill matches', async () => {
+    const provider = skillCompletions(base, () => skills)
+    expect((await provider.getSuggestions(['$'], 0, 1, { signal }))?.items.map((item) => item.value)).toEqual(['review', 'refactor', 'deploy'])
+    expect(await provider.getSuggestions(['cost $5'], 0, 7, { signal })).toBeNull()
+  })
+
+  it('gives a line that starts with a skill invocation no file completions in its arguments', async () => {
+    const files: AutocompleteProvider = { getSuggestions: async () => ({ items: [{ value: 'src/', label: 'src/' }], prefix: 'sr' }), applyCompletion: (lines) => ({ lines, cursorLine: 0, cursorCol: 0 }) }
+    const provider = skillCompletions(files, () => skills)
+    expect(await provider.getSuggestions(['$review '], 0, 8, { signal })).toBeNull()
+    expect(await provider.getSuggestions(['$review check the sr'], 0, 18, { signal })).toBeNull()
+    expect((await provider.getSuggestions(['check the sr'], 0, 12, { signal }))?.items).toEqual([{ value: 'src/', label: 'src/' }])
+  })
+
+  it('hands every other completion to the base provider', async () => {
+    const provider = skillCompletions(base, () => skills)
+    expect(await provider.getSuggestions(['/a'], 0, 2, { signal })).toEqual({ items: [{ value: 'accounts', label: 'accounts' }], prefix: '/a' })
+  })
+
+  it('inserts the chosen skill as $name and a space in place of the typed prefix', () => {
+    const provider = skillCompletions(base, () => skills)
+    const completed = provider.applyCompletion(['look at $re and more'], 0, 11, { value: 'review', label: '$review' }, '$re')
+    expect(completed).toEqual({ lines: ['look at $review  and more'], cursorLine: 0, cursorCol: 16 })
+  })
+
+  it('opens the menu when a $ is typed', () => {
+    expect(skillCompletions(base, () => skills).triggerCharacters).toContain('$')
+  })
+})

package/src/terminal/tui/skillInvocation.ts

@@ -0,0 +1,51 @@
+// A skill is invoked as `$name` in the terminal. Pi expands only `/skill:name`, so the terminal
+// rewrites the leading `$name` before the prompt is sent, and offers the loaded skills at a `$`.
+import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from '@earendil-works/pi-tui'
+
+export interface SkillEntry {
+  name: string
+  description: string
+}
+
+/** Rewrites a leading `$name` of a loaded skill into `/skill:name`. Anything else passes through, so `$5` stays text. */
+export function expandSkillInvocation(text: string, skills: ReadonlySet<string>): string {
+  const trimmed = text.trimStart()
+  const match = /^\$(\S+)(?=\s|$)/.exec(trimmed)
+  if (!match || !skills.has(match[1]!)) return text
+  return `/skill:${match[1]}${trimmed.slice(match[0].length)}`
+}
+
+/** A `$` that starts a word, and the partial name after it, at the cursor. */
+const SKILL_TOKEN = /(?:^|\s)\$([^\s$]*)$/
+/** A line whose first word is a skill invocation. */
+const SKILL_LINE = /^\s*\$\S/
+
+/** Offers the loaded skills at a `$` that starts a word. Every other completion is `base`'s. */
+export function skillCompletions(base: AutocompleteProvider, skills: () => readonly SkillEntry[]): AutocompleteProvider {
+  return {
+    triggerCharacters: [...(base.triggerCharacters ?? []), '$'],
+    async getSuggestions(lines, cursorLine, cursorCol, options): Promise<AutocompleteSuggestions | null> {
+      const line = lines[cursorLine] ?? ''
+      const token = SKILL_TOKEN.exec(line.slice(0, cursorCol))
+      if (token) {
+        const partial = token[1]!
+        const items: AutocompleteItem[] = skills()
+          .filter((skill) => skill.name.startsWith(partial))
+          .map((skill) => ({ value: skill.name, label: `$${skill.name}`, description: skill.description }))
+        return items.length ? { items, prefix: `$${partial}` } : null
+      }
+      // The arguments of a line that starts with a skill invocation are free text, not file paths.
+      if (SKILL_LINE.test(line)) return null
+      return base.getSuggestions(lines, cursorLine, cursorCol, options)
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      if (!prefix.startsWith('$')) return base.applyCompletion(lines, cursorLine, cursorCol, item, prefix)
+      const line = lines[cursorLine] ?? ''
+      const start = cursorCol - prefix.length
+      const inserted = `$${item.value} `
+      const newLines = [...lines]
+      newLines[cursorLine] = `${line.slice(0, start)}${inserted}${line.slice(cursorCol)}`
+      return { lines: newLines, cursorLine, cursorCol: start + inserted.length }
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+import { initTheme, Theme } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, visibleWidth } from '@earendil-works/pi-tui'
+import { describe, expect, it } from 'vitest'
+
+import { displayProjectName, renderStatusBand, type BandState } from './status'
+import { createHarnessTheme } from './theme'
+
+initTheme('dark', false)
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const state: BandState = {
+  cwd: '/work/project', model: { name: 'Claude Sonnet 4.6', reasoning: true, contextWindow: 200_000 },
+  thinkingLevel: 'high', branch: 'main', account: 'Tanny', inputTokens: 1300, outputTokens: 50,
+  tokensPerSecond: 30
+}
+
+describe('composer status band', () => {
+  it('renders the four text groups in order with distinct colors', () => {
+    const line = renderStatusBand(state, 120, theme)
+    expect(stripTerminalSequences(line)).toBe('project | main | Tanny · Sonnet 4.6 · high | 30 tok/s in 1,300 out 50')
+    for (const color of ['38;2;232;236;244', '38;2;0;255;136', '38;2;0;180;255', '38;2;212;192;144']) {
+      expect(line).toContain(color)
+    }
+    expect(visibleWidth(line)).toBe(stripTerminalSequences(line).length)
+  })
+
+  it('uses the last path component and a readable root fallback', () => {
+    expect(displayProjectName('/work/a/long-project/')).toBe('long-project')
+    expect(displayProjectName('/')).toBe('/')
+  })
+
+  it('shows text fallbacks when branch, account, model, and rate are unavailable', () => {
+    const line = renderStatusBand({ ...state, branch: null, account: undefined, model: undefined, tokensPerSecond: null }, 120, theme)
+    expect(stripTerminalSequences(line)).toBe('project | — | account unknown · no-model · high | — tok/s in 1,300 out 50')
+  })
+
+  it('stays within narrow terminal widths and sanitizes metadata', () => {
+    for (let width = 1; width <= 180; width++) {
+      const line = renderStatusBand({ ...state,
+        cwd: '/work/日本語/long-project-name',
+        branch: '\x1b]2;malicious title\x07main\nother',
+        model: { ...state.model!, name: '非常に長い名前'.repeat(20) }
+      }, width, theme)
+      expect(visibleWidth(line), `width ${width}`).toBeLessThanOrEqual(width)
+      expect(stripTerminalSequences(line)).not.toContain('malicious title')
+      expect(stripTerminalSequences(line)).not.toContain('\n')
+    }
+  })
+})

package/src/terminal/tui/status.ts

@@ -0,0 +1,82 @@
+// Presentation adapted from Oh My Pi 18.11.3's status line; it sits in the footer below the prompt frame.
+// Upstream MIT license and evidence are recorded in NOTICE.md and docs/terminal-tui.md.
+import { basename, sep } from 'node:path'
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { parseColor, stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
+
+import { TITANIUM } from './theme'
+
+export interface BandState {
+  cwd: string
+  model?: { name: string; reasoning: boolean; contextWindow: number }
+  thinkingLevel: string
+  branch: string | null
+  account?: string
+  inputTokens: number
+  outputTokens: number
+  tokensPerSecond: number | null
+}
+
+// OMP's shipped light theme supplies status colors separately from transcript colors.
+const LIGHT_STATUS = {
+  ...TITANIUM, darkTitanium: '#e0e0e0', electricBlue: '#875f87', subtleGray: '#808080',
+  brightAluminum: '#005f87', readoutGreen: '#005f00', titaniumGold: '#005f5f'
+}
+const palette = (theme: Theme) => theme.appearance === 'light' ? LIGHT_STATUS : TITANIUM
+
+type StatusPart = { text: string; color: string }
+
+export function singleLine(text: string): string {
+  return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ').replace(/ +/g, ' ').trim()
+}
+
+export function displayProjectName(cwd: string): string {
+  return singleLine(basename(cwd) || cwd || sep)
+}
+
+function tokenCount(value: number): string {
+  return Math.max(0, Number.isFinite(value) ? Math.round(value) : 0).toLocaleString('en-US')
+}
+
+function fitParts(parts: StatusPart[], width: number): StatusPart[] {
+  const fitted = parts.map(part => ({ ...part }))
+  const separator = ' | '
+  const plain = () => fitted.map(part => part.text).join(separator)
+  while (fitted.length > 1 && visibleWidth(plain()) > width) {
+    const last = fitted[fitted.length - 1]
+    const otherWidth = visibleWidth(plain()) - visibleWidth(separator) - visibleWidth(last.text)
+    const available = width - otherWidth - visibleWidth(separator)
+    if (available > 0 && available < visibleWidth(last.text)) {
+      last.text = truncateToWidth(last.text, available, '', false)
+      if (visibleWidth(plain()) <= width) return fitted
+    }
+    fitted.pop()
+  }
+  if (fitted.length && visibleWidth(plain()) > width) {
+    fitted[0].text = truncateToWidth(fitted[0].text, width, '', false)
+  }
+  return fitted
+}
+
+function color(theme: Theme, hex: string, text: string): string {
+  return theme.style(text, { fg: parseColor(hex) })
+}
+
+export function renderStatusBand(state: BandState, width: number, theme: Theme): string {
+  const size = Math.max(0, Math.floor(width))
+  if (!size) return ''
+  const colors = palette(theme)
+  const model = state.model ? singleLine(state.model.name).replace(/^Claude /, '') || 'no-model' : 'no-model'
+  const account = singleLine(state.account ?? '') || 'account unknown'
+  const effort = singleLine(state.thinkingLevel) || 'off'
+  const rate = state.tokensPerSecond === null || !Number.isFinite(state.tokensPerSecond)
+    ? '— tok/s' : `${Math.max(0, Math.round(state.tokensPerSecond))} tok/s`
+  const parts = fitParts([
+    { text: displayProjectName(state.cwd), color: colors.brightAluminum },
+    { text: singleLine(state.branch ?? '') || '—', color: colors.readoutGreen },
+    { text: `${account} · ${model} · ${effort}`, color: colors.electricBlue },
+    { text: `${rate} in ${tokenCount(state.inputTokens)} out ${tokenCount(state.outputTokens)}`, color: colors.titaniumGold }
+  ], size)
+  const separator = color(theme, colors.subtleGray, ' | ')
+  return parts.map(part => color(theme, part.color, part.text)).join(separator)
+}

package/src/terminal/tui/theme.ts

@@ -0,0 +1,185 @@
+/*!
+ * Adapted from @oh-my-pi/pi-tui 18.11.3 (https://github.com/can1357/oh-my-pi).
+ *
+ * MIT License
+ *
+ * Copyright (c) 2025 Mario Zechner
+ * Copyright (c) 2025-2026 Can Bölük
+ * Copyright (c) 2026 Stencil Labs, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { Theme, type ThemeBg, type ThemeColor } from '@earendil-works/pi-coding-agent'
+
+const orange = { dark: '#ffb347', light: '#9a7326' } as const
+
+export const TITANIUM = {
+  brushedTitanium: '#151820',
+  darkTitanium: '#0f1216',
+  electricBlue: '#00b4ff',
+  deepBlue: '#0082b3',
+  titaniumGold: '#d4c090',
+  brightAluminum: '#e8ecf4',
+  dimAluminum: '#9ca3b0',
+  warningAmber: orange.dark,
+  readoutGreen: '#00ff88',
+  alertRed: '#ff4757',
+  subtleGray: '#2a3038'
+} as const
+
+const foreground = {
+  accent: '#00b4ff',
+  border: '#2a3038',
+  borderAccent: '#00b4ff',
+  borderMuted: '#1f252d',
+  success: '#00ff88',
+  error: '#ff4757',
+  warning: orange.dark,
+  muted: '#9ca3b0',
+  dim: '#6b7280',
+  text: '',
+  thinkingText: '#9ca3b0',
+  userMessageText: '',
+  customMessageText: '',
+  customMessageLabel: '#d4c090',
+  toolTitle: '',
+  toolOutput: '#9ca3b0',
+  mdHeading: '#00b4ff',
+  mdLink: '#00b4ff',
+  mdLinkUrl: '#0082b3',
+  mdCode: '#00ff88',
+  mdCodeBlock: '#9ca3b0',
+  mdCodeBlockBorder: '#2a3038',
+  mdQuote: '#9ca3b0',
+  mdQuoteBorder: '#2a3038',
+  mdHr: '#2a3038',
+  mdListBullet: '#00b4ff',
+  toolDiffAdded: '#00ff88',
+  toolDiffRemoved: '#ff4757',
+  toolDiffContext: '#9ca3b0',
+  syntaxComment: '#6b7280',
+  syntaxKeyword: '#00b4ff',
+  syntaxFunction: '#00ff88',
+  syntaxVariable: '#e8ecf4',
+  syntaxString: '#d4c090',
+  syntaxNumber: '#ffb347',
+  syntaxType: '#00b4ff',
+  syntaxOperator: '#00b4ff',
+  syntaxPunctuation: '#9ca3b0',
+  thinkingOff: '#4a5058',
+  thinkingMinimal: '#5a6068',
+  thinkingLow: '#6a7078',
+  thinkingMedium: '#9ca3b0',
+  thinkingHigh: '#00b4ff',
+  thinkingXhigh: '#d4c090',
+  bashMode: '#00ff88',
+  scrollbarTrack: '#2a3038',
+  scrollbarThumb: '#9ca3b0',
+  searchMatchText: '#e8ecf4',
+  thinkingMax: '#d4c090'
+} satisfies Record<ThemeColor, string>
+
+const background = {
+  selectedBg: '#0082b3',
+  searchMatchBg: '#0082b3',
+  userMessageBg: '#0f1216',
+  customMessageBg: '#2a3038',
+  toolPendingBg: '#0f1216',
+  toolSuccessBg: '#0f1216',
+  toolErrorBg: '#1a0f10'
+} satisfies Record<ThemeBg, string>
+
+export function createHarnessTheme(base: Theme): Theme {
+  return new Theme(foreground, background, base.getColorMode(), { name: 'harness-titanium', appearance: 'dark' })
+}
+
+const lightForeground = {
+  accent: '#5a8080',
+  border: '#547da7',
+  borderAccent: '#5a8080',
+  borderMuted: '#b0b0b0',
+  success: '#588458',
+  error: '#aa5555',
+  warning: orange.light,
+  muted: '#6c6c6c',
+  dim: '#767676',
+  text: '',
+  thinkingText: '#6c6c6c',
+  userMessageText: '',
+  customMessageText: '',
+  customMessageLabel: '#7e57c2',
+  toolTitle: '',
+  toolOutput: '#6c6c6c',
+  mdHeading: '#9a7326',
+  mdLink: '#547da7',
+  mdLinkUrl: '#767676',
+  mdCode: '#5a8080',
+  mdCodeBlock: '#588458',
+  mdCodeBlockBorder: '#6c6c6c',
+  mdQuote: '#6c6c6c',
+  mdQuoteBorder: '#6c6c6c',
+  mdHr: '#6c6c6c',
+  mdListBullet: '#588458',
+  toolDiffAdded: '#588458',
+  toolDiffRemoved: '#aa5555',
+  toolDiffContext: '#6c6c6c',
+  syntaxComment: '#008000',
+  syntaxKeyword: '#0000FF',
+  syntaxFunction: '#795E26',
+  syntaxVariable: '#001080',
+  syntaxString: '#A31515',
+  syntaxNumber: '#098658',
+  syntaxType: '#267F99',
+  syntaxOperator: '#000000',
+  syntaxPunctuation: '#000000',
+  thinkingOff: '#b0b0b0',
+  thinkingMinimal: '#767676',
+  thinkingLow: '#547da7',
+  thinkingMedium: '#5a8080',
+  thinkingHigh: '#875f87',
+  thinkingXhigh: '#8b008b',
+  bashMode: '#588458',
+  scrollbarTrack: '#b0b0b0',
+  scrollbarThumb: '#6c6c6c',
+  searchMatchText: '#3b3b3b',
+  thinkingMax: '#8b008b'
+} satisfies Record<ThemeColor, string>
+
+const lightBackground = {
+  selectedBg: '#d0d0e0',
+  searchMatchBg: '#d0d0e0',
+  userMessageBg: '#e8e8e8',
+  customMessageBg: '#ede7f6',
+  toolPendingBg: '#e8e8f0',
+  toolSuccessBg: '#e8f0e8',
+  toolErrorBg: '#f0e8e8'
+} satisfies Record<ThemeBg, string>
+
+export function createHarnessLightTheme(base: Theme): Theme {
+  return new Theme(lightForeground, lightBackground, base.getColorMode(), { name: 'light', appearance: 'light' })
+}
+
+// The composer keeps its neutral frame; the slash completion divider uses warning amber.
+export function composerRuleColor(theme: Theme): string {
+  return theme.appearance === 'light' ? '#8a8a8a' : '#888888'
+}
+
+export function autocompleteRuleColor(theme: Theme): string {
+  return theme.appearance === 'light' ? orange.light : orange.dark
+}

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)
+  })
+})