fix(ui-tui): harden TUI error handling, model validation, command UX parity, and gateway lifecycle

ui-tui/src/components/modelPicker.tsx

@@ -0,0 +1,241 @@
+import { Box, Text, useInput } from '@hermes/ink'
+import { useEffect, useState } from 'react'
+
+import type { GatewayClient } from '../gatewayClient.js'
+import { asRpcResult, rpcErrorMessage } from '../lib/rpc.js'
+import type { Theme } from '../theme.js'
+
+interface ProviderItem {
+  is_current?: boolean
+  models?: string[]
+  name: string
+  slug: string
+  total_models?: number
+  warning?: string
+}
+
+const VISIBLE = 12
+
+const pageOffset = (count: number, sel: number) => Math.max(0, Math.min(sel - Math.floor(VISIBLE / 2), count - VISIBLE))
+
+export function ModelPicker({
+  gw,
+  onCancel,
+  onSelect,
+  sessionId,
+  t
+}: {
+  gw: GatewayClient
+  onCancel: () => void
+  onSelect: (value: string) => void
+  sessionId: string | null
+  t: Theme
+}) {
+  const [providers, setProviders] = useState<ProviderItem[]>([])
+  const [currentModel, setCurrentModel] = useState('')
+  const [err, setErr] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [persistGlobal, setPersistGlobal] = useState(false)
+  const [providerIdx, setProviderIdx] = useState(0)
+  const [modelIdx, setModelIdx] = useState(0)
+  const [stage, setStage] = useState<'model' | 'provider'>('provider')
+
+  useEffect(() => {
+    gw.request('model.options', sessionId ? { session_id: sessionId } : {})
+      .then((raw: any) => {
+        const r = asRpcResult(raw)
+
+        if (!r) {
+          setErr('invalid response: model.options')
+          setLoading(false)
+
+          return
+        }
+
+        const next = (r.providers ?? []) as ProviderItem[]
+        setProviders(next)
+        setCurrentModel(String(r.model ?? ''))
+        setProviderIdx(
+          Math.max(
+            0,
+            next.findIndex(p => p.is_current)
+          )
+        )
+        setModelIdx(0)
+        setErr('')
+        setLoading(false)
+      })
+      .catch((e: unknown) => {
+        setErr(rpcErrorMessage(e))
+        setLoading(false)
+      })
+  }, [gw, sessionId])
+
+  const provider = providers[providerIdx]
+  const models = provider?.models ?? []
+
+  const visibleItems = (items: string[], sel: number) => {
+    const off = pageOffset(items.length, sel)
+
+    return { items: items.slice(off, off + VISIBLE), off }
+  }
+
+  useInput((ch, key) => {
+    if (key.escape) {
+      if (stage === 'model') {
+        setStage('provider')
+        setModelIdx(0)
+
+        return
+      }
+
+      onCancel()
+
+      return
+    }
+
+    const count = stage === 'provider' ? providers.length : models.length
+    const sel = stage === 'provider' ? providerIdx : modelIdx
+    const setSel = stage === 'provider' ? setProviderIdx : setModelIdx
+
+    if (key.upArrow && sel > 0) {
+      setSel(v => v - 1)
+
+      return
+    }
+
+    if (key.downArrow && sel < count - 1) {
+      setSel(v => v + 1)
+
+      return
+    }
+
+    if (key.return) {
+      if (stage === 'provider') {
+        if (!provider) {
+          return
+        }
+
+        setStage('model')
+        setModelIdx(0)
+
+        return
+      }
+
+      const model = models[modelIdx]
+
+      if (provider && model) {
+        onSelect(`${model} --provider ${provider.slug}${persistGlobal ? ' --global' : ''}`)
+      } else {
+        setStage('provider')
+      }
+
+      return
+    }
+
+    if (ch.toLowerCase() === 'g') {
+      setPersistGlobal(v => !v)
+
+      return
+    }
+
+    const n = ch === '0' ? 10 : parseInt(ch, 10)
+
+    if (!Number.isNaN(n) && n >= 1 && n <= Math.min(10, count)) {
+      const off = pageOffset(count, sel)
+
+      if (stage === 'provider') {
+        const next = off + n - 1
+
+        if (providers[next]) {
+          setProviderIdx(next)
+        }
+      } else if (provider && models[off + n - 1]) {
+        onSelect(`${models[off + n - 1]} --provider ${provider.slug}${persistGlobal ? ' --global' : ''}`)
+      }
+    }
+  })
+
+  if (loading) {
+    return <Text color={t.color.dim}>loading models…</Text>
+  }
+
+  if (err) {
+    return (
+      <Box flexDirection="column">
+        <Text color={t.color.label}>error: {err}</Text>
+        <Text color={t.color.dim}>Esc to cancel</Text>
+      </Box>
+    )
+  }
+
+  if (!providers.length) {
+    return (
+      <Box flexDirection="column">
+        <Text color={t.color.dim}>no authenticated providers</Text>
+        <Text color={t.color.dim}>Esc to cancel</Text>
+      </Box>
+    )
+  }
+
+  if (stage === 'provider') {
+    const rows = providers.map(
+      p => `${p.is_current ? '*' : ' '} ${p.name} · ${p.total_models ?? p.models?.length ?? 0} models`
+    )
+
+    const { items, off } = visibleItems(rows, providerIdx)
+
+    return (
+      <Box flexDirection="column">
+        <Text bold color={t.color.amber}>
+          Select Provider
+        </Text>
+        <Text color={t.color.dim}>Current model: {currentModel || '(unknown)'}</Text>
+        {provider?.warning ? <Text color={t.color.label}>warning: {provider.warning}</Text> : null}
+        {off > 0 && <Text color={t.color.dim}> ↑ {off} more</Text>}
+        {items.map((row, i) => {
+          const idx = off + i
+
+          return (
+            <Text color={providerIdx === idx ? t.color.cornsilk : t.color.dim} key={row}>
+              {providerIdx === idx ? '▸ ' : '  '}
+              {i + 1}. {row}
+            </Text>
+          )
+        })}
+        {off + VISIBLE < rows.length && <Text color={t.color.dim}> ↓ {rows.length - off - VISIBLE} more</Text>}
+        <Text color={t.color.dim}>persist: {persistGlobal ? 'global' : 'session'} · g toggle</Text>
+        <Text color={t.color.dim}>↑/↓ select · Enter choose · 1-9,0 quick · Esc cancel</Text>
+      </Box>
+    )
+  }
+
+  const { items, off } = visibleItems(models, modelIdx)
+
+  return (
+    <Box flexDirection="column">
+      <Text bold color={t.color.amber}>
+        Select Model
+      </Text>
+      <Text color={t.color.dim}>{provider?.name || '(unknown provider)'}</Text>
+      {!models.length ? <Text color={t.color.dim}>no models listed for this provider</Text> : null}
+      {provider?.warning ? <Text color={t.color.label}>warning: {provider.warning}</Text> : null}
+      {off > 0 && <Text color={t.color.dim}> ↑ {off} more</Text>}
+      {items.map((row, i) => {
+        const idx = off + i
+
+        return (
+          <Text color={modelIdx === idx ? t.color.cornsilk : t.color.dim} key={row}>
+            {modelIdx === idx ? '▸ ' : '  '}
+            {i + 1}. {row}
+          </Text>
+        )
+      })}
+      {off + VISIBLE < models.length && <Text color={t.color.dim}> ↓ {models.length - off - VISIBLE} more</Text>}
+      <Text color={t.color.dim}>persist: {persistGlobal ? 'global' : 'session'} · g toggle</Text>
+      <Text color={t.color.dim}>
+        {models.length ? '↑/↓ select · Enter switch · 1-9,0 quick · Esc back' : 'Enter/Esc back'}
+      </Text>
+    </Box>
+  )
+}

