free-coding-models 0.2.1 → 0.2.3

package/src/key-handler.js

@@ -4,7 +4,7 @@
  *
  * @details
  *   This module encapsulates the full onKeyPress switch used by the TUI,
- *   including settings navigation, overlays, profile management, and
+ *   including settings navigation, install-endpoint flow, overlays, profile management, and
  *   OpenCode/OpenClaw launch actions. It also keeps the live key bindings
  *   aligned with the highlighted letters shown in the table headers.
  *
@@ -19,9 +19,10 @@
  *   - `parseProviderModelIds` — extract model ids from an OpenAI-style `/models` payload
  *   - `listProviderTestModels` — build an ordered candidate list for provider key verification
  *   - `classifyProviderTestOutcome` — convert attempted HTTP codes into a settings badge state
+ *   - `buildProviderTestDetail` — turn probe attempts into a readable failure explanation
  *   - `createKeyHandler` — returns the async keypress handler
  *
- * @exports { buildProviderModelsUrl, parseProviderModelIds, listProviderTestModels, classifyProviderTestOutcome, createKeyHandler }
+ * @exports { buildProviderModelsUrl, parseProviderModelIds, listProviderTestModels, classifyProviderTestOutcome, buildProviderTestDetail, createKeyHandler }
  */
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
@@ -31,6 +32,17 @@ const PROVIDER_TEST_MODEL_OVERRIDES = {
   nvidia: ['deepseek-ai/deepseek-v3.1-terminus', 'openai/gpt-oss-120b'],
 }
 
+// 📖 Settings key tests retry retryable failures across several models so a
+// 📖 single stale catalog entry or transient timeout does not mark a valid key as dead.
+const SETTINGS_TEST_MAX_ATTEMPTS = 10
+const SETTINGS_TEST_RETRY_DELAY_MS = 4000
+
+// 📖 Sleep helper kept local to this module so the Settings key test flow can
+// 📖 back off between retries without leaking timer logic into the rest of the TUI.
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
 /**
  * 📖 buildProviderModelsUrl derives the matching `/models` endpoint for providers
  * 📖 that expose an OpenAI-compatible model list next to `/chat/completions`.
@@ -86,16 +98,52 @@ export function listProviderTestModels(providerKey, src, discoveredModelIds = []
  * 📖 - `rate_limited` means the key is valid but the provider is currently throttling
  * 📖 - `no_callable_model` means the provider responded, but none of the attempted models were callable
  * @param {string[]} codes
- * @returns {'ok'|'fail'|'rate_limited'|'no_callable_model'}
+ * @returns {'ok'|'auth_error'|'rate_limited'|'no_callable_model'|'fail'}
  */
 export function classifyProviderTestOutcome(codes) {
   if (codes.includes('200')) return 'ok'
-  if (codes.includes('401') || codes.includes('403')) return 'fail'
+  if (codes.includes('401') || codes.includes('403')) return 'auth_error'
   if (codes.length > 0 && codes.every(code => code === '429')) return 'rate_limited'
   if (codes.length > 0 && codes.every(code => code === '404' || code === '410')) return 'no_callable_model'
   return 'fail'
 }
 
