@asobacloud/nehanda 0.7.0 → 0.9.0

package/bin/nehanda-ui.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // nehanda-ui — Ink terminal UI for ona-code
 // Connects directly to nehanda-ml.asoba.co via the in-process ona-code engine.
-// No aimee-server, no HTTP daemon, no cross-repo resolution.
+// Standalone terminal UI, no external HTTP daemon, no cross-repo resolution.
 
 if (process.stdout.isTTY) {
   process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
@@ -19,11 +19,23 @@ import { runUserTurn } from '../lib/orchestrate.mjs'
 import { loadInstructions } from '../lib/instructions.mjs'
 import { modelConfigFromAgent } from '../lib/modelConfig.mjs'
 import { runConfigureWizard } from '../lib/configureProvider.mjs'
+import {
+  TUI_SLASH_COMMANDS,
+  filterSlashAutocomplete,
+  parseMcpEnvParts,
+} from '../lib/slashCommands.mjs'
 import { applyMcpConfig, loadMcpConfig, writeGlobalMcpConfig, readGlobalMcpConfig, globalMcpConfigPath, updateMcpServerEnv } from '../lib/mcp-config.mjs'
 import { getMcpServer, closeAllMcpServers, listMcpServers, mcpListResources } from '../lib/mcp.mjs'
 import { invalidateMcpToolCache } from '../lib/tools.mjs'
 import { saveOpenAiCompatKey, resolveOpenAiCompatKey, saveSecureCredentials, resolveZhipuApiKey } from '../lib/auth.mjs'
-import { TOOL_VERBS, verbForTool, summarizeToolArgs, formatToolResultSuffix } from '../lib/ui.mjs'
+import { TOOL_VERBS, verbForTool, summarizeToolArgs, formatToolResultSuffix, maskSecretAnswer } from '../lib/ui.mjs'
+import {
+  PICKER_THRESHOLD,
+  createAskIdSequencer,
+  groupModelsByVendor,
+  filterModelItems,
+  visibleWindow,
+} from '../lib/modelPicker.mjs'
 import Database from 'better-sqlite3'
 import { ensureLayaReady } from '../lib/laya_sidecar.mjs'
 
@@ -41,6 +53,10 @@ const { default: TerminalRenderer }= await import(`${REPO_ROOT}/node_modules/mar
 
 const e = React.createElement
 
+// Per-question id source for AskPrompt React keys (HP-1a, #10). Module scope:
+// ids only need to be unique for the process lifetime.
+const askIdSeq = createAskIdSequencer()
+
 // ── Asoba 3 Visual Identity ───────────────────────────────────
 const BRAND = {
   accent:   '#455BF1',
@@ -53,9 +69,9 @@ const BRAND = {
 // ── Config paths ─────────────────────────────────────────────
 const NEHANDA_DIR   = path.join(os.homedir(), '.config', 'nehanda')
 const NEHANDA_DB    = path.join(NEHANDA_DIR, 'ona-session.db')
-const AIMEE_DIR     = path.join(os.homedir(), '.config', 'aimee')
-const AGENTS_JSON   = path.join(AIMEE_DIR,   'agents.json')
+const AGENTS_JSON   = path.join(NEHANDA_DIR, 'agents.json')
 const SPLASH_SEEN   = path.join(NEHANDA_DIR, '.splash-seen')
+const LAUNCH_CWD    = process.cwd()
 
 function hasSeenSplash() { try { return fs.existsSync(SPLASH_SEEN) } catch { return false } }
 function markSplashSeen() {
@@ -78,8 +94,15 @@ function readApiKey() {
 
 function writeApiKey(key) {
   const data  = readAgents()
-  const agent = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
-  if (agent) { agent.api_key = key; fs.writeFileSync(AGENTS_JSON, JSON.stringify(data, null, 2), 'utf8') }
+  let agent = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
+  if (!agent) {
+    agent = { name: data.default_agent || 'default' }
+    if (!Array.isArray(data.agents)) data.agents = []
+    data.agents.push(agent)
+    data.default_agent = agent.name
+  }
+  agent.api_key = key
+  fs.writeFileSync(AGENTS_JSON, JSON.stringify(data, null, 2), 'utf8')
 }
 
 // ── Session DB bootstrap ─────────────────────────────────────
@@ -137,16 +160,7 @@ function renderMd(text) {
 
 // ── Constants ────────────────────────────────────────────────
 const SPINNER_FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏']
-const SLASH_COMMANDS = [
-  { name: '/model',  desc: 'Configure provider, key, host, and model (single wizard)' },
-  { name: '/key',    desc: 'Set API key then continue configure (/key openrouter|zhipu|openai)' },
-  { name: '/config', desc: 'Show current config' },
-  { name: '/mcp',    desc: 'MCP server & tool management (/mcp list)' },
-  { name: '/clear',  desc: 'New conversation' },
-  { name: '/retry',  desc: 'Resend the last failed message' },
-  { name: '/help',   desc: 'Show commands' },
-  { name: '/exit',   desc: 'Quit' },
-]
+const SLASH_COMMANDS = TUI_SLASH_COMMANDS
 
 // ── Asoba lock-up (compact) ───────────────────────────────────
 function AsobaMark() {
@@ -217,7 +231,7 @@ function SplashScreen({ onDone }) {
     e(Box, { marginTop: 1 }, e(Text, { dimColor: true }, 'press any key to continue…')),
   )
 }
-function WelcomeBanner({ model, endpoint }) {
+function WelcomeBanner({ model, endpoint, cwd = LAUNCH_CWD }) {
   let cols = 80; try { cols = process.stdout.columns || 80 } catch {}
   const bw = Math.min(cols - 2, 80)
   const lw = Math.floor(bw * 0.42), rw = bw - lw - 3
@@ -229,8 +243,9 @@ function WelcomeBanner({ model, endpoint }) {
       e(Box, { flexDirection: 'column', width: rw, paddingLeft: 1, paddingY: 1 },
         e(Text, { bold: true, color: BRAND.accent }, 'Configuration'),
         e(Box, { marginTop: 1, flexDirection: 'column' },
-          e(Text, {}, e(Text, { dimColor: true }, 'Model:    '), e(Text, { color: BRAND.lavender, bold: true }, model || '—')),
-          e(Text, {}, e(Text, { dimColor: true }, 'Endpoint: '), e(Text, { dimColor: true }, endpoint || '—')),
+          e(Text, {}, e(Text, { dimColor: true }, 'Model:     '), e(Text, { color: BRAND.lavender, bold: true }, model || '—')),
+          e(Text, {}, e(Text, { dimColor: true }, 'Endpoint:  '), e(Text, { dimColor: true }, endpoint || '—')),
+          e(Text, {}, e(Text, { dimColor: true }, 'Directory: '), e(Text, { dimColor: true }, cwd || LAUNCH_CWD)),
         ),
         e(Box, { marginTop: 1 }, e(Text, { dimColor: true }, 'Type /help for commands')),
       ),
@@ -268,15 +283,20 @@ function Spinner({ label }) {
   return e(Box, { marginLeft: 1 }, e(Text, { color: BRAND.accent }, SPINNER_FRAMES[frame % SPINNER_FRAMES.length] + ' '), e(Text, { dimColor: true }, verb + '…'))
 }
 function SlashMenu({ filter }) {
-  const matches = SLASH_COMMANDS.filter(c => c.name.startsWith(filter) || c.name.includes(filter.slice(1)))
+  const matches = filterSlashAutocomplete(filter)
   if (!matches.length) return null
+  const pad = Math.min(36, Math.max(...matches.map(c => c.name.length), 12) + 1)
   return e(Box, { flexDirection: 'column', marginLeft: 2 },
     ...matches.map((c, i) => e(Box, { key: String(i) },
-      e(Text, { color: BRAND.accent }, c.name.padEnd(12)), e(Text, { dimColor: true }, c.desc))))
+      e(Text, { color: BRAND.accent }, c.name.padEnd(pad)), e(Text, { dimColor: true }, c.desc))))
 }
 function InputArea({ onSubmit, isLoading }) {
   const [value, setValue] = React.useState('')
-  const showMenu = value.startsWith('/') && !value.includes(' ')
+  // Show slash menu for top-level (`/m`) and while typing known parents (`/mcp `, `/key o`)
+  const showMenu = value.startsWith('/') && (
+    !value.includes(' ')
+    || /^\/(mcp|key)(\s|$)/i.test(value)
+  )
   const handleSubmit = React.useCallback(v => { if (!v.trim()) return; setValue(''); onSubmit(v.trim()) }, [onSubmit])
   if (isLoading) return e(Box, { paddingX: 1 }, e(Text, { dimColor: true }, 'esc to cancel'))
   return e(Box, { flexDirection: 'column' },
@@ -286,6 +306,9 @@ function InputArea({ onSubmit, isLoading }) {
 }
 function AskPrompt({ question, onAnswer, onCancel }) {
   const [value, setValue] = React.useState('')
+  // Defense-in-depth for HP-1a (#10): if this instance ever re-renders with a
+  // new question (fiber reuse), the typed value must not carry over.
+  React.useEffect(() => { setValue('') }, [question])
   useInput((_input, key) => { if (key.escape) onCancel() })
   return e(Box, { flexDirection: 'column' },
     e(Box, { marginLeft: 1 }, e(Text, { dimColor: true }, question)),
@@ -293,7 +316,124 @@ function AskPrompt({ question, onAnswer, onCancel }) {
       e(TextInput, { value, onChange: setValue, onSubmit: React.useCallback(v => onAnswer(v.trim()), [onAnswer]) })),
     e(Box, { marginLeft: 1 }, e(Text, { dimColor: true }, 'Esc cancel')))
 }
+// ── Model Picker (large lists, #10 / HP-2) ───────────────────
+// Three views: vendor GROUPS → windowed BROWSE within a vendor →
+// type-to-filter SEARCH across every discovered model.
+// Digits jump rows, '/' opens search, Esc steps back.
+function ModelPicker({ title, items, onSelect, onCancel }) {
+  const groups = React.useMemo(() => groupModelsByVendor(items), [items])
+  const [view, setView] = React.useState('groups')   // 'groups' | 'browse' | 'search'
+  const [groupIdx, setGroupIdx] = React.useState(0)
+  const [browseIdx, setBrowseIdx] = React.useState(0)
+  const [filter, setFilter] = React.useState('')
+  const [searchIdx, setSearchIdx] = React.useState(0)
+
+  const browseModels = view === 'browse' && groups[groupIdx] ? groups[groupIdx].models : []
+  const searchResults = React.useMemo(() => filterModelItems(items, filter), [items, filter])
+  const prevView = React.useRef('groups')
+
+  const jump = (setter, list, n) => {
+    if (!isNaN(n) && n >= 1 && n <= list.length) setter(n - 1)
+  }
+
+  useInput((input, key) => {
+    if (view === 'search') {
+      // TextInput owns printable chars + Enter (its onSubmit); arrows pass through.
+      if (key.escape) {
+        if (filter) { setFilter(''); setSearchIdx(0) }
+        else { setView(prevView.current); setSearchIdx(0) }
+      } else if (key.upArrow)   { setSearchIdx(i => (i - 1 + searchResults.length) % searchResults.length) }
+      else if (key.downArrow) { setSearchIdx(i => (i + 1) % searchResults.length) }
+      return
+    }
+    if (key.escape) {
+      if (view === 'browse') setView('groups')
+      else onCancel()
+      return
+    }
+    if (input === '/') { prevView.current = view; setView('search'); setFilter(''); setSearchIdx(0); return }
+    if (view === 'groups') {
+      if (key.upArrow)   { setGroupIdx(i => (i - 1 + groups.length) % groups.length); return }
+      if (key.downArrow) { setGroupIdx(i => (i + 1) % groups.length); return }
+      if (key.return) {
+        const g = groups[groupIdx]
+        if (!g) return
+        if (g.isCustom) { onSelect(g.models[0]); return }
+        setBrowseIdx(0); setView('browse')
+        return
+      }
+      jump(setGroupIdx, groups, parseInt(input, 10))
+    } else if (view === 'browse') {
+      if (key.upArrow)   { setBrowseIdx(i => (i - 1 + browseModels.length) % browseModels.length); return }
+      if (key.downArrow) { setBrowseIdx(i => (i + 1) % browseModels.length); return }
+      if (key.return)    { const m = browseModels[browseIdx]; if (m) onSelect(m); return }
+      const win = visibleWindow(browseModels, browseIdx)
+      const shown = win.visible
+      const n = parseInt(input, 10)
+      if (!isNaN(n) && n >= 1 && n <= shown.length) {
+        const item = shown[n - 1]
+        const abs = browseModels.indexOf(item)
+        if (abs !== -1) setBrowseIdx(abs)
+      }
+    }
+  })
+
+  const row = (item, i, cursor) => e(Box, { key: String(item.id ?? i), flexDirection: 'column' },
+    e(Box, {}, e(Text, { color: cursor ? BRAND.accent : undefined }, cursor ? '❯ ' : '  '),
+      e(Text, { color: BRAND.lavender }, `${i + 1}. `),
+      e(Text, { bold: true, color: cursor ? BRAND.accent : undefined }, item.label)),
+    e(Box, { marginLeft: 5 }, e(Text, { dimColor: true }, item.desc)))
+  const hiddenHints = win => e(Box, { key: 'hints', flexDirection: 'column' },
+    win.hiddenAbove ? e(Text, { dimColor: true }, `  ↑ ${win.hiddenAbove} more above`) : null,
+    win.hiddenBelow ? e(Text, { dimColor: true }, `  ↓ ${win.hiddenBelow} more below`) : null)
+
+  let body
+  if (view === 'groups') {
+    body = e(Box, { marginTop: 1, flexDirection: 'column' },
+      ...groups.map((g, i) => row(g, i, i === groupIdx)),
+      e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
+        `↑↓/1–${Math.min(9, groups.length)} vendor · Enter open · / search all · Esc cancel`)))
+  } else if (view === 'browse') {
+    const win = visibleWindow(browseModels, browseIdx)
+    body = e(Box, { marginTop: 1, flexDirection: 'column' },
+      e(Text, { dimColor: true }, `${groups[groupIdx].label} — ${browseModels.length} models`),
+      ...win.visible.map((m, i) => row(m, win.start + i, win.start + i === browseIdx)),
+      hiddenHints(win),
+      e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
+        '↑↓ navigate · Enter select · / search all · Esc back')))
+  } else {
+    const win = visibleWindow(searchResults, searchIdx)
+    const handleSearchSubmit = v => {
+      const item = searchResults[searchIdx]
+      if (item) onSelect(item)
+    }
+    body = e(Box, { marginTop: 1, flexDirection: 'column' },
+      e(Box, { paddingX: 1 }, e(Text, { color: BRAND.accent }, '/'),
+        e(TextInput, { value: filter, onChange: v => { setFilter(v); setSearchIdx(0) }, onSubmit: handleSearchSubmit })),
+      searchResults.length
+        ? e(Box, { marginTop: 1, flexDirection: 'column' },
+            ...win.visible.map((m, i) => row(m, win.start + i, win.start + i === searchIdx)),
+            hiddenHints(win))
+        : e(Text, { dimColor: true }, '  (no matches)'),
+      e(Box, { marginTop: 1 }, e(Text, { dimColor: true },
+        'type to filter · ↑↓ select · Enter confirm · Esc clear/back')))
+  }
+
+  return e(Box, { flexDirection: 'column', marginLeft: 1 },
+    e(Text, { bold: true, color: BRAND.accent }, title),
+    body)
+}
+
+// Wrapper (no hooks): large catalogs (e.g. OpenRouter's hundreds of models)
+// switch to the grouped/filterable picker instead of a flat scroll list (HP-2, #10).
 function SelectMenu({ title, items, onSelect, onCancel }) {
+  if (items.length > PICKER_THRESHOLD) {
+    return e(ModelPicker, { title, items, onSelect, onCancel })
+  }
+  return e(SelectMenuFlat, { title, items, onSelect, onCancel })
+}
+
+function SelectMenuFlat({ title, items, onSelect, onCancel }) {
   const [idx, setIdx] = React.useState(0)
   useInput((input, key) => {
     if (key.escape)    { onCancel(); return }
@@ -355,13 +495,17 @@ function BlockConfirmMenu({ payload, onDecide }) {
       e(Text, {}, ' Cancel')))
 }
 
-function TokenFooter({ calls, model }) {
+function TokenFooter({ calls, model, cwd = LAUNCH_CWD }) {
   const cols = process.stdout.columns || 80
   return e(Box, { flexDirection: 'column' },
     e(Text, { dimColor: true }, '─'.repeat(cols)),
     e(Box, { flexDirection: 'row', paddingX: 1, justifyContent: 'space-between' },
       e(Text, { dimColor: true }, `calls ${calls}`),
-      e(Text, {}, e(Text, { dimColor: true }, 'model: '), e(Text, { color: BRAND.lavender }, model || '—')),
+      e(Box, { flexDirection: 'row' },
+        e(Text, {}, e(Text, { dimColor: true }, 'model: '), e(Text, { color: BRAND.lavender }, model || '—')),
+        e(Text, { dimColor: true }, '  '),
+        e(Text, {}, e(Text, { dimColor: true }, 'dir: '), e(Text, { dimColor: true }, cwd || LAUNCH_CWD)),
+      ),
       e(Text, { dimColor: true }, '? /help  ^C exit')))
 }
 
@@ -383,7 +527,8 @@ function App({ bridge }) {
     const ag = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
     return { model: ag?.model || 'nehanda-rag-synthesis-27b', endpoint: ag?.endpoint || 'https://nehanda-ml.asoba.co/v1' }
   })
-  const lastCtrlCRef = React.useRef(0)
+  const lastCtrlCRef     = React.useRef(0)
+  const lastSpinLabelRef = React.useRef(null)  // #18: retain last explicit label to prevent spitfire between tool calls
   const bannerRef    = React.useRef({ kind: 'banner' })
   const historyItems = React.useMemo(() => [bannerRef.current, ...finalized], [finalized])
 
@@ -395,8 +540,12 @@ function App({ bridge }) {
     bridge.endAssistant   = msg  => { setFinalized(p => [...p, msg]); setStreaming(null); setCallCount(c => c + 1) }
     bridge.clearMessages  = ()   => { setFinalized([]); setStreaming(null); setClearGen(g => g + 1) }
     bridge.setLoading     = v    => setIsLoading(v)
-    bridge.updateSpinner  = text => setSpinLabel(text)
-    bridge.ask    = q     => new Promise(resolve => setAskState({ question: q, resolve }))
+    bridge.updateSpinner  = text => { if (text !== null) lastSpinLabelRef.current = text; setSpinLabel(text) }
+    // HP-1a (#10): unique id per question — AskPrompt is keyed by it, so every
+    // new wizard question remounts with an EMPTY input (no key carry-over).
+    // opts.secret → the persisted transcript line is masked (HP-1b).
+    bridge.ask    = (q, opts) => new Promise(resolve =>
+      setAskState({ id: askIdSeq.next(), question: q, secret: !!(opts && opts.secret), resolve }))
     bridge.select = (t,i) => new Promise(resolve => setSelectState({ title: t, items: i, resolve }))
     bridge.confirmBlock = payload => new Promise(resolve => setBlockState({ payload, resolve }))
     bridge.exit   = ()    => { exit() }
@@ -408,7 +557,10 @@ function App({ bridge }) {
   }, [bridge, exit])
 
   const handleAnswer = React.useCallback(answer => {
-    if (askState?.resolve) { setFinalized(p => [...p, { role: 'system', text: askState.question + ' ' + answer }]); askState.resolve(answer) }
+    // HP-1b (#10): secret answers persist masked to transcript history; the
+    // wizard still receives the raw answer via resolve().
+    const shown = askState?.secret ? maskSecretAnswer(answer) : answer
+    if (askState?.resolve) { setFinalized(p => [...p, { role: 'system', text: `${askState.question} ${shown}`.trim() }]); askState.resolve(answer) }
     setAskState(null)
   }, [askState])
   const handleAskCancel = React.useCallback(() => { askState?.resolve(null); setAskState(null) }, [askState])
@@ -443,18 +595,25 @@ function App({ bridge }) {
   return e(Box, { flexDirection: 'column' },
     e(Static, { items: historyItems, key: clearGen },
       (item, i) => item.kind === 'banner'
-        ? e(WelcomeBanner, { key: 'banner', model: modelInfo.model, endpoint: modelInfo.endpoint })
+        ? e(WelcomeBanner, { key: 'banner', model: modelInfo.model, endpoint: modelInfo.endpoint, cwd: LAUNCH_CWD })
         : e(MessageView,   { key: String(i), msg: item })),
     streaming ? e(MessageView, { msg: { role: 'assistant', ...streaming } }) : null,
-    (isLoading && (!streaming || !streaming.text)) || spinLabel ? e(Spinner, { label: spinLabel || undefined }) : null,
+    // #18 fix 1: !askState hides Spinner while AskPrompt is shown (permission prompt visible).
+    // #18 fix 2: effectiveSpinLabel uses lastSpinLabelRef fallback when spinLabel=null during
+    //   active loading, preventing snap-back to a random rotating verb between tool calls.
+    (() => {
+      const effectiveSpinLabel = spinLabel ?? (isLoading ? lastSpinLabelRef.current : null)
+      return (!askState && ((isLoading && (!streaming || !streaming.text)) || effectiveSpinLabel))
+        ? e(Spinner, { label: effectiveSpinLabel || undefined }) : null
+    })(),
     askState
-      ? e(AskPrompt, { question: askState.question, onAnswer: handleAnswer, onCancel: handleAskCancel })
+      ? e(AskPrompt, { key: askState.id, question: askState.question, onAnswer: handleAnswer, onCancel: handleAskCancel })
       : blockState
         ? e(BlockConfirmMenu, { payload: blockState.payload, onDecide: handleBlock })
         : selectState
           ? e(SelectMenu, { title: selectState.title, items: selectState.items, onSelect: handleSelect, onCancel: handleSelectCancel })
           : e(InputArea, { onSubmit: bridge.onSubmit, isLoading }),
-    e(TokenFooter, { calls: callCount, model: modelInfo.model }))
+    e(TokenFooter, { calls: callCount, model: modelInfo.model, cwd: LAUNCH_CWD }))
 }
 
 // ── Diff executor ─────────────────────────────────────────────
@@ -491,7 +650,7 @@ function stripThink(text) {
 async function runUiConfigureWizard(bridge, opts = {}) {
   try {
     const result = await runConfigureWizard({
-      ask: q => bridge.ask(q),
+      ask: (q, opts) => bridge.ask(q, opts),
       select: (title, items) => bridge.select(title, items),
       notify: msg => bridge.addMessage({ role: 'system', text: `  ${msg}` }),
       resolveExistingKey: async (preset) => {
@@ -507,12 +666,16 @@ async function runUiConfigureWizard(bridge, opts = {}) {
       },
       persist: async (cfg) => {
         const data = readAgents()
-        const ag = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
-        if (ag) {
-          ag.model = cfg.model
-          ag.endpoint = cfg.endpoint
-          if (cfg.provider === 'nehanda' && cfg.apiKey) ag.api_key = cfg.apiKey
+        let ag = data.agents?.find(a => a.name === data.default_agent) || data.agents?.[0]
+        if (!ag) {
+          ag = { name: data.default_agent || 'default' }
+          if (!Array.isArray(data.agents)) data.agents = []
+          data.agents.push(ag)
+          data.default_agent = ag.name
         }
+        ag.model = cfg.model
+        ag.endpoint = cfg.endpoint
+        if (cfg.provider === 'nehanda' && cfg.apiKey) ag.api_key = cfg.apiKey
         fs.writeFileSync(AGENTS_JSON, JSON.stringify(data, null, 2), 'utf8')
         runtimeSettings.model_config = cfg.model_config || modelConfigFromAgent(
           { model: cfg.model, endpoint: cfg.endpoint },
@@ -541,8 +704,11 @@ async function handleCommand(cmd, bridge) {
   const [name] = cmd.split(/\s+/)
 
   if (name === '/help') {
-    bridge.addMessage({ role: 'system', text: '\nCommands:\n' +
-      SLASH_COMMANDS.map(c => `  ${chalk.hex(BRAND.accent)(c.name.padEnd(12))} ${chalk.dim(c.desc)}`).join('\n') + '\n' })
+    const pad = Math.max(...TUI_SLASH_COMMANDS.map(c => c.name.length), 12) + 2
+    const body = TUI_SLASH_COMMANDS.map(c =>
+      `  ${chalk.hex(BRAND.accent)(c.name.padEnd(pad))}${chalk.dim(c.desc)}`
+    ).join('\n')
+    bridge.addMessage({ role: 'system', text: `\nCommands:\n\n${body}\n` })
     return
   }
   if (name === '/config') {
@@ -585,7 +751,7 @@ async function handleCommand(cmd, bridge) {
     }
 
     if (!sub || !KEY_TO_PRESET[sub]) {
-      const answer = await bridge.ask('New Nehanda API key:')
+      const answer = await bridge.ask('New Nehanda API key:', { secret: true })
       if (!answer) return
       try {
         writeApiKey(answer)
@@ -597,7 +763,7 @@ async function handleCommand(cmd, bridge) {
 
     const presetId = KEY_TO_PRESET[sub]
     const inlineValue = parts.slice(2).join(' ').trim()
-    const answer = inlineValue || await bridge.ask(`New ${sub} API key:`)
+    const answer = inlineValue || await bridge.ask(`New ${sub} API key:`, { secret: true })
     if (!answer) return
 
     try {
@@ -620,14 +786,19 @@ async function handleCommand(cmd, bridge) {
     const serverNames = Object.keys(servers)
 
     if (!sub || sub === 'help') {
+      const pad = 40
+      const row = (n, d) => `    ${chalk.hex(BRAND.accent)(n.padEnd(pad))}${chalk.dim(d)}`
       const lines = [
         '',
         `  ${chalk.bold('MCP Server & Tool Commands:')}`,
-        `    ${chalk.hex(BRAND.accent)('/mcp list'.padEnd(28))} ${chalk.dim('Discover and list all available MCP tools')}`,
-        `    ${chalk.hex(BRAND.accent)('/mcp status'.padEnd(28))} ${chalk.dim('Show configured servers and command paths')}`,
-        `    ${chalk.hex(BRAND.accent)('/mcp reload [server]'.padEnd(28))} ${chalk.dim('Reload mcp.json configs into session')}`,
-        `    ${chalk.hex(BRAND.accent)('/mcp add <name> <cmd> […]'.padEnd(28))} ${chalk.dim('Register a new MCP server')}`,
-        `    ${chalk.hex(BRAND.accent)('/mcp env [server] [K] [V]'.padEnd(28))} ${chalk.dim('View or set server environment variables')}`,
+        row('/mcp list', 'List tools from configured MCP servers'),
+        row('/mcp status', 'Show configured servers'),
+        row('/mcp reload [server]', 'Reload mcp.json into this session'),
+        row('/mcp add <name> <command> [args…]', 'Register a server'),
+        row('/mcp env', 'Show env vars for every server (values masked)'),
+        row('/mcp env <server>', 'Show env vars for one server'),
+        row('/mcp env <server> <NAME> <VALUE>', 'Set env var  e.g. /mcp env jupyter JUPYTER_TOKEN sk-…'),
+        row('/mcp env unset <server> <NAME>', 'Remove an env var'),
         '',
         `  ${chalk.dim(`Configured servers: ${serverNames.length ? serverNames.join(', ') : 'none'}`)}`,
         `  ${chalk.dim('Tip: Run /mcp list to inspect tools injected into the assistant.')}`,
@@ -717,24 +888,26 @@ async function handleCommand(cmd, bridge) {
     }
 
     if (sub === 'env') {
-      const targetServer = parts[2]
-      const envKey = parts[3]
-      const envVal = parts[4]
+      const parsed = parseMcpEnvParts(parts.slice(1))
+
+      if (parsed.action === 'usage_error') {
+        bridge.addMessage({ role: 'system', text: '  ' + parsed.error.replace(/\n/g, '\n  ') })
+        return
+      }
 
-      if (!targetServer) {
-        // Show env for all servers
+      if (parsed.action === 'list_all') {
         if (!serverNames.length) {
           bridge.addMessage({ role: 'system', text: '  No MCP servers configured.' })
           return
         }
         const lines = ['\n  MCP Server Environment Variables:']
-        for (const name of serverNames) {
-          const cfg = servers[name]
+        for (const srv of serverNames) {
+          const cfg = servers[srv]
           const envKeys = Object.keys(cfg.env || {})
           if (!envKeys.length) {
-            lines.push(`  ${chalk.hex(BRAND.accent)(name)}: (none)`)
+            lines.push(`  ${chalk.hex(BRAND.accent)(srv)}: (none)`)
           } else {
-            lines.push(`  ${chalk.hex(BRAND.accent)(name)}:`)
+            lines.push(`  ${chalk.hex(BRAND.accent)(srv)}:`)
             for (const k of envKeys) {
               const v = cfg.env[k]
               const masked = v.length > 10 ? v.slice(0, 6) + '...' + v.slice(-4) : '********'
@@ -746,18 +919,17 @@ async function handleCommand(cmd, bridge) {
         return
       }
 
-      if (!envKey) {
-        // Show env for a specific server
-        const cfg = servers[targetServer]
+      if (parsed.action === 'list_server') {
+        const cfg = servers[parsed.server]
         if (!cfg) {
-          bridge.addMessage({ role: 'system', text: `  Server "${targetServer}" not found.` })
+          bridge.addMessage({ role: 'system', text: `  Server "${parsed.server}" not found.` })
           return
         }
         const envKeys = Object.keys(cfg.env || {})
         if (!envKeys.length) {
-          bridge.addMessage({ role: 'system', text: `  ${chalk.hex(BRAND.accent)(targetServer)}: (no env vars set)` })
+          bridge.addMessage({ role: 'system', text: `  ${chalk.hex(BRAND.accent)(parsed.server)}: (no env vars set)\n  Set one with: /mcp env ${parsed.server} <NAME> <VALUE>` })
         } else {
-          const lines = [`  ${chalk.hex(BRAND.accent)(targetServer)}:`]
+          const lines = [`  ${chalk.hex(BRAND.accent)(parsed.server)}:`]
           for (const k of envKeys) {
             const v = cfg.env[k]
             const masked = v.length > 10 ? v.slice(0, 6) + '...' + v.slice(-4) : '********'
@@ -768,25 +940,26 @@ async function handleCommand(cmd, bridge) {
         return
       }
 
-      // Set or clear env var
-      const result = updateMcpServerEnv(targetServer, envKey, envVal || '', process.cwd())
-      if (!result.ok) {
-        bridge.addMessage({ role: 'system', text: `  ${chalk.hex(BRAND.red)('✗')} ${result.error}` })
+      if (parsed.action === 'set' || parsed.action === 'unset') {
+        const value = parsed.action === 'unset' ? '' : parsed.value
+        const result = updateMcpServerEnv(parsed.server, parsed.name, value, process.cwd())
+        if (!result.ok) {
+          bridge.addMessage({ role: 'system', text: `  ${chalk.hex(BRAND.red)('✗')} ${result.error}` })
+          return
+        }
+        runtimeSettings.mcp_servers = {}
+        applyMcpConfig(runtimeSettings, process.cwd())
+        invalidateMcpToolCache()
+        if (parsed.action === 'set') {
+          bridge.addMessage({ role: 'system', text: `  ${chalk.green('✓')} Set ${chalk.bold(parsed.name)} = ******** on ${chalk.bold(parsed.server)}\n  Config file: ${result.path}` })
+        } else {
+          bridge.addMessage({ role: 'system', text: `  ${chalk.green('✓')} Unset ${chalk.bold(parsed.name)} on ${chalk.bold(parsed.server)}\n  Config file: ${result.path}` })
+        }
         return
       }
-      // Reload runtime settings and bust cache
-      runtimeSettings.mcp_servers = {}
-      applyMcpConfig(runtimeSettings, process.cwd())
-      invalidateMcpToolCache()
-      if (result.set) {
-        bridge.addMessage({ role: 'system', text: `  ${chalk.green('✓')} Set ${chalk.bold(envKey)} = ${'********'} on ${chalk.bold(targetServer)}\n  Config file: ${result.path}` })
-      } else {
-        bridge.addMessage({ role: 'system', text: `  ${chalk.green('✓')} Cleared ${chalk.bold(envKey)} on ${chalk.bold(targetServer)}\n  Config file: ${result.path}` })
-      }
-      return
     }
 
-    bridge.addMessage({ role: 'system', text: '  /mcp sub-commands: status · list · reload [server] · add <name> <command> [args…] · env [server] [KEY [VALUE]]' })
+    bridge.addMessage({ role: 'system', text: '  /mcp sub-commands: status · list · reload · add · env · env unset — type /help for full list' })
     return
   }
 
@@ -822,8 +995,12 @@ bridge.onSubmit = async (text) => {
   if (text.startsWith('/')) { await handleCommand(text, bridge); return }
 
   bridge.setLoading(true)
+  bridge.updateSpinner('Analyzing')
   const controller = new AbortController()
-  bridge.abortCurrent = () => controller.abort()
+  bridge.abortCurrent = () => {
+    bridge.updateSpinner('Cancelling…')   // #22: immediate UI feedback before abort propagates
+    controller.abort()
+  }
   let lastPartial = ''
 
   try {
@@ -850,7 +1027,7 @@ bridge.onSubmit = async (text) => {
       bareMode:        false,
       // Project instructions sourced from nehanda's own loadInstructions() (Ona.md),
       // matching bin/agent.mjs. Does NOT read agents.json exec_system_prompt — that
-      // field belongs to aimee and was silently reintroducing conflicting tool-call
+      // legacy field was silently reintroducing conflicting tool-call
       // syntax (<tool_call><name>...) that fights orchestrate.mjs's [TOOL_CALL] format.
       onaInstructions: onaInstructionsContent || null,
       // Esc/Ctrl+C abort — must reach fetch / Anthropic stream (issue #7).

package/lib/configureProvider.mjs

@@ -107,7 +107,7 @@ export async function discoverModelsForPreset(preset, opts = {}) {
  * Interactive configure wizard.
  *
  * @param {object} deps
- * @param {(q: string) => Promise<string>} deps.ask
+ * @param {(q: string, opts?: { secret?: boolean }) => Promise<string>} deps.ask
  * @param {(title: string, items: object[]) => Promise<object|null>} deps.select
  * @param {(msg: string) => void} [deps.notify]
  * @param {(ctx: {preset, host, apiKey}) => Promise<{success, models?, error?}>} [deps.discover]
@@ -155,7 +155,8 @@ export async function runConfigureWizard(deps, opts = {}) {
       ])
       if (!choice) return null
       if (choice.id === 'replace') {
-        const entered = await ask(`${preset.label} API key:`)
+        // {secret:true} → the TUI masks this answer in transcript history (HP-1b, #10)
+        const entered = await ask(`${preset.label} API key:`, { secret: true })
         if (!entered) return null
         apiKey = entered.trim()
         keyDirty = true
@@ -163,7 +164,7 @@ export async function runConfigureWizard(deps, opts = {}) {
         apiKey = existing
       }
     } else {
-      const entered = await ask(`${preset.label} API key:`)
+      const entered = await ask(`${preset.label} API key:`, { secret: true })
       if (!entered) return null
       apiKey = entered.trim()
       keyDirty = true