free-coding-models 0.3.17 → 0.3.19

package/src/key-handler.js

@@ -30,6 +30,8 @@
 import { loadChangelog } from './changelog-loader.js'
 import { loadConfig, replaceConfigContents } from './config.js'
 import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
+import { cycleThemeSetting, detectActiveTheme } from './theme.js'
+import { buildCommandPaletteEntries, filterCommandPaletteEntries } from './command-palette.js'
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
 // 📖 is not guaranteed to be accepted by their chat endpoint.
@@ -184,6 +186,9 @@ export function createKeyHandler(ctx) {
     startOpenCode,
     startExternalTool,
     getToolModeOrder,
+    getToolInstallPlan,
+    isToolInstalled,
+    installToolWithPlan,
     startRecommendAnalysis,
     stopRecommendAnalysis,
     sendBugReport,
@@ -207,6 +212,97 @@ export function createKeyHandler(ctx) {
 
   let userSelected = null
 
+  function resetToolInstallPrompt() {
+    state.toolInstallPromptOpen = false
+    state.toolInstallPromptCursor = 0
+    state.toolInstallPromptScrollOffset = 0
+    state.toolInstallPromptMode = null
+    state.toolInstallPromptModel = null
+    state.toolInstallPromptPlan = null
+    state.toolInstallPromptErrorMsg = null
+  }
+
+  function shouldCheckMissingTool(mode) {
+    return mode !== 'opencode-desktop'
+  }
+
+  async function launchSelectedModel(selected, options = {}) {
+    const { uiAlreadyStopped = false } = options
+    userSelected = { modelId: selected.modelId, label: selected.label, tier: selected.tier, providerKey: selected.providerKey }
+
+    if (!uiAlreadyStopped) {
+      readline.emitKeypressEvents(process.stdin)
+      if (process.stdin.isTTY) process.stdin.setRawMode(true)
+      stopUi()
+    }
+
+    // 📖 Show selection status before handing control to the target tool.
+    if (selected.status === 'timeout') {
+      console.log(chalk.yellow(`  ⚠ Selected: ${selected.label} (currently timing out)`))
+    } else if (selected.status === 'down') {
+      console.log(chalk.red(`  ⚠ Selected: ${selected.label} (currently down)`))
+    } else {
+      console.log(chalk.cyan(`  ✓ Selected: ${selected.label}`))
+    }
+    console.log()
+
+    // 📖 OpenClaw manages API keys inside its own config file. All other tools
+    // 📖 still need a provider key to be useful, so keep the existing warning.
+    if (state.mode !== 'openclaw') {
+      const selectedApiKey = getApiKey(state.config, selected.providerKey)
+      if (!selectedApiKey) {
+        console.log(chalk.yellow(`  Warning: No API key configured for ${selected.providerKey}.`))
+        console.log(chalk.yellow(`  The selected tool may not be able to use ${selected.label}.`))
+        console.log(chalk.dim(`  Set ${ENV_VAR_NAMES[selected.providerKey] || selected.providerKey.toUpperCase() + '_API_KEY'} or configure via settings (P key).`))
+        console.log()
+      }
+    }
+
+    let exitCode = 0
+    if (state.mode === 'openclaw') {
+      exitCode = await startOpenClaw(userSelected, state.config, { launchCli: true })
+    } else if (state.mode === 'opencode-desktop') {
+      exitCode = await startOpenCodeDesktop(userSelected, state.config)
+    } else if (state.mode === 'opencode') {
+      exitCode = await startOpenCode(userSelected, state.config)
+    } else {
+      exitCode = await startExternalTool(state.mode, userSelected, state.config)
+    }
+
+    process.exit(typeof exitCode === 'number' ? exitCode : 0)
+  }
+
+  async function installMissingToolAndLaunch(selected, installPlan) {
+    const currentPlan = installPlan || getToolInstallPlan(state.mode)
+    stopUi({ resetRawMode: true })
+
+    console.log(chalk.cyan(`  📦 Installing missing tool for ${state.mode}...`))
+    if (currentPlan?.summary) console.log(chalk.dim(`  ${currentPlan.summary}`))
+    if (currentPlan?.shellCommand) console.log(chalk.dim(`  ${currentPlan.shellCommand}`))
+    if (currentPlan?.note) console.log(chalk.dim(`  ${currentPlan.note}`))
+    console.log()
+
+    const installResult = await installToolWithPlan(currentPlan)
+    if (!installResult.ok) {
+      console.log(chalk.red(`  X Tool installation failed with exit code ${installResult.exitCode}.`))
+      if (currentPlan?.docsUrl) console.log(chalk.dim(`  Docs: ${currentPlan.docsUrl}`))
+      console.log()
+      process.exit(installResult.exitCode || 1)
+    }
+
+    if (shouldCheckMissingTool(state.mode) && !isToolInstalled(state.mode)) {
+      console.log(chalk.yellow('  ⚠ The installer finished, but the tool is still not reachable from this terminal session.'))
+      console.log(chalk.dim('  Restart your shell or add the tool bin directory to PATH, then retry the launch.'))
+      if (currentPlan?.docsUrl) console.log(chalk.dim(`  Docs: ${currentPlan.docsUrl}`))
+      console.log()
+      process.exit(1)
+    }
+
+    console.log(chalk.green('  ✓ Tool installed successfully. Continuing with the selected model...'))
+    console.log()
+    await launchSelectedModel(selected, { uiAlreadyStopped: true })
+  }
+
   // ─── Settings key test helper ───────────────────────────────────────────────
   // 📖 Fires a single ping to the selected provider to verify the API key works.
   async function testProviderKey(providerKey) {
@@ -383,6 +479,20 @@ export function createKeyHandler(ctx) {
     saveConfig(state.config)
   }
 
+  // 📖 Theme switches need to update both persisted preference and the live
+  // 📖 semantic palette immediately so every screen redraw adopts the new colors.
+  function applyThemeSetting(nextTheme) {
+    if (!state.config.settings) state.config.settings = {}
+    state.config.settings.theme = nextTheme
+    saveConfig(state.config)
+    detectActiveTheme(nextTheme)
+  }
+
+  function cycleGlobalTheme() {
+    const currentTheme = state.config.settings?.theme || 'auto'
+    applyThemeSetting(cycleThemeSetting(currentTheme))
+  }
+
   function resetInstallEndpointsOverlay() {
     state.installEndpointsOpen = false
     state.installEndpointsPhase = 'providers'
@@ -427,10 +537,320 @@ export function createKeyHandler(ctx) {
     state.installEndpointsErrorMsg = null
   }
 
+  // 📖 Persist current table-view preferences so sort/filter state survives restarts.
+  function persistUiSettings() {
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    state.config.settings.tierFilter = TIER_CYCLE[state.tierFilterMode]
+    state.config.settings.originFilter = ORIGIN_CYCLE[state.originFilterMode] ?? null
+    state.config.settings.sortColumn = state.sortColumn
+    state.config.settings.sortAsc = state.sortDirection === 'asc'
+    saveConfig(state.config)
+  }
+
+  // 📖 Shared table refresh helper so command-palette and hotkeys keep identical behavior.
+  function refreshVisibleSorted({ resetCursor = true } = {}) {
+    const visible = state.results.filter(r => !r.hidden)
+    state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+    if (resetCursor) {
+      state.cursor = 0
+      state.scrollOffset = 0
+      return
+    }
+    if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
+    adjustScrollOffset(state)
+  }
+
+  function setSortColumnFromCommand(col) {
+    if (state.sortColumn === col) {
+      state.sortDirection = state.sortDirection === 'asc' ? 'desc' : 'asc'
+    } else {
+      state.sortColumn = col
+      state.sortDirection = 'asc'
+    }
+    refreshVisibleSorted({ resetCursor: true })
+    persistUiSettings()
+  }
+
+  function setTierFilterFromCommand(tierLabel) {
+    const nextMode = tierLabel === null ? 0 : TIER_CYCLE.indexOf(tierLabel)
+    state.tierFilterMode = nextMode >= 0 ? nextMode : 0
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: true })
+    persistUiSettings()
+  }
+
+  function openSettingsOverlay() {
+    state.settingsOpen = true
+    state.settingsCursor = 0
+    state.settingsEditMode = false
+    state.settingsAddKeyMode = false
+    state.settingsEditBuffer = ''
+    state.settingsScrollOffset = 0
+  }
+
+  function openRecommendOverlay() {
+    state.recommendOpen = true
+    state.recommendPhase = 'questionnaire'
+    state.recommendQuestion = 0
+    state.recommendCursor = 0
+    state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+    state.recommendResults = []
+    state.recommendScrollOffset = 0
+  }
+
+  function openInstallEndpointsOverlay() {
+    state.installEndpointsOpen = true
+    state.installEndpointsPhase = 'providers'
+    state.installEndpointsCursor = 0
+    state.installEndpointsScrollOffset = 0
+    state.installEndpointsProviderKey = null
+    state.installEndpointsToolMode = null
+    state.installEndpointsConnectionMode = null
+    state.installEndpointsScope = null
+    state.installEndpointsSelectedModelIds = new Set()
+    state.installEndpointsErrorMsg = null
+    state.installEndpointsResult = null
+  }
+
+  function openFeedbackOverlay() {
+    state.feedbackOpen = true
+    state.bugReportBuffer = ''
+    state.bugReportStatus = 'idle'
+    state.bugReportError = null
+  }
+
+  function openChangelogOverlay() {
+    state.changelogOpen = true
+    state.changelogScrollOffset = 0
+    state.changelogPhase = 'index'
+    state.changelogCursor = 0
+    state.changelogSelectedVersion = null
+  }
+
+  function cycleToolMode() {
+    const modeOrder = getToolModeOrder()
+    const currentIndex = modeOrder.indexOf(state.mode)
+    const nextIndex = (currentIndex + 1) % modeOrder.length
+    state.mode = modeOrder[nextIndex]
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    state.config.settings.preferredToolMode = state.mode
+    saveConfig(state.config)
+  }
+
+  function resetViewSettings() {
+    state.tierFilterMode = 0
+    state.originFilterMode = 0
+    state.sortColumn = 'avg'
+    state.sortDirection = 'asc'
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    delete state.config.settings.tierFilter
+    delete state.config.settings.originFilter
+    delete state.config.settings.sortColumn
+    delete state.config.settings.sortAsc
+    saveConfig(state.config)
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: true })
+  }
+
+  function toggleFavoriteOnSelectedRow() {
+    const selected = state.visibleSorted[state.cursor]
+    if (!selected) return
+    const wasFavorite = selected.isFavorite
+    toggleFavoriteModel(state.config, selected.providerKey, selected.modelId)
+    syncFavoriteFlags(state.results, state.config)
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: false })
+
+    if (wasFavorite) {
+      state.cursor = 0
+      state.scrollOffset = 0
+      return
+    }
+
+    const selectedKey = toFavoriteKey(selected.providerKey, selected.modelId)
+    const newCursor = state.visibleSorted.findIndex(r => toFavoriteKey(r.providerKey, r.modelId) === selectedKey)
+    if (newCursor >= 0) state.cursor = newCursor
+    adjustScrollOffset(state)
+  }
+
+  function commandPaletteHasBlockingOverlay() {
+    return state.settingsOpen
+      || state.installEndpointsOpen
+      || state.toolInstallPromptOpen
+      || state.recommendOpen
+      || state.feedbackOpen
+      || state.helpVisible
+      || state.changelogOpen
+  }
+
+  function refreshCommandPaletteResults() {
+    const commands = buildCommandPaletteEntries()
+    state.commandPaletteResults = filterCommandPaletteEntries(commands, state.commandPaletteQuery)
+    if (state.commandPaletteCursor >= state.commandPaletteResults.length) {
+      state.commandPaletteCursor = Math.max(0, state.commandPaletteResults.length - 1)
+    }
+  }
+
+  function openCommandPalette() {
+    state.commandPaletteOpen = true
+    state.commandPaletteFrozenTable = null
+    state.commandPaletteQuery = ''
+    state.commandPaletteCursor = 0
+    state.commandPaletteScrollOffset = 0
+    refreshCommandPaletteResults()
+  }
+
+  function closeCommandPalette() {
+    state.commandPaletteOpen = false
+    state.commandPaletteFrozenTable = null
+    state.commandPaletteQuery = ''
+    state.commandPaletteCursor = 0
+    state.commandPaletteScrollOffset = 0
+    state.commandPaletteResults = []
+  }
+
+  function executeCommandPaletteEntry(entry) {
+    if (!entry?.id) return
+
+    if (entry.id.startsWith('filter-tier-')) {
+      setTierFilterFromCommand(entry.tierValue ?? null)
+      return
+    }
+
+    switch (entry.id) {
+      case 'filter-provider-cycle':
+        state.originFilterMode = (state.originFilterMode + 1) % ORIGIN_CYCLE.length
+        applyTierFilter()
+        refreshVisibleSorted({ resetCursor: true })
+        persistUiSettings()
+        return
+      case 'filter-configured-toggle':
+        state.hideUnconfiguredModels = !state.hideUnconfiguredModels
+        if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+        state.config.settings.hideUnconfiguredModels = state.hideUnconfiguredModels
+        saveConfig(state.config)
+        applyTierFilter()
+        refreshVisibleSorted({ resetCursor: true })
+        return
+      case 'sort-rank': return setSortColumnFromCommand('rank')
+      case 'sort-tier': return setSortColumnFromCommand('tier')
+      case 'sort-provider': return setSortColumnFromCommand('origin')
+      case 'sort-model': return setSortColumnFromCommand('model')
+      case 'sort-latest-ping': return setSortColumnFromCommand('ping')
+      case 'sort-avg-ping': return setSortColumnFromCommand('avg')
+      case 'sort-swe': return setSortColumnFromCommand('swe')
+      case 'sort-ctx': return setSortColumnFromCommand('ctx')
+      case 'sort-health': return setSortColumnFromCommand('condition')
+      case 'sort-verdict': return setSortColumnFromCommand('verdict')
+      case 'sort-stability': return setSortColumnFromCommand('stability')
+      case 'sort-uptime': return setSortColumnFromCommand('uptime')
+      case 'open-settings': return openSettingsOverlay()
+      case 'open-help':
+        state.helpVisible = true
+        state.helpScrollOffset = 0
+        return
+      case 'open-changelog': return openChangelogOverlay()
+      case 'open-feedback': return openFeedbackOverlay()
+      case 'open-recommend': return openRecommendOverlay()
+      case 'open-install-endpoints': return openInstallEndpointsOverlay()
+      case 'action-cycle-theme': return cycleGlobalTheme()
+      case 'action-cycle-tool-mode': return cycleToolMode()
+      case 'action-cycle-ping-mode': {
+        const currentIdx = PING_MODE_CYCLE.indexOf(state.pingMode)
+        const nextIdx = currentIdx >= 0 ? (currentIdx + 1) % PING_MODE_CYCLE.length : 0
+        setPingMode(PING_MODE_CYCLE[nextIdx], 'manual')
+        return
+      }
+      case 'action-toggle-favorite': return toggleFavoriteOnSelectedRow()
+      case 'action-reset-view': return resetViewSettings()
+      default:
+        return
+    }
+  }
+
   return async (str, key) => {
     if (!key) return
     noteUserActivity()
 
+    // 📖 Ctrl+P toggles the command palette from the main table only.
+    if (key.ctrl && key.name === 'p') {
+      if (state.commandPaletteOpen) {
+        closeCommandPalette()
+        return
+      }
+      if (!commandPaletteHasBlockingOverlay()) {
+        openCommandPalette()
+      }
+      return
+    }
+
+    // 📖 Command palette captures the keyboard while active.
+    if (state.commandPaletteOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      const pageStep = Math.max(1, (state.terminalRows || 1) - 10)
+
+      if (key.name === 'escape') {
+        closeCommandPalette()
+        return
+      }
+      if (key.name === 'up') {
+        const count = state.commandPaletteResults.length
+        if (count === 0) return
+        state.commandPaletteCursor = state.commandPaletteCursor > 0 ? state.commandPaletteCursor - 1 : count - 1
+        return
+      }
+      if (key.name === 'down') {
+        const count = state.commandPaletteResults.length
+        if (count === 0) return
+        state.commandPaletteCursor = state.commandPaletteCursor < count - 1 ? state.commandPaletteCursor + 1 : 0
+        return
+      }
+      if (key.name === 'pageup') {
+        state.commandPaletteCursor = Math.max(0, state.commandPaletteCursor - pageStep)
+        return
+      }
+      if (key.name === 'pagedown') {
+        const max = Math.max(0, state.commandPaletteResults.length - 1)
+        state.commandPaletteCursor = Math.min(max, state.commandPaletteCursor + pageStep)
+        return
+      }
+      if (key.name === 'home') {
+        state.commandPaletteCursor = 0
+        return
+      }
+      if (key.name === 'end') {
+        state.commandPaletteCursor = Math.max(0, state.commandPaletteResults.length - 1)
+        return
+      }
+      if (key.name === 'backspace') {
+        state.commandPaletteQuery = state.commandPaletteQuery.slice(0, -1)
+        state.commandPaletteCursor = 0
+        state.commandPaletteScrollOffset = 0
+        refreshCommandPaletteResults()
+        return
+      }
+      if (key.name === 'return') {
+        const selectedCommand = state.commandPaletteResults[state.commandPaletteCursor]
+        closeCommandPalette()
+        executeCommandPaletteEntry(selectedCommand)
+        return
+      }
+      if (str && str.length === 1 && !key.ctrl && !key.meta) {
+        state.commandPaletteQuery += str
+        state.commandPaletteCursor = 0
+        state.commandPaletteScrollOffset = 0
+        refreshCommandPaletteResults()
+        return
+      }
+      return
+    }
+
+    if (!state.feedbackOpen && !state.settingsEditMode && !state.settingsAddKeyMode && key.name === 'g' && !key.ctrl && !key.meta) {
+      cycleGlobalTheme()
+      return
+    }
+
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
     // 📖 Install Endpoints overlay: provider → tool → connection → scope → optional model subset.
@@ -614,6 +1034,44 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    if (state.toolInstallPromptOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      const installPlan = state.toolInstallPromptPlan || getToolInstallPlan(state.toolInstallPromptMode)
+      const installSupported = Boolean(installPlan?.supported)
+
+      if (key.name === 'escape') {
+        resetToolInstallPrompt()
+        return
+      }
+
+      if (installSupported && key.name === 'up') {
+        state.toolInstallPromptCursor = Math.max(0, state.toolInstallPromptCursor - 1)
+        return
+      }
+
+      if (installSupported && key.name === 'down') {
+        state.toolInstallPromptCursor = Math.min(1, state.toolInstallPromptCursor + 1)
+        return
+      }
+
+      if (key.name === 'return') {
+        if (!installSupported) {
+          resetToolInstallPrompt()
+          return
+        }
+
+        const selectedModel = state.toolInstallPromptModel
+        const shouldInstall = state.toolInstallPromptCursor === 0
+        resetToolInstallPrompt()
+
+        if (!shouldInstall || !selectedModel) return
+        await installMissingToolAndLaunch(selectedModel, installPlan)
+      }
+
+      return
+    }
+
     // 📖 Feedback overlay: intercept ALL keys while overlay is active.
     // 📖 Enter → send to Discord, Esc → cancel, Backspace → delete char, printable → append to buffer.
     if (state.feedbackOpen) {
@@ -1078,6 +1536,11 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        if (state.settingsCursor === themeRowIdx) {
+          cycleGlobalTheme()
+          return
+        }
+
         if (state.settingsCursor === cleanupLegacyProxyRowIdx) {
           runLegacyProxyCleanup()
           return
@@ -1098,6 +1561,7 @@ export function createKeyHandler(ctx) {
 
         // 📖 Enter edit mode for the selected provider's key
         const pk = providerKeys[state.settingsCursor]
+        if (!pk) return
         state.settingsEditBuffer = resolveApiKeys(state.config, pk)[0] ?? ''
         state.settingsEditMode = true
         return
@@ -1112,15 +1576,7 @@ export function createKeyHandler(ctx) {
         ) return
         // 📖 Theme configuration cycle inside settings
         if (state.settingsCursor === themeRowIdx) {
-          const themes = ['dark', 'light', 'auto']
-          const currentTheme = state.config.settings?.theme || 'dark'
-          const nextIndex = (themes.indexOf(currentTheme) + 1) % themes.length
-          state.config.settings.theme = themes[nextIndex]
-          saveConfig(state.config)
-          try {
-            const { detectActiveTheme } = await import('../src/theme.js')
-            detectActiveTheme(state.config.settings.theme)
-          } catch {}
+          cycleGlobalTheme()
           return
         }
         // 📖 Widths Warning toggle (disable/enable)
@@ -1142,6 +1598,8 @@ export function createKeyHandler(ctx) {
       if (key.name === 't') {
         if (
           state.settingsCursor === updateRowIdx
+          || state.settingsCursor === widthWarningRowIdx
+          || state.settingsCursor === themeRowIdx
           || state.settingsCursor === cleanupLegacyProxyRowIdx
           || state.settingsCursor === changelogViewRowIdx
         ) return
@@ -1149,6 +1607,7 @@ export function createKeyHandler(ctx) {
 
         // 📖 Test the selected provider's key (fires a real ping)
         const pk = providerKeys[state.settingsCursor]
+        if (!pk) return
         testProviderKey(pk)
         return
       }
@@ -1193,41 +1652,20 @@ export function createKeyHandler(ctx) {
     }
 
     // 📖 P key: open settings screen
-    if (key.name === 'p' && !key.shift) {
-      state.settingsOpen = true
-      state.settingsCursor = 0
-      state.settingsEditMode = false
-      state.settingsAddKeyMode = false
-      state.settingsEditBuffer = ''
-      state.settingsScrollOffset = 0
+    if (key.name === 'p' && !key.shift && !key.ctrl && !key.meta) {
+      openSettingsOverlay()
       return
     }
 
     // 📖 Q key: open Smart Recommend overlay
     if (key.name === 'q') {
-      state.recommendOpen = true
-      state.recommendPhase = 'questionnaire'
-      state.recommendQuestion = 0
-      state.recommendCursor = 0
-      state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
-      state.recommendResults = []
-      state.recommendScrollOffset = 0
+      openRecommendOverlay()
       return
     }
 
     // 📖 Y key: open Install Endpoints flow for configured providers.
     if (key.name === 'y') {
-      state.installEndpointsOpen = true
-      state.installEndpointsPhase = 'providers'
-      state.installEndpointsCursor = 0
-      state.installEndpointsScrollOffset = 0
-      state.installEndpointsProviderKey = null
-      state.installEndpointsToolMode = null
-      state.installEndpointsConnectionMode = null
-      state.installEndpointsScope = null
-      state.installEndpointsSelectedModelIds = new Set()
-      state.installEndpointsErrorMsg = null
-      state.installEndpointsResult = null
+      openInstallEndpointsOverlay()
       return
     }
 
@@ -1235,34 +1673,9 @@ export function createKeyHandler(ctx) {
 
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
-    // 📖 Helper: persist current UI view settings (tier, provider, sort) to config.settings
-    // 📖 Called after every T / D / sort key so preferences survive session restarts.
-    function persistUiSettings() {
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      state.config.settings.tierFilter = TIER_CYCLE[state.tierFilterMode]
-      state.config.settings.originFilter = ORIGIN_CYCLE[state.originFilterMode] ?? null
-      state.config.settings.sortColumn = state.sortColumn
-      state.config.settings.sortAsc = state.sortDirection === 'asc'
-      saveConfig(state.config)
-    }
-
     // 📖 Shift+R: reset all UI view settings to defaults (tier, sort, provider) and clear persisted config
     if (key.name === 'r' && key.shift) {
-      state.tierFilterMode = 0
-      state.originFilterMode = 0
-      state.sortColumn = 'avg'
-      state.sortDirection = 'asc'
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      delete state.config.settings.tierFilter
-      delete state.config.settings.originFilter
-      delete state.config.settings.sortColumn
-      delete state.config.settings.sortAsc
-      saveConfig(state.config)
-      applyTierFilter()
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      resetViewSettings()
       return
     }
 
@@ -1277,54 +1690,19 @@ export function createKeyHandler(ctx) {
 
     if (sortKeys[key.name] && !key.ctrl && !key.shift) {
       const col = sortKeys[key.name]
-      // 📖 Toggle direction if same column, otherwise reset to asc
-      if (state.sortColumn === col) {
-        state.sortDirection = state.sortDirection === 'asc' ? 'desc' : 'asc'
-      } else {
-        state.sortColumn = col
-        state.sortDirection = 'asc'
-      }
-      // 📖 Recompute visible sorted list and reset cursor to top to avoid stale index
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
-      persistUiSettings()
+      setSortColumnFromCommand(col)
       return
     }
 
     // 📖 F key: toggle favorite on the currently selected row and persist to config.
     if (key.name === 'f') {
-      const selected = state.visibleSorted[state.cursor]
-      if (!selected) return
-      const wasFavorite = selected.isFavorite
-      toggleFavoriteModel(state.config, selected.providerKey, selected.modelId)
-      syncFavoriteFlags(state.results, state.config)
-      applyTierFilter()
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-
-      // 📖 UX rule: when unpinning a favorite, jump back to the top of the list.
-      if (wasFavorite) {
-        state.cursor = 0
-        state.scrollOffset = 0
-        return
-      }
-
-      const selectedKey = toFavoriteKey(selected.providerKey, selected.modelId)
-      const newCursor = state.visibleSorted.findIndex(r => toFavoriteKey(r.providerKey, r.modelId) === selectedKey)
-      if (newCursor >= 0) state.cursor = newCursor
-      else if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
-      adjustScrollOffset(state)
+      toggleFavoriteOnSelectedRow()
       return
     }
 
     // 📖 I key: open Feedback overlay (anonymous Discord feedback)
     if (key.name === 'i') {
-      state.feedbackOpen = true
-      state.bugReportBuffer = ''
-      state.bugReportStatus = 'idle'
-      state.bugReportError = null
+      openFeedbackOverlay()
       return
     }
 
@@ -1399,13 +1777,7 @@ export function createKeyHandler(ctx) {
 
     // 📖 Mode toggle key: Z cycles through the supported tool targets.
     if (key.name === 'z') {
-      const modeOrder = getToolModeOrder()
-      const currentIndex = modeOrder.indexOf(state.mode)
-      const nextIndex = (currentIndex + 1) % modeOrder.length
-      state.mode = modeOrder[nextIndex]
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      state.config.settings.preferredToolMode = state.mode
-      saveConfig(state.config)
+      cycleToolMode()
       return
     }
 
@@ -1442,46 +1814,24 @@ export function createKeyHandler(ctx) {
       // 📖 Use the cached visible+sorted array — guaranteed to match what's on screen
       const selected = state.visibleSorted[state.cursor]
       if (!selected) return // 📖 Guard: empty visible list (all filtered out)
-      // 📖 Allow selecting ANY model (even timeout/down) - user knows what they're doing
-      userSelected = { modelId: selected.modelId, label: selected.label, tier: selected.tier, providerKey: selected.providerKey }
-
-      // 📖 Stop everything and act on selection immediately
-      readline.emitKeypressEvents(process.stdin)
-      process.stdin.setRawMode(true)
-      stopUi()
-
-      // 📖 Show selection with status
-      if (selected.status === 'timeout') {
-        console.log(chalk.yellow(`  ⚠ Selected: ${selected.label} (currently timing out)`))
-      } else if (selected.status === 'down') {
-        console.log(chalk.red(`  ⚠ Selected: ${selected.label} (currently down)`))
-      } else {
-        console.log(chalk.cyan(`  ✓ Selected: ${selected.label}`))
-      }
-      console.log()
-
-      // 📖 Warn if no API key is configured for the selected model's provider
-      if (state.mode !== 'openclaw') {
-        const selectedApiKey = getApiKey(state.config, selected.providerKey)
-        if (!selectedApiKey) {
-          console.log(chalk.yellow(`  Warning: No API key configured for ${selected.providerKey}.`))
-          console.log(chalk.yellow(`  The selected tool may not be able to use ${selected.label}.`))
-          console.log(chalk.dim(`  Set ${ENV_VAR_NAMES[selected.providerKey] || selected.providerKey.toUpperCase() + '_API_KEY'} or configure via settings (P key).`))
-          console.log()
+      if (shouldCheckMissingTool(state.mode) && !isToolInstalled(state.mode)) {
+        state.toolInstallPromptOpen = true
+        state.toolInstallPromptCursor = 0
+        state.toolInstallPromptScrollOffset = 0
+        state.toolInstallPromptMode = state.mode
+        state.toolInstallPromptModel = {
+          modelId: selected.modelId,
+          label: selected.label,
+          tier: selected.tier,
+          providerKey: selected.providerKey,
+          status: selected.status,
         }
+        state.toolInstallPromptPlan = getToolInstallPlan(state.mode)
+        state.toolInstallPromptErrorMsg = null
+        return
       }
 
-      // 📖 Dispatch to the correct integration based on active mode
-      if (state.mode === 'openclaw') {
-        await startOpenClaw(userSelected, state.config)
-      } else if (state.mode === 'opencode-desktop') {
-        await startOpenCodeDesktop(userSelected, state.config)
-      } else if (state.mode === 'opencode') {
-        await startOpenCode(userSelected, state.config)
-      } else {
-        await startExternalTool(state.mode, userSelected, state.config)
-      }
-      process.exit(0)
+      await launchSelectedModel(selected)
     }
   }
 }