@xingular/harness 0.1.7 → 2.1.0

package/src/terminal/tui/runtime.socket.test.ts

@@ -1,5 +1,5 @@
 import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
-import { mkdtempSync, mkdirSync, rmSync } from 'node:fs'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -7,7 +7,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createHarness, type Harness } from '../../harness'
 import { memorySecretStore } from '../../accounts/secrets'
 import { connectionFromEnv, socketCall, terminalCall } from '../client'
+import type { TerminalPrepareInput } from '../terminals'
 import { controlCall } from '../control'
+import { readAllRuns } from '../../sessions/runIndex'
 import { createTerminalRuntime, type TerminalRuntime } from './runtime'
 
 const opened: Array<{ harness: Harness; runtime?: TerminalRuntime; root: string }> = []
@@ -21,7 +23,7 @@ afterEach(async () => {
   vi.unstubAllEnvs()
 })
 
-async function setup() {
+async function setup(input: Partial<TerminalPrepareInput> = {}) {
   const root = mkdtempSync(join(tmpdir(), 'harness-sdk-socket-'))
   const cwd = join(root, 'project')
   mkdirSync(cwd)
@@ -30,7 +32,7 @@ async function setup() {
   opened.push(entry)
   await harness.ready
   const account = harness.accounts.create('Offline test', 'apiKey').accounts[0]
-  const launch = await harness.terminals.prepare({ sessionId: 'offline-sdk', cwd, accountId: account.id, sessionFolder: join(root, 'history') })
+  const launch = await harness.terminals.prepare({ sessionId: 'offline-sdk', cwd, accountId: account.id, sessionFolder: join(root, 'history'), ...input })
   for (const [name, value] of Object.entries(launch.env)) vi.stubEnv(name, value === null ? undefined : value)
   vi.spyOn(process, 'cwd').mockReturnValue(cwd)
   const ui = { select: vi.fn(async () => undefined), confirm: vi.fn(async () => false), notify: vi.fn(), getEditorText: () => '' } as unknown as ExtensionUIContext
@@ -40,6 +42,78 @@ async function setup() {
 }
 
 describe('a native SDK runtime on the actual Harness terminal socket', () => {
+  it('reads and changes shared terminal permissions only through the claimed private control key', async () => {
+    const { runtime } = await setup()
+    await expect(socketCall(connectionFromEnv(), 'terminal.permissions.get')).rejects.toThrow('Only a person')
+    expect(await runtime.permissions()).toEqual({ full: false, globalTools: [] })
+    await runtime.setGlobalTool('bash', true)
+    await runtime.setFullPermission(true)
+    expect(await runtime.permissions()).toEqual({ full: true, globalTools: ['bash'] })
+    await runtime.setGlobalTool('bash', false)
+    await runtime.setFullPermission(false)
+    expect(await runtime.permissions()).toEqual({ full: false, globalTools: [] })
+  })
+
+  it('runs asynchronous children through the protected bridge and joins their results before settling', async () => {
+    const { harness, runtime } = await setup()
+    const ai = await import('@earendil-works/pi-ai')
+    const faux = ai.fauxProvider()
+    runtime.services.modelRuntime.registerNativeProvider(faux.provider)
+    harness.accounts.runtime = async () => runtime.services.modelRuntime
+    await runtime.session.setModel(faux.getModel())
+    const route = (context: { messages: Array<{ role: string; content: unknown }> }) => {
+      const users = context.messages.filter(message => message.role === 'user').map(message => typeof message.content === 'string' ? message.content : (message.content as Array<{ text?: string }>).map(part => part.text ?? '').join(''))
+      if (users.includes('terminal-native-child')) return ai.fauxAssistantMessage('TERMINAL_CHILD_EVIDENCE')
+      if (JSON.stringify(context.messages).includes('TERMINAL_CHILD_EVIDENCE')) return ai.fauxAssistantMessage('Final with TERMINAL_CHILD_EVIDENCE')
+      if (!context.messages.some(message => message.role === 'toolResult')) return ai.fauxAssistantMessage([ai.fauxToolCall('spawn_subagent', { brief: 'terminal-native-child' })], { stopReason: 'toolUse' })
+      return ai.fauxAssistantMessage('Draft before joining')
+    }
+    faux.setResponses(Array(8).fill(route) as never)
+    await expect(socketCall(connectionFromEnv(), 'terminal.subagents.tools')).rejects.toThrow('Only a person')
+    await runtime.session.prompt('Terminal parent')
+    const runs = readAllRuns(harness.env.root)
+    const parent = runs.find(run => run.sessionId === 'offline-sdk')!
+    const child = runs.find(run => run.relation === 'subagent')!
+    expect(parent.status).toBe('completed')
+    expect(child).toMatchObject({ parentRunId: parent.id, accountId: parent.accountId, status: 'completed' })
+    expect(harness.runs.activeRunIds()).toEqual([])
+    const entries = readFileSync(runtime.session.sessionFile!, 'utf8').trim().split('\n').map(line => JSON.parse(line))
+    const receipts = entries.filter(entry => entry.customType === 'xingular-subagent-results')
+    expect(receipts).toHaveLength(1)
+    expect(receipts[0].content).toContain('TERMINAL_CHILD_EVIDENCE')
+    expect(harness.terminals.state('offline-sdk').active).toBe(false)
+  })
+
+  it('routes a child approval to its original run through the terminal decision controls', async () => {
+    const { harness, runtime } = await setup()
+    await terminalCall('begin', { text: 'Parent fixture' })
+    await controlCall('terminal.subagents.register', { tools: ['read', 'bash', 'spawn_subagent', 'wait_subagents'], history: { owners: [], receipts: [] } })
+    const parentId = harness.runs.activeForSession('offline-sdk')!.runId
+    const { loadRun, saveRun } = await import('../../sessions/runStore')
+    const parent = loadRun(harness.env.root, parentId)
+    saveRun(harness.env.root, { ...parent, id: 'approval-child', sessionId: 'opaque-child', parentRunId: parentId, relation: 'subagent', status: 'queued', endedAt: null })
+    const active = harness.runs.start('opaque-child', 'approval-child')
+    const answer = active.requestApproval({ target: 'bash', action: 'fixture', rememberable: false })
+    let pending: Awaited<ReturnType<typeof runtime.pending>> = []
+    await vi.waitFor(async () => { pending = await runtime.pending(); expect(pending).toHaveLength(1) })
+    await runtime.approve(pending[0].requestId, 'denied')
+    await expect(answer).resolves.toBe('denied')
+    expect(await runtime.pending()).toEqual([])
+    active.finish('interrupted')
+  })
+
+  it('offers native tools without connected apps and preserves a read-only child ceiling', async () => {
+    const { harness, runtime } = await setup({ connections: false, readOnly: true })
+    expect(runtime.session.getToolDefinition('spawn_subagent')).toBeDefined()
+    await terminalCall('begin', { text: 'Read-only parent' })
+    await controlCall('terminal.subagents.register', { tools: ['read', 'write', 'bash', 'spawn_subagent', 'wait_subagents'], history: { owners: [], receipts: [] } })
+    const parentRunId = harness.runs.activeForSession('offline-sdk')!.runId
+    await expect(harness.subagents.spawn({ parentRunId, brief: 'Cannot widen', tools: ['write'] })).rejects.toThrow('cannot have tools')
+    const { loadRun } = await import('../../capabilities/runSnapshot')
+    expect(loadRun(harness.env.root, parentRunId)?.tools).toEqual(['read', 'spawn_subagent', 'wait_subagents'])
+    await runtime.interrupt()
+  })
+
   it('keeps the same account, command control and readiness after new/reload with no provider request', async () => {
     const { harness, runtime, ui } = await setup()
     expect(harness.terminals.state('offline-sdk')).toEqual({ ready: true, dirty: false, active: false })

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

@@ -187,6 +187,16 @@ describe('the persistent terminal SDK adapter', () => {
     expect(runtime.session.sessionFile).toBe(join(realpathSync(history), 'external.jsonl'))
   })
 
+  it('starts a new conversation when the recorded history file was never written', async () => {
+    // Pi writes a session file only after its first message, so a restart before that has nothing to resume.
+    const f = fixture()
+    const unwritten = join(f.history, 'not-written-yet.jsonl')
+    const runtime = await createTerminalRuntime([...f.args, '--session', unwritten], f.host)
+    runtimes.push(runtime)
+    expect(runtime.session.sessionFile?.startsWith(realpathSync(f.history))).toBe(true)
+    expect(runtime.session.sessionFile).not.toBe(unwritten)
+  })
+
   it('requires the prepared isolated account and refuses malformed session headers', async () => {
     const f = fixture()
     vi.stubEnv('PI_CODING_AGENT_DIR', '')

package/src/terminal/tui/runtime.ts

@@ -4,7 +4,7 @@ import {
   type AgentSession, type AgentSessionEventListener, type AgentSessionRuntime, type AgentSessionServices,
   type CreateAgentSessionRuntimeFactory, type ExtensionUIContext
 } from '@earendil-works/pi-coding-agent'
-import { closeSync, openSync, readSync, realpathSync } from 'node:fs'
+import { closeSync, existsSync, openSync, readSync, realpathSync } from 'node:fs'
 import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 
 import terminalExtension from '../piExtension'
@@ -84,11 +84,19 @@ export interface TerminalSnapshot {
   readonly queue: Readonly<{ steering: readonly string[]; followUp: readonly string[] }>
 }
 
-export interface TerminalDecision extends TerminalQuestion { type: 'approval' | 'question'; target?: string; action?: string }
+export interface TerminalDecision extends TerminalQuestion { type: 'approval' | 'question'; target?: string; action?: string; rememberable?: boolean }
+
+export interface TerminalPermissionState {
+  readonly full: boolean
+  readonly globalTools: readonly string[]
+}
 
 export interface TerminalRuntime {
   pending(): Promise<TerminalDecision[]>
-  approve(requestId: string, decision: 'approved' | 'denied'): Promise<void>
+  approve(requestId: string, decision: 'approved' | 'denied', alwaysAllowTool?: boolean): Promise<void>
+  permissions(): Promise<TerminalPermissionState>
+  setFullPermission(enabled: boolean): Promise<void>
+  setGlobalTool(tool: string, allowed: boolean): Promise<void>
   answer(requestId: string, answer: QuestionAnswer): Promise<void>
   answerBatch(batchId: string, answers: Array<{ questionId: string; answer: QuestionAnswer }>): Promise<void>
   snapshot(): TerminalSnapshot
@@ -157,10 +165,11 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
   if (!agentDirValue || !isAbsolute(agentDirValue)) throw new Error('The Harness terminal requires its isolated account directory.')
   const agentDir = realpathSync(agentDirValue)
   const sessionDirectory = realpathSync(resolve(cwd, prepared.sessionDir))
-  if (prepared.session) {
-    const path = resolve(cwd, prepared.session)
-    assertTerminalHistoryPath(path, sessionDirectory)
-    assertTerminalSessionScope(path, cwd)
+  // Pi writes a session file only after its first message, so a restart before that has nothing to resume.
+  const resume = prepared.session && existsSync(resolve(cwd, prepared.session)) ? resolve(cwd, prepared.session) : null
+  if (resume) {
+    assertTerminalHistoryPath(resume, sessionDirectory)
+    assertTerminalSessionScope(resume, cwd)
   }
 
   // Claim before loading any plugin code and retain it in the trusted process across reloads.
@@ -233,7 +242,7 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
   }
   const native = await createAgentSessionRuntime(factory, {
     cwd, agentDir,
-    sessionManager: prepared.session ? SessionManager.open(resolve(cwd, prepared.session), sessionDirectory) : SessionManager.create(cwd, sessionDirectory),
+    sessionManager: resume ? SessionManager.open(resume, sessionDirectory) : SessionManager.create(cwd, sessionDirectory),
     sessionStartEvent: { type: 'session_start', reason: 'startup' }
   })
 
@@ -268,7 +277,13 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
       if (disposed) return []
       return (await controlCall<{ requests: TerminalDecision[] }>('terminal.pending')).requests
     },
-    approve: (requestId, decision) => decide('terminal.approve', { requestId, decision }),
+    approve: (requestId, decision, alwaysAllowTool = false) => decide('terminal.approve', { requestId, decision, alwaysAllow: alwaysAllowTool }),
+    async permissions() {
+      if (disposed) return { full: false, globalTools: [] }
+      return controlCall<TerminalPermissionState>('terminal.permissions.get')
+    },
+    setFullPermission: async enabled => { await decide('terminal.permissions.setFull', { enabled }) },
+    setGlobalTool: async (tool, allowed) => { await decide('terminal.permissions.setTool', { tool, allowed }) },
     answer: (requestId, answer) => decide('terminal.answer', { requestId, answer }),
     answerBatch: (batchId, answers) => decide('terminal.answers', { batchId, answers }),
     snapshot() {

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

@@ -0,0 +1,143 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { type Theme } from '@earendil-works/pi-coding-agent'
+import { Container, TuiAltScreen, TuiMainScreen, VStack, stripTerminalSequences, type Component, type Terminal } from '@earendil-works/pi-tui'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createDock, createTerminalScreen, mountTerminalLayout, readScreenPreferences, scrollbackLines, writeScrollback, type ScreenHooks, type ScreenPreferences } from './screen'
+import { createHarnessTheme } from './theme'
+
+const directories: string[] = []
+afterEach(async () => { for (const directory of directories.splice(0)) await rm(directory, { recursive: true, force: true }) })
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const hooks: ScreenHooks = { theme: () => theme, latestKey: () => 'ctrl+end', openUrl: vi.fn(), pasteClipboard: vi.fn() }
+const defaults = readScreenPreferences(undefined)
+const prefs = (mode: ScreenPreferences['mode']): ScreenPreferences => ({ ...defaults, mode })
+
+function fakeTerminal(columns = 40, rows = 12): Terminal {
+  return {
+    columns, rows, kittyProtocolActive: false, start: vi.fn(), stop: vi.fn(), drainInput: vi.fn(async () => {}), write: vi.fn(),
+    moveBy: vi.fn(), hideCursor: vi.fn(), showCursor: vi.fn(), clearLine: vi.fn(), clearFromCursor: vi.fn(), clearScreen: vi.fn(),
+    setTitle: vi.fn(), setProgress: vi.fn(), setProgramStatus: vi.fn()
+  } as unknown as Terminal
+}
+
+/** A transcript whose rows the test changes, and a three-row dock standing in for the rule, prompt and footer. */
+function panes(initial: string[]) {
+  let transcript = initial
+  const document = new Container()
+  document.addChild({ render: () => [...transcript], invalidate: () => {} })
+  const dock = new VStack([{ component: { render: () => ['─'.repeat(40), '❯ prompt', '? for shortcuts'], invalidate: () => {} }, shrink: 1, minSize: 0 }])
+  return { document, dock, set(lines: string[]) { transcript = lines } }
+}
+
+function rowOf(lines: string[]): Component {
+  return { render: () => [...lines], invalidate: () => {} }
+}
+
+function screenRows(tui: TuiAltScreen): string[] {
+  return tui.getScreenLines().map(line => stripTerminalSequences(line).trimEnd())
+}
+
+describe('terminal screen preferences', () => {
+  it('follows Pi fullscreen defaults when no account folder is prepared', () => {
+    expect(defaults).toEqual({ mode: 'fullscreen', exitOutput: 'transcript', scrollbar: 'auto', wheelScrollLines: 'auto', copyOnSelect: true })
+  })
+
+  it('reads the regular screen from the account settings', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'harness-screen-'))
+    directories.push(directory)
+    await writeFile(join(directory, 'settings.json'), JSON.stringify({ tuiMode: 'regular' }))
+    expect(readScreenPreferences(directory).mode).toBe('regular')
+  })
+})
+
+describe('terminal screen layout', () => {
+  it('keeps the dock on the last rows while the transcript is short', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const { document, dock } = panes(['Welcome'])
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    const rows = screenRows(tui)
+    expect(rows).toHaveLength(12)
+    expect(rows[0]).toBe('Welcome')
+    expect(rows.slice(-3)).toEqual(['─'.repeat(40), '❯ prompt', '? for shortcuts'])
+    tui.stop()
+  })
+
+  it('does not move the dock as the transcript grows', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const { document, dock, set } = panes(['Welcome'])
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    set(Array.from({ length: 30 }, (_, index) => `message ${index}`))
+    tui.renderNow(true)
+    const rows = screenRows(tui)
+    expect(rows).toHaveLength(12)
+    expect(rows.slice(-3)).toEqual(['─'.repeat(40), '❯ prompt', '? for shortcuts'])
+    expect(rows[8]).toBe('message 29')
+    tui.stop()
+  })
+
+  it('scrolls the transcript above a dock that stays where it is', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const { document, dock, set } = panes(Array.from({ length: 30 }, (_, index) => `message ${index}`))
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    expect(tui.isFollowingOutput).toBe(true)
+    tui.scrollBy(-10)
+    tui.renderNow(true)
+    expect(tui.isFollowingOutput).toBe(false)
+    const rows = screenRows(tui)
+    expect(rows.slice(-3)).toEqual(['─'.repeat(40), '❯ prompt', '? for shortcuts'])
+    expect(rows.some(row => row === 'message 29')).toBe(false)
+    set(['message 0'])
+    tui.stop()
+  })
+
+  it('shows the first rows of a long queue while the prompt and status stay whole', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const queued = Array.from({ length: 20 }, (_, index) => `queued ${index}`)
+    const dock = createDock({
+      title: rowOf(['title']), above: rowOf([]), queue: rowOf(queued), below: rowOf([]), footer: rowOf(['status']),
+      editor: rowOf(['─'.repeat(40), '❯ prompt', '─'.repeat(40), '? for shortcuts'])
+    })
+    const document = new Container()
+    document.addChild(rowOf(['Welcome']))
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    const rows = screenRows(tui)
+    expect(rows).toHaveLength(12)
+    expect(rows.slice(-5)).toEqual(['─'.repeat(40), '❯ prompt', '─'.repeat(40), '? for shortcuts', 'status'])
+    expect(rows).toContain('queued 0')
+    expect(rows).not.toContain('queued 19')
+    tui.stop()
+  })
+
+  it('flows the regular screen in order without a viewport', () => {
+    const tui = createTerminalScreen(fakeTerminal(), prefs('regular'), hooks)
+    expect(tui).toBeInstanceOf(TuiMainScreen)
+    const { document, dock } = panes(['Welcome'])
+    expect(mountTerminalLayout(tui, { document, dock }, prefs('regular'), hooks)).toBeUndefined()
+    expect(tui.children).toEqual([document, dock])
+  })
+})
+
+describe('terminal scrollback on exit', () => {
+  it('truncates the conversation to the terminal width', () => {
+    const component: Component = { render: () => ['x'.repeat(30)], invalidate: () => {} }
+    expect(scrollbackLines(component, 10).map(line => stripTerminalSequences(line))).toEqual(['x'.repeat(10)])
+  })
+
+  it('writes each line with its styles reset and CRLF endings', () => {
+    const terminal = fakeTerminal()
+    writeScrollback(terminal, ['first', 'second'])
+    expect(terminal.write).toHaveBeenCalledWith('first\x1b[0m\r\nsecond\x1b[0m\r\n')
+  })
+})

package/src/terminal/tui/screen.ts

@@ -0,0 +1,121 @@
+// Screen mode and layout. Pi's fullscreen settings still choose the mode; Harness supplies its own composition.
+import { SettingsManager, copyToClipboard, type FullscreenExitOutput, type Theme, type TuiMode } from '@earendil-works/pi-coding-agent'
+import { ScrollView, TuiAltScreen, TuiMainScreen, VStack, isViewportTUI, truncateToWidth, type Component, type Terminal, type TuiAltScreenOptions } from '@earendil-works/pi-tui'
+
+export interface DockSlots {
+  readonly title: Component
+  readonly above: Component
+  readonly queue: Component
+  readonly editor: Component
+  readonly below: Component
+  readonly footer: Component
+}
+
+export type TerminalScreen = TuiMainScreen | TuiAltScreen
+
+export interface ScreenPreferences {
+  readonly mode: TuiMode
+  readonly exitOutput: FullscreenExitOutput
+  readonly scrollbar: ReturnType<SettingsManager['getFullscreenScrollbar']>
+  readonly wheelScrollLines: ReturnType<SettingsManager['getFullscreenWheelScrollLines']>
+  readonly copyOnSelect: boolean
+}
+
+export interface ScreenHooks {
+  theme(): Theme
+  latestKey(): string | undefined
+  openUrl(url: string): void
+  pasteClipboard(): void
+}
+
+export interface TerminalPanes {
+  readonly document: Component
+  readonly dock: Component
+}
+
+export function readScreenPreferences(agentDir: string | undefined): ScreenPreferences {
+  // Without an account folder there is no settings file to read, so Pi's defaults apply.
+  const settings = agentDir ? SettingsManager.create(process.cwd(), agentDir) : SettingsManager.inMemory()
+  return {
+    mode: settings.getTuiMode(),
+    exitOutput: settings.getFullscreenExitOutput(),
+    scrollbar: settings.getFullscreenScrollbar(),
+    wheelScrollLines: settings.getFullscreenWheelScrollLines(),
+    copyOnSelect: settings.getFullscreenCopyOnSelect()
+  }
+}
+
+export function createTerminalScreen(terminal: Terminal, preferences: ScreenPreferences, hooks: ScreenHooks): TerminalScreen {
+  if (preferences.mode === 'regular') return new TuiMainScreen(terminal)
+  const { theme } = hooks
+  const options: TuiAltScreenOptions = {
+    wheelScrollLines: preferences.wheelScrollLines,
+    copyOnSelect: preferences.copyOnSelect,
+    searchMatchStyle: text => theme().underline(theme().bg('searchMatchBg', theme().fg('searchMatchText', text))),
+    searchCurrentMatchStyle: text => theme().bold(theme().inverse(theme().bg('searchMatchBg', theme().fg('searchMatchText', text)))),
+    searchNavigationButtonStyle: (text, hovered) => hovered ? theme().underline(text) : text,
+    scrollToEndIndicator: () => {
+      const key = hooks.latestKey()
+      return theme().bg('selectedBg', theme().fg('text', ` ↓ Jump to latest message${key ? ` · ${keyLabel(key)}` : ''} `))
+    },
+    openUrl: hooks.openUrl,
+    onRightClickPaste: hooks.pasteClipboard,
+    copySelection: copySelectionText
+  }
+  return new TuiAltScreen(terminal, undefined, undefined, options)
+}
+
+/** The prompt and status keep their full height; when the screen is short, queued messages and widgets show their first rows and scroll for the rest. */
+export function createDock(slots: DockSlots): VStack {
+  const region = (component: Component) => new ScrollView(component)
+  return new VStack([
+    { component: slots.title, shrink: 0 },
+    { component: region(slots.above), shrink: 1, minSize: 0 },
+    { component: region(slots.queue), shrink: 1, minSize: 0 },
+    { component: slots.editor, shrink: 0 },
+    { component: region(slots.below), shrink: 1, minSize: 0 },
+    { component: slots.footer, shrink: 0 }
+  ])
+}
+
+/** Fullscreen keeps the dock on the last rows and scrolls only the transcript above it; regular mode flows in order. */
+export function mountTerminalLayout(tui: TerminalScreen, panes: TerminalPanes, preferences: ScreenPreferences, hooks: ScreenHooks): ScrollView | undefined {
+  if (!isViewportTUI(tui)) {
+    tui.addChild(panes.document)
+    tui.addChild(panes.dock)
+    return undefined
+  }
+  const transcript = new ScrollView(panes.document, {
+    follow: 'end', primary: true, overscroll: 'chain', scrollbar: preferences.scrollbar,
+    scrollbarTrackStyle: text => hooks.theme().fg('scrollbarTrack', text),
+    scrollbarThumbStyle: text => hooks.theme().fg('scrollbarThumb', text)
+  })
+  tui.setLayoutRoot(new VStack([
+    { component: transcript, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+    { component: panes.dock, basis: 'auto', grow: 0, shrink: 1, minSize: 1 }
+  ]))
+  return transcript
+}
+
+/** Rendered before the alternate screen is left, because the components are disposed afterwards. */
+export function scrollbackLines(component: Component, width: number): string[] {
+  return component.render(width).map(line => truncateToWidth(line, width, ''))
+}
+
+/** Leaving fullscreen discards the alternate screen, so the conversation is copied into normal scrollback. */
+export function writeScrollback(terminal: Terminal, lines: string[]): void {
+  terminal.write(lines.map(line => `${line}\x1b[0m`).join('\r\n') + '\r\n')
+}
+
+function keyLabel(key: string): string {
+  return key.replace(/(^|\+)([a-z])/g, (_match, separator: string, letter: string) => separator + letter.toUpperCase())
+}
+
+async function copySelectionText(text: string): Promise<boolean | string> {
+  try {
+    await copyToClipboard(text)
+    return true
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}

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