ui-tui/src/components/textInput.tsx

@@ -30,10 +30,68 @@ const dim = (s: string) => DIM + s + DIM_OFF
 let _seg: Intl.Segmenter | null = null
 const seg = () => (_seg ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' }))
 
+function graphemeStops(s: string) {
+  const stops = [0]
+
+  for (const { index } of seg().segment(s)) {
+    if (index > 0) {
+      stops.push(index)
+    }
+  }
+
+  if (stops.at(-1) !== s.length) {
+    stops.push(s.length)
+  }
+
+  return stops
+}
+
+function snapPos(s: string, p: number) {
+  const pos = Math.max(0, Math.min(p, s.length))
+  let last = 0
+
+  for (const stop of graphemeStops(s)) {
+    if (stop > pos) {
+      break
+    }
+
+    last = stop
+  }
+
+  return last
+}
+
+function prevPos(s: string, p: number) {
+  const pos = snapPos(s, p)
+  let prev = 0
+
+  for (const stop of graphemeStops(s)) {
+    if (stop >= pos) {
+      return prev
+    }
+
+    prev = stop
+  }
+
+  return prev
+}
+
+function nextPos(s: string, p: number) {
+  const pos = snapPos(s, p)
+
+  for (const stop of graphemeStops(s)) {
+    if (stop > pos) {
+      return stop
+    }
+  }
+
+  return s.length
+}
+
 // ── Word movement ────────────────────────────────────────────────────
 
 function wordLeft(s: string, p: number) {
-  let i = p - 1
+  let i = snapPos(s, p) - 1
 
   while (i > 0 && /\s/.test(s[i]!)) {
     i--
@@ -47,7 +105,7 @@ function wordLeft(s: string, p: number) {
 }
 
 function wordRight(s: string, p: number) {
-  let i = p
+  let i = snapPos(s, p)
 
   while (i < s.length && !/\s/.test(s[i]!)) {
     i++
@@ -252,7 +310,7 @@ export function TextInput({
 
   const commit = (next: string, nextCur: number, track = true) => {
     const prev = vRef.current
-    const c = Math.max(0, Math.min(nextCur, next.length))
+    const c = snapPos(next, nextCur)
 
     if (track && next !== prev) {
       undo.current.push({ cursor: curRef.current, value: prev })
@@ -316,11 +374,10 @@ export function TextInput({
 
   useInput(
     (inp: string, k: Key, event: InputEvent) => {
-      // Some terminals normalize Ctrl+V to "v"; others deliver raw ^V (\x16).
-      const ctrlPaste = k.ctrl && (inp.toLowerCase() === 'v' || event.keypress.raw === '\x16')
-      const metaPaste = k.meta && inp.toLowerCase() === 'v'
+      const raw = event.keypress.raw
+      const metaPaste = raw === '\x1bv' || raw === '\x1bV'
 
-      if (ctrlPaste || metaPaste) {
+      if (metaPaste) {
         return void emitPaste({ cursor: curRef.current, hotkey: true, text: '', value: vRef.current })
       }
 
@@ -366,9 +423,9 @@ export function TextInput({
       } else if (k.end || (k.ctrl && inp === 'e')) {
         c = v.length
       } else if (k.leftArrow) {
-        c = mod ? wordLeft(v, c) : Math.max(0, c - 1)
+        c = mod ? wordLeft(v, c) : prevPos(v, c)
       } else if (k.rightArrow) {
-        c = mod ? wordRight(v, c) : Math.min(v.length, c + 1)
+        c = mod ? wordRight(v, c) : nextPos(v, c)
       } else if (k.meta && inp === 'b') {
         c = wordLeft(v, c)
       } else if (k.meta && inp === 'f') {
@@ -382,15 +439,16 @@ export function TextInput({
           v = v.slice(0, t) + v.slice(c)
           c = t
         } else {
-          v = v.slice(0, c - 1) + v.slice(c)
-          c--
+          const t = prevPos(v, c)
+          v = v.slice(0, t) + v.slice(c)
+          c = t
         }
       } else if (k.delete && fwdDel.current && c < v.length) {
         if (mod) {
           const t = wordRight(v, c)
           v = v.slice(0, c) + v.slice(t)
         } else {
-          v = v.slice(0, c) + v.slice(c + 1)
+          v = v.slice(0, c) + v.slice(nextPos(v, c))
         }
       } else if (k.ctrl && inp === 'w' && c > 0) {
         const t = wordLeft(v, c)

ui-tui/src/constants.ts

@@ -25,7 +25,7 @@ export const HOTKEYS: [string, string][] = [
   ['Ctrl+G', 'open $EDITOR for prompt'],
   ['Ctrl+L', 'new session (clear)'],
   ['Ctrl+T', 'cycle thinking detail'],
-  ['Ctrl+V / Alt+V', 'paste clipboard image'],
+  ['Alt+V / /paste', 'paste clipboard image'],
   ['Tab', 'apply completion'],
   ['↑/↓', 'completions / queue edit / history'],
   ['Ctrl+A/E', 'home / end of line'],

ui-tui/src/gatewayClient.ts

@@ -5,6 +5,8 @@ import { createInterface } from 'node:readline'
 
 const MAX_GATEWAY_LOG_LINES = 200
 const MAX_LOG_PREVIEW = 240
+const STARTUP_TIMEOUT_MS = Math.max(5000, parseInt(process.env.HERMES_TUI_STARTUP_TIMEOUT_MS ?? '15000', 10) || 15000)
+const REQUEST_TIMEOUT_MS = Math.max(30000, parseInt(process.env.HERMES_TUI_RPC_TIMEOUT_MS ?? '120000', 10) || 120000)
 
 export interface GatewayEvent {
   type: string
@@ -23,27 +25,78 @@ export class GatewayClient extends EventEmitter {
   private logs: string[] = []
   private pending = new Map<string, Pending>()
   private bufferedEvents: GatewayEvent[] = []
+  private pendingExit: number | null | undefined
+  private ready = false
+  private readyTimer: ReturnType<typeof setTimeout> | null = null
   private subscribed = false
+  private stdoutRl: ReturnType<typeof createInterface> | null = null
+  private stderrRl: ReturnType<typeof createInterface> | null = null
+
+  private publish(ev: GatewayEvent) {
+    if (ev.type === 'gateway.ready') {
+      this.ready = true
+
+      if (this.readyTimer) {
+        clearTimeout(this.readyTimer)
+        this.readyTimer = null
+      }
+    }
+
+    if (this.subscribed) {
+      this.emit('event', ev)
+
+      return
+    }
+
+    this.bufferedEvents.push(ev)
+  }
 
   start() {
     const root = process.env.HERMES_PYTHON_SRC_ROOT ?? resolve(import.meta.dirname, '../../')
+    const python = process.env.HERMES_PYTHON ?? resolve(root, 'venv/bin/python')
+    const cwd = process.env.HERMES_CWD || root
+    this.ready = false
+    this.pendingExit = undefined
+    this.stdoutRl?.close()
+    this.stderrRl?.close()
+    this.stdoutRl = null
+    this.stderrRl = null
 
-    this.proc = spawn(process.env.HERMES_PYTHON ?? resolve(root, 'venv/bin/python'), ['-m', 'tui_gateway.entry'], {
-      cwd: process.env.HERMES_CWD || root,
+    if (this.proc && !this.proc.killed && this.proc.exitCode === null) {
+      this.proc.kill()
+    }
+
+    if (this.readyTimer) {
+      clearTimeout(this.readyTimer)
+    }
+
+    this.readyTimer = setTimeout(() => {
+      if (this.ready) {
+        return
+      }
+
+      this.pushLog(`[startup] timed out waiting for gateway.ready (python=${python}, cwd=${cwd})`)
+      this.publish({ type: 'gateway.start_timeout', payload: { cwd, python } })
+    }, STARTUP_TIMEOUT_MS)
+
+    this.proc = spawn(python, ['-m', 'tui_gateway.entry'], {
+      cwd,
       stdio: ['pipe', 'pipe', 'pipe']
     })
 
-    createInterface({ input: this.proc.stdout! }).on('line', raw => {
+    this.stdoutRl = createInterface({ input: this.proc.stdout! })
+    this.stdoutRl.on('line', raw => {
       try {
         this.dispatch(JSON.parse(raw))
       } catch {
         const preview = raw.trim().slice(0, MAX_LOG_PREVIEW) || '(empty line)'
         this.pushLog(`[protocol] malformed stdout: ${preview}`)
-        this.emit('event', { type: 'gateway.protocol_error', payload: { preview } } satisfies GatewayEvent)
+        this.publish({ type: 'gateway.protocol_error', payload: { preview } } satisfies GatewayEvent)
       }
     })
 
-    createInterface({ input: this.proc.stderr! }).on('line', raw => {
+    this.stderrRl = createInterface({ input: this.proc.stderr! })
+    this.stderrRl.on('line', raw => {
       const line = raw.trim()
 
       if (!line) {
@@ -51,18 +104,28 @@ export class GatewayClient extends EventEmitter {
       }
 
       this.pushLog(line)
-      this.emit('event', { type: 'gateway.stderr', payload: { line } } satisfies GatewayEvent)
+      this.publish({ type: 'gateway.stderr', payload: { line } } satisfies GatewayEvent)
     })
 
     this.proc.on('error', err => {
       this.pushLog(`[spawn] ${err.message}`)
       this.rejectPending(new Error(`gateway error: ${err.message}`))
-      this.emit('event', { type: 'gateway.stderr', payload: { line: `[spawn] ${err.message}` } } satisfies GatewayEvent)
+      this.publish({ type: 'gateway.stderr', payload: { line: `[spawn] ${err.message}` } } satisfies GatewayEvent)
     })
 
     this.proc.on('exit', code => {
+      if (this.readyTimer) {
+        clearTimeout(this.readyTimer)
+        this.readyTimer = null
+      }
+
       this.rejectPending(new Error(`gateway exited${code === null ? '' : ` (${code})`}`))
-      this.emit('exit', code)
+
+      if (this.subscribed) {
+        this.emit('exit', code)
+      } else {
+        this.pendingExit = code
+      }
     })
   }
 
@@ -78,13 +141,7 @@ export class GatewayClient extends EventEmitter {
     }
 
     if (msg.method === 'event') {
-      const ev = msg.params as GatewayEvent
-
-      if (this.subscribed) {
-        this.emit('event', ev)
-      } else {
-        this.bufferedEvents.push(ev)
-      }
+      this.publish(msg.params as GatewayEvent)
     }
   }
 
@@ -110,6 +167,12 @@ export class GatewayClient extends EventEmitter {
     for (const ev of pending) {
       this.emit('event', ev)
     }
+
+    if (this.pendingExit !== undefined) {
+      const code = this.pendingExit
+      this.pendingExit = undefined
+      this.emit('exit', code)
+    }
   }
 
   getLogTail(limit = 20): string {
@@ -117,6 +180,10 @@ export class GatewayClient extends EventEmitter {
   }
 
   request(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    if (!this.proc?.stdin || this.proc.killed || this.proc.exitCode !== null) {
+      this.start()
+    }
+
     if (!this.proc?.stdin) {
       return Promise.reject(new Error('gateway not running'))
     }
@@ -128,7 +195,7 @@ export class GatewayClient extends EventEmitter {
         if (this.pending.delete(id)) {
           reject(new Error(`timeout: ${method}`))
         }
-      }, 30_000)
+      }, REQUEST_TIMEOUT_MS)
 
       this.pending.set(id, {
         reject: e => {

ui-tui/src/hooks/useCompletion.ts

@@ -2,7 +2,7 @@ import { startTransition, useEffect, useRef, useState } from 'react'
 
 import type { GatewayClient } from '../gatewayClient.js'
 
-const TAB_PATH_RE = /((?:\.\.?\/|~\/|\/|@)[^\s]*)$/
+const TAB_PATH_RE = /((?:["']?(?:[A-Za-z]:[\\/]|\.{1,2}\/|~\/|\/|@|[^"'`\s]+\/))[^\s]*)$/
 
 export function useCompletion(input: string, blocked: boolean, gw: GatewayClient) {
   const [completions, setCompletions] = useState<{ text: string; display: string; meta: string }[]>([])
@@ -59,7 +59,18 @@ export function useCompletion(input: string, blocked: boolean, gw: GatewayClient
             setCompReplace(isSlash ? (r?.replace_from ?? 1) : input.length - (pathWord?.length ?? 0))
           })
         })
-        .catch(() => {})
+        .catch((e: unknown) => {
+          if (ref.current !== input) {
+            return
+          }
+
+          const meta = e instanceof Error && e.message ? e.message : 'unavailable'
+          startTransition(() => {
+            setCompletions([{ text: '', display: 'completion unavailable', meta }])
+            setCompIdx(0)
+            setCompReplace(isSlash ? 1 : input.length - (pathWord?.length ?? 0))
+          })
+        })
     }, 60)
 
     return () => clearTimeout(t)

ui-tui/src/lib/text.ts

@@ -243,4 +243,4 @@ export const userDisplay = (text: string): string => {
 }
 
 export const isPasteBackedText = (text: string): boolean =>
-  /\[\[paste:\d+(?:[^\n]*?)\]\]|\[paste #\d+ (?:attached|excerpt)\]/.test(text)
+  /\[\[paste:\d+(?:[^\n]*?)\]\]|\[paste #\d+ (?:attached|excerpt)(?:[^\n]*?)\]/.test(text)

ui-tui/src/types.ts

@@ -43,6 +43,7 @@ export interface SessionInfo {
   tools: Record<string, string[]>
   update_behind?: number | null
   update_command?: string
+  usage?: Usage
   version?: string
 }