+// 📖 buildProviderTestDetail explains why the Settings `T` probe failed, with
+// 📖 enough context for the user to know whether the key, model list, or provider
+// 📖 quota is the problem.
+export function buildProviderTestDetail(providerLabel, outcome, attempts = [], discoveryNote = '') {
+  const introByOutcome = {
+    missing_key: `${providerLabel} has no saved API key right now, so no authenticated test could be sent.`,
+    ok: `${providerLabel} accepted the key.`,
+    auth_error: `${providerLabel} rejected the configured key with an authentication error.`,
+    rate_limited: `${providerLabel} throttled every probe, so the key may still be valid but is currently rate-limited.`,
+    no_callable_model: `${providerLabel} answered the requests, but none of the probed models were callable on its chat endpoint.`,
+    fail: `${providerLabel} never returned a successful probe during the retry window.`,
+  }
+
+  const hintsByOutcome = {
+    missing_key: 'Save the key with Enter in Settings, then rerun T.',
+    ok: attempts.length > 0 ? `Validated on ${attempts[attempts.length - 1].model}.` : 'The provider returned a success response.',
+    auth_error: 'This usually means the saved key is invalid, expired, revoked, or truncated before it reached disk.',
+    rate_limited: 'Wait for the provider quota window to reset, then rerun T.',
+    no_callable_model: 'The provider catalog or repo defaults likely drifted; try another model family or refresh the catalog.',
+    fail: 'This can be caused by timeouts, 5xx responses, or a provider-side outage.',
+  }
+
+  const attemptSummary = attempts.length > 0
+    ? `Attempts: ${attempts.map(({ attempt, model, code }) => `#${attempt} ${model} -> ${code}`).join(' | ')}`
+    : 'Attempts: none'
+
+  const segments = [
+    introByOutcome[outcome] || introByOutcome.fail,
+    hintsByOutcome[outcome] || hintsByOutcome.fail,
+    discoveryNote,
+    attemptSummary,
+  ].filter(Boolean)
+
+  return segments.join(' ')
+}
+
 export function createKeyHandler(ctx) {
   const {
     state,
@@ -115,6 +163,10 @@ export function createKeyHandler(ctx) {
     saveAsProfile,
     setActiveProfile,
     saveConfig,
+    getConfiguredInstallableProviders,
+    getInstallTargetModes,
+    getProviderCatalogModels,
+    installProviderEndpoints,
     syncFavoriteFlags,
     toggleFavoriteModel,
     sortResultsWithPinnedFavorites,
@@ -168,11 +220,19 @@ export function createKeyHandler(ctx) {
     const src = sources[providerKey]
     if (!src) return
     const testKey = getApiKey(state.config, providerKey)
-    if (!testKey) { state.settingsTestResults[providerKey] = 'fail'; return }
+    const providerLabel = src.name || providerKey
+    if (!state.settingsTestDetails) state.settingsTestDetails = {}
+    if (!testKey) {
+      state.settingsTestResults[providerKey] = 'missing_key'
+      state.settingsTestDetails[providerKey] = buildProviderTestDetail(providerLabel, 'missing_key')
+      return
+    }
 
     state.settingsTestResults[providerKey] = 'pending'
+    state.settingsTestDetails[providerKey] = `Testing ${providerLabel} across up to ${SETTINGS_TEST_MAX_ATTEMPTS} probes...`
     const discoveredModelIds = []
     const modelsUrl = buildProviderModelsUrl(src.url)
+    let discoveryNote = ''
 
     if (modelsUrl) {
       try {
@@ -185,30 +245,53 @@ export function createKeyHandler(ctx) {
         if (modelsResp.ok) {
           const data = await modelsResp.json()
           discoveredModelIds.push(...parseProviderModelIds(data))
+          discoveryNote = discoveredModelIds.length > 0
+            ? `Live model discovery returned ${discoveredModelIds.length} ids.`
+            : 'Live model discovery succeeded but returned no callable ids.'
+        } else {
+          discoveryNote = `Live model discovery returned HTTP ${modelsResp.status}; falling back to the repo catalog.`
         }
-      } catch {
+      } catch (err) {
         // 📖 Discovery failure is non-fatal; we still have repo-defined fallbacks.
+        discoveryNote = `Live model discovery failed (${err?.name || 'error'}); falling back to the repo catalog.`
       }
     }
 
     const candidateModels = listProviderTestModels(providerKey, src, discoveredModelIds)
-    if (candidateModels.length === 0) { state.settingsTestResults[providerKey] = 'fail'; return }
-    const attemptedCodes = []
+    if (candidateModels.length === 0) {
+      state.settingsTestResults[providerKey] = 'fail'
+      state.settingsTestDetails[providerKey] = buildProviderTestDetail(providerLabel, 'fail', [], discoveryNote || 'No candidate model was available for probing.')
+      return
+    }
+    const attempts = []
 
-    for (const testModel of candidateModels.slice(0, 8)) {
+    for (let attemptIndex = 0; attemptIndex < SETTINGS_TEST_MAX_ATTEMPTS; attemptIndex++) {
+      const testModel = candidateModels[attemptIndex % candidateModels.length]
       const { code } = await ping(testKey, testModel, providerKey, src.url)
-      attemptedCodes.push(code)
+      attempts.push({ attempt: attemptIndex + 1, model: testModel, code })
+
       if (code === '200') {
         state.settingsTestResults[providerKey] = 'ok'
+        state.settingsTestDetails[providerKey] = buildProviderTestDetail(providerLabel, 'ok', attempts, discoveryNote)
         return
       }
-      if (code === '401' || code === '403') {
-        state.settingsTestResults[providerKey] = 'fail'
+
+      const outcome = classifyProviderTestOutcome(attempts.map(({ code: attemptCode }) => attemptCode))
+      if (outcome === 'auth_error') {
+        state.settingsTestResults[providerKey] = 'auth_error'
+        state.settingsTestDetails[providerKey] = buildProviderTestDetail(providerLabel, 'auth_error', attempts, discoveryNote)
         return
       }
+
+      if (attemptIndex < SETTINGS_TEST_MAX_ATTEMPTS - 1) {
+        state.settingsTestDetails[providerKey] = `Testing ${providerLabel}... probe ${attemptIndex + 1}/${SETTINGS_TEST_MAX_ATTEMPTS} failed on ${testModel} (${code}). Retrying in ${SETTINGS_TEST_RETRY_DELAY_MS / 1000}s.`
+        await sleep(SETTINGS_TEST_RETRY_DELAY_MS)
+      }
     }
 
-    state.settingsTestResults[providerKey] = classifyProviderTestOutcome(attemptedCodes)
+    const finalOutcome = classifyProviderTestOutcome(attempts.map(({ code }) => code))
+    state.settingsTestResults[providerKey] = finalOutcome
+    state.settingsTestDetails[providerKey] = buildProviderTestDetail(providerLabel, finalOutcome, attempts, discoveryNote)
   }
 
   // 📖 Manual update checker from settings; keeps status visible in maintenance row.
@@ -242,6 +325,48 @@ export function createKeyHandler(ctx) {
     runUpdate(latestVersion)
   }
 
+  function resetInstallEndpointsOverlay() {
+    state.installEndpointsOpen = false
+    state.installEndpointsPhase = 'providers'
+    state.installEndpointsCursor = 0
+    state.installEndpointsScrollOffset = 0
+    state.installEndpointsProviderKey = null
+    state.installEndpointsToolMode = null
+    state.installEndpointsScope = null
+    state.installEndpointsSelectedModelIds = new Set()
+    state.installEndpointsErrorMsg = null
+    state.installEndpointsResult = null
+  }
+
+  async function runInstallEndpointsFlow() {
+    const selectedModelIds = [...state.installEndpointsSelectedModelIds]
+    const result = installProviderEndpoints(
+      state.config,
+      state.installEndpointsProviderKey,
+      state.installEndpointsToolMode,
+      {
+        scope: state.installEndpointsScope,
+        modelIds: selectedModelIds,
+      }
+    )
+
+    state.installEndpointsResult = {
+      type: 'success',
+      title: `${result.modelCount} models installed into ${result.toolLabel}`,
+      lines: [
+        chalk.bold(`Provider:`) + ` ${result.providerLabel}`,
+        chalk.bold(`Scope:`) + ` ${result.scope === 'selected' ? 'Selected models' : 'All current models'}`,
+        chalk.bold(`Managed Id:`) + ` ${result.providerId}`,
+        chalk.bold(`Config:`) + ` ${result.path}`,
+        ...(result.extraPath ? [chalk.bold(`Secrets:`) + ` ${result.extraPath}`] : []),
+      ],
+    }
+    state.installEndpointsPhase = 'result'
+    state.installEndpointsCursor = 0
+    state.installEndpointsScrollOffset = 0
+    state.installEndpointsErrorMsg = null
+  }
+
   return async (str, key) => {
     if (!key) return
     noteUserActivity()
@@ -287,6 +412,186 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Install Endpoints overlay: provider → tool → scope → optional model subset.
+    if (state.installEndpointsOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      const providerChoices = getConfiguredInstallableProviders(state.config)
+      const toolChoices = getInstallTargetModes()
+      const modelChoices = state.installEndpointsProviderKey
+        ? getProviderCatalogModels(state.installEndpointsProviderKey)
+        : []
+      const pageStep = Math.max(1, (state.terminalRows || 1) - 4)
+
+      const maxIndexByPhase = () => {
+        if (state.installEndpointsPhase === 'providers') return Math.max(0, providerChoices.length - 1)
+        if (state.installEndpointsPhase === 'tools') return Math.max(0, toolChoices.length - 1)
+        if (state.installEndpointsPhase === 'scope') return 1
+        if (state.installEndpointsPhase === 'models') return Math.max(0, modelChoices.length - 1)
+        return 0
+      }
+
+      if (key.name === 'up') {
+        state.installEndpointsCursor = Math.max(0, state.installEndpointsCursor - 1)
+        return
+      }
+      if (key.name === 'down') {
+        state.installEndpointsCursor = Math.min(maxIndexByPhase(), state.installEndpointsCursor + 1)
+        return
+      }
+      if (key.name === 'pageup') {
+        state.installEndpointsCursor = Math.max(0, state.installEndpointsCursor - pageStep)
+        return
+      }
+      if (key.name === 'pagedown') {
+        state.installEndpointsCursor = Math.min(maxIndexByPhase(), state.installEndpointsCursor + pageStep)
+        return
+      }
+      if (key.name === 'home') {
+        state.installEndpointsCursor = 0
+        return
+      }
+      if (key.name === 'end') {
+        state.installEndpointsCursor = maxIndexByPhase()
+        return
+      }
+
+      if (key.name === 'escape') {
+        state.installEndpointsErrorMsg = null
+        if (state.installEndpointsPhase === 'providers' || state.installEndpointsPhase === 'result') {
+          resetInstallEndpointsOverlay()
+          return
+        }
+        if (state.installEndpointsPhase === 'tools') {
+          state.installEndpointsPhase = 'providers'
+          state.installEndpointsCursor = 0
+          state.installEndpointsScrollOffset = 0
+          return
+        }
+        if (state.installEndpointsPhase === 'scope') {
+          state.installEndpointsPhase = 'tools'
+          state.installEndpointsCursor = 0
+          state.installEndpointsScrollOffset = 0
+          return
+        }
+        if (state.installEndpointsPhase === 'models') {
+          state.installEndpointsPhase = 'scope'
+          state.installEndpointsCursor = state.installEndpointsScope === 'selected' ? 1 : 0
+          state.installEndpointsScrollOffset = 0
+          return
+        }
+      }
+
+      if (state.installEndpointsPhase === 'providers') {
+        if (key.name === 'return') {
+          const selectedProvider = providerChoices[state.installEndpointsCursor]
+          if (!selectedProvider) {
+            state.installEndpointsErrorMsg = '⚠ No installable configured provider is available yet.'
+            return
+          }
+          state.installEndpointsProviderKey = selectedProvider.providerKey
+          state.installEndpointsToolMode = null
+          state.installEndpointsScope = null
+          state.installEndpointsSelectedModelIds = new Set()
+          state.installEndpointsPhase = 'tools'
+          state.installEndpointsCursor = 0
+          state.installEndpointsScrollOffset = 0
+          state.installEndpointsErrorMsg = null
+        }
+        return
+      }
+
+      if (state.installEndpointsPhase === 'tools') {
+        if (key.name === 'return') {
+          const selectedToolMode = toolChoices[state.installEndpointsCursor]
+          if (!selectedToolMode) return
+          state.installEndpointsToolMode = selectedToolMode
+          state.installEndpointsPhase = 'scope'
+          state.installEndpointsCursor = 0
+          state.installEndpointsScrollOffset = 0
+          state.installEndpointsErrorMsg = null
+        }
+        return
+      }
+
+      if (state.installEndpointsPhase === 'scope') {
+        if (key.name === 'return') {
+          state.installEndpointsScope = state.installEndpointsCursor === 1 ? 'selected' : 'all'
+          state.installEndpointsScrollOffset = 0
+          state.installEndpointsErrorMsg = null
+          if (state.installEndpointsScope === 'all') {
+            try {
+              await runInstallEndpointsFlow()
+            } catch (error) {
+              state.installEndpointsResult = {
+                type: 'error',
+                title: 'Install failed',
+                lines: [error instanceof Error ? error.message : String(error)],
+              }
+              state.installEndpointsPhase = 'result'
+            }
+            return
+          }
+
+          state.installEndpointsSelectedModelIds = new Set()
+          state.installEndpointsPhase = 'models'
+          state.installEndpointsCursor = 0
+        }
+        return
+      }
+
+      if (state.installEndpointsPhase === 'models') {
+        if (key.name === 'a') {
+          if (state.installEndpointsSelectedModelIds.size === modelChoices.length) {
+            state.installEndpointsSelectedModelIds = new Set()
+          } else {
+            state.installEndpointsSelectedModelIds = new Set(modelChoices.map((model) => model.modelId))
+          }
+          state.installEndpointsErrorMsg = null
+          return
+        }
+
+        if (key.name === 'space') {
+          const selectedModel = modelChoices[state.installEndpointsCursor]
+          if (!selectedModel) return
+          const next = new Set(state.installEndpointsSelectedModelIds)
+          if (next.has(selectedModel.modelId)) next.delete(selectedModel.modelId)
+          else next.add(selectedModel.modelId)
+          state.installEndpointsSelectedModelIds = next
+          state.installEndpointsErrorMsg = null
+          return
+        }
+
+        if (key.name === 'return') {
+          if (state.installEndpointsSelectedModelIds.size === 0) {
+            state.installEndpointsErrorMsg = '⚠ Select at least one model before installing.'
+            return
+          }
+
+          try {
+            await runInstallEndpointsFlow()
+          } catch (error) {
+            state.installEndpointsResult = {
+              type: 'error',
+              title: 'Install failed',
+              lines: [error instanceof Error ? error.message : String(error)],
+            }
+            state.installEndpointsPhase = 'result'
+          }
+        }
+        return
+      }
+
+      if (state.installEndpointsPhase === 'result') {
+        if (key.name === 'return' || key.name === 'y') {
+          resetInstallEndpointsOverlay()
+        }
+        return
+      }
+
+      return
+    }
+
     // 📖 Feature Request overlay: intercept ALL keys while overlay is active.
     // 📖 Enter → send to Discord, Esc → cancel, Backspace → delete char, printable → append to buffer.
     if (state.featureRequestOpen) {
@@ -945,6 +1250,21 @@ export function createKeyHandler(ctx) {
       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.installEndpointsScope = null
+      state.installEndpointsSelectedModelIds = new Set()
+      state.installEndpointsErrorMsg = null
+      state.installEndpointsResult = null
+      return
+    }
+
     // 📖 Shift+P: cycle through profiles (or show profile picker)
     if (key.name === 'p' && key.shift) {
       const profiles = listProfiles(state.config)
@@ -1007,11 +1327,11 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Sorting keys: R=rank, Y=tier, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime, G=usage
-    // 📖 T is reserved for tier filter cycling — tier sort moved to Y
+    // 📖 Sorting keys: R=rank, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime, G=usage
+    // 📖 T is reserved for tier filter cycling. Y now opens the install-endpoints flow.
     // 📖 D is now reserved for provider filter cycling
     const sortKeys = {
-      'r': 'rank', 'y': 'tier', 'o': 'origin', 'm': 'model',
+      'r': 'rank', 'o': 'origin', 'm': 'model',
       'l': 'ping', 'a': 'avg', 's': 'swe', 'c': 'ctx', 'h': 'condition', 'v': 'verdict', 'b': 'stability', 'u': 'uptime', 'g': 'usage'
     }
 

package/src/opencode.js

@@ -425,7 +425,7 @@ export async function startOpenCode(model, fcmConfig) {
       config.provider.codestral = {
         npm: '@ai-sdk/openai-compatible',
         name: 'Mistral Codestral',
-        options: { baseURL: 'https://codestral.mistral.ai/v1', apiKey: '{env:CODESTRAL_API_KEY}' },
+        options: { baseURL: 'https://api.mistral.ai/v1', apiKey: '{env:CODESTRAL_API_KEY}' },
         models: {}
       }
     } else if (providerKey === 'hyperbolic') {
@@ -889,7 +889,7 @@ export async function startOpenCodeDesktop(model, fcmConfig) {
       config.provider.codestral = {
         npm: '@ai-sdk/openai-compatible',
         name: 'Mistral Codestral',
-        options: { baseURL: 'https://codestral.mistral.ai/v1', apiKey: '{env:CODESTRAL_API_KEY}' },
+        options: { baseURL: 'https://api.mistral.ai/v1', apiKey: '{env:CODESTRAL_API_KEY}' },
         models: {}
       }
     } else if (providerKey === 'hyperbolic') {