free-coding-models 0.2.17 → 0.3.1

package/src/tool-launchers.js

@@ -15,11 +15,23 @@
  *   For those, we prefer a transparent warning over pretending the integration is
  *   fully official. The user still gets a reproducible env/config handoff.
  *
+ *   📖 Goose: writes custom provider JSON + secrets.yaml + updates config.yaml (GOOSE_PROVIDER/GOOSE_MODEL)
+ *   📖 Crush: writes crush.json with provider config + models.large/small defaults
+ *   📖 Pi: uses --provider/--model CLI flags for guaranteed auto-selection
+ *   📖 Aider: writes ~/.aider.conf.yml + passes --model flag
+ *   📖 Claude Code: uses ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN only (mirrors free-claude-code)
+ *   📖 Codex CLI: uses a custom model_provider override so Codex stays in explicit API-provider mode
+ *   📖 Gemini CLI: proxy mode is capability-gated because older builds do not support custom base URL routing cleanly
+ *
  * @functions
  *   → `resolveLauncherModelId` — choose the provider-specific id or proxy slug for a launch
+ *   → `buildCodexProxyArgs` — force Codex into a proxy-backed custom provider config
+ *   → `inspectGeminiCliSupport` — detect whether the installed Gemini CLI can use proxy mode safely
+ *   → `writeGooseConfig` — install provider + set GOOSE_PROVIDER/GOOSE_MODEL in config.yaml
+ *   → `writeCrushConfig` — write provider + models.large/small to crush.json
  *   → `startExternalTool` — configure and launch the selected external tool mode
  *
- * @exports resolveLauncherModelId, startExternalTool
+ * @exports resolveLauncherModelId, buildCodexProxyArgs, inspectGeminiCliSupport, startExternalTool
  *
  * @see src/tool-metadata.js
  * @see src/provider-metadata.js
@@ -27,16 +39,42 @@
  */
 
 import chalk from 'chalk'
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs'
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, copyFileSync } from 'fs'
 import { homedir } from 'os'
-import { dirname, join } from 'path'
-import { spawn } from 'child_process'
+import { delimiter, dirname, join } from 'path'
+import { spawn, spawnSync } from 'child_process'
 import { sources } from '../sources.js'
 import { PROVIDER_COLOR } from './render-table.js'
 import { getApiKey, getProxySettings } from './config.js'
 import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 import { ensureProxyRunning, resolveProxyModelId } from './opencode.js'
+import { PROVIDER_METADATA } from './provider-metadata.js'
+
+const OPENAI_COMPAT_ENV_KEYS = [
+  'OPENAI_API_KEY',
+  'OPENAI_BASE_URL',
+  'OPENAI_API_BASE',
+  'OPENAI_MODEL',
+  'LLM_API_KEY',
+  'LLM_BASE_URL',
+  'LLM_MODEL',
+]
+const ANTHROPIC_ENV_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_MODEL',
+]
+const GEMINI_ENV_KEYS = [
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+  'GOOGLE_GEMINI_BASE_URL',
+  'GOOGLE_VERTEX_BASE_URL',
+]
+const PROXY_SANITIZED_ENV_KEYS = [...OPENAI_COMPAT_ENV_KEYS, ...ANTHROPIC_ENV_KEYS, ...GEMINI_ENV_KEYS]
+const GEMINI_PROXY_MIN_VERSION = '0.34.0'
+const EXPERIMENTAL_PROXY_TOOLS_NOTE = 'FCM Proxy V2 support for external tools is still in beta, so some launch and authentication flows can remain flaky while the integration stabilizes.'
 
 function ensureDir(filePath) {
   const dir = dirname(filePath)
@@ -73,6 +111,16 @@ function getProviderBaseUrl(providerKey) {
     .replace(/\/predictions$/i, '')
 }
 
+function deleteEnvKeys(env, keys) {
+  for (const key of keys) delete env[key]
+}
+
+function cloneInheritedEnv(inheritedEnv = process.env, sanitizeKeys = []) {
+  const env = { ...inheritedEnv }
+  deleteEnvKeys(env, sanitizeKeys)
+  return env
+}
+
 function applyOpenAiCompatEnv(env, apiKey, baseUrl, modelId) {
   if (!apiKey || !baseUrl || !modelId) return env
   env.OPENAI_API_KEY = apiKey
@@ -98,17 +146,23 @@ export function resolveLauncherModelId(model, useProxy = false) {
   return model?.modelId ?? ''
 }
 
-function buildToolEnv(mode, model, config) {
+export function buildToolEnv(mode, model, config, options = {}) {
+  const {
+    sanitize = false,
+    includeCompatDefaults = true,
+    includeProviderEnv = true,
+    inheritedEnv = process.env,
+  } = options
   const providerKey = model.providerKey
   const providerUrl = sources[providerKey]?.url || ''
   const baseUrl = getProviderBaseUrl(providerKey)
   const apiKey = getApiKey(config, providerKey)
-  const env = { ...process.env }
+  const env = cloneInheritedEnv(inheritedEnv, sanitize ? PROXY_SANITIZED_ENV_KEYS : [])
   const providerEnvName = ENV_VAR_NAMES[providerKey]
-  if (providerEnvName && apiKey) env[providerEnvName] = apiKey
+  if (includeProviderEnv && providerEnvName && apiKey) env[providerEnvName] = apiKey
 
   // 📖 OpenAI-compatible defaults reused by multiple CLIs.
-  if (apiKey && baseUrl) {
+  if (includeCompatDefaults && apiKey && baseUrl) {
     env.OPENAI_API_KEY = apiKey
     env.OPENAI_BASE_URL = baseUrl
     env.OPENAI_API_BASE = baseUrl
@@ -126,6 +180,7 @@ function buildToolEnv(mode, model, config) {
   }
 
   if (mode === 'gemini' && apiKey && baseUrl) {
+    env.GEMINI_API_KEY = apiKey
     env.GOOGLE_API_KEY = apiKey
     env.GOOGLE_GEMINI_BASE_URL = baseUrl
   }
@@ -133,6 +188,114 @@ function buildToolEnv(mode, model, config) {
   return { env, apiKey, baseUrl, providerUrl }
 }
 
+export function buildCodexProxyArgs(baseUrl) {
+  return [
+    '-c', 'model_provider="fcm_proxy"',
+    '-c', 'model_providers.fcm_proxy.name="FCM Proxy V2"',
+    '-c', `model_providers.fcm_proxy.base_url=${JSON.stringify(baseUrl)}`,
+    '-c', 'model_providers.fcm_proxy.env_key="FCM_PROXY_API_KEY"',
+    '-c', 'model_providers.fcm_proxy.wire_api="responses"',
+  ]
+}
+
+function compareSemver(a, b) {
+  const left = String(a || '').split('.').map(part => Number.parseInt(part, 10) || 0)
+  const right = String(b || '').split('.').map(part => Number.parseInt(part, 10) || 0)
+  const length = Math.max(left.length, right.length)
+  for (let idx = 0; idx < length; idx++) {
+    const lhs = left[idx] || 0
+    const rhs = right[idx] || 0
+    if (lhs > rhs) return 1
+    if (lhs < rhs) return -1
+  }
+  return 0
+}
+
+function findExecutableOnPath(command) {
+  const pathValue = process.env.PATH || ''
+  const candidates = process.platform === 'win32'
+    ? [command, `${command}.cmd`, `${command}.exe`]
+    : [command]
+
+  for (const dir of pathValue.split(delimiter).filter(Boolean)) {
+    for (const candidate of candidates) {
+      const fullPath = join(dir, candidate)
+      try {
+        accessSync(fullPath, constants.X_OK)
+        return fullPath
+      } catch { /* not executable */ }
+    }
+  }
+  return null
+}
+
+function findPackageJsonUpwards(startPath) {
+  let current = dirname(startPath)
+  while (current && current !== dirname(current)) {
+    const packageJsonPath = join(current, 'package.json')
+    if (existsSync(packageJsonPath)) return packageJsonPath
+    current = dirname(current)
+  }
+  return null
+}
+
+function detectGeminiCliVersion(binaryPath) {
+  if (!binaryPath) return null
+  try {
+    const realPath = realpathSync(binaryPath)
+    const versionMatch = realPath.match(/gemini-cli[\\/](\d+\.\d+\.\d+)(?:[\\/]|$)/)
+    if (versionMatch?.[1]) return versionMatch[1]
+
+    const packageJsonPath = findPackageJsonUpwards(realPath)
+    if (!packageJsonPath) return null
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    if (typeof pkg?.version === 'string' && pkg.version.length > 0) {
+      return pkg.version
+    }
+  } catch { /* best effort */ }
+  return null
+}
+
+export function extractGeminiConfigError(output) {
+  const text = String(output || '').trim()
+  if (!text.includes('Invalid configuration in ')) return null
+  const lines = text.split(/\r?\n/).filter(Boolean)
+  return lines.slice(0, 8).join('\n')
+}
+
+export function inspectGeminiCliSupport(options = {}) {
+  const binaryPath = options.binaryPath || findExecutableOnPath(options.command || 'gemini')
+  if (!binaryPath) {
+    return {
+      installed: false,
+      version: null,
+      supportsProxyBaseUrl: false,
+      configError: null,
+      reason: 'Gemini CLI is not installed in PATH.',
+    }
+  }
+
+  const version = options.version || detectGeminiCliVersion(binaryPath)
+  const helpResult = options.helpResult || spawnSync(binaryPath, ['--help'], {
+    encoding: 'utf8',
+    timeout: 5000,
+    env: options.inheritedEnv || process.env,
+  })
+  const helpOutput = `${helpResult.stdout || ''}\n${helpResult.stderr || ''}`.trim()
+  const configError = extractGeminiConfigError(helpOutput)
+  const supportsProxyBaseUrl = version ? compareSemver(version, GEMINI_PROXY_MIN_VERSION) >= 0 : false
+
+  return {
+    installed: true,
+    version,
+    supportsProxyBaseUrl,
+    configError,
+    reason: supportsProxyBaseUrl
+      ? null
+      : `Gemini CLI ${version || '(unknown version)'} does not expose stable custom base URL support for proxy mode yet.`,
+  }
+}
+
 function spawnCommand(command, args, env) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
@@ -173,8 +336,10 @@ function writeCrushConfig(model, apiKey, baseUrl, providerId) {
   const filePath = join(homedir(), '.config', 'crush', 'crush.json')
   const backupPath = backupIfExists(filePath)
   const config = readJson(filePath, { $schema: 'https://charm.land/crush.json' })
-  if (!config.options || typeof config.options !== 'object') config.options = {}
-  config.options.disable_default_providers = true
+  // 📖 Remove legacy disable_default_providers — it can prevent Crush from auto-selecting models
+  if (config.options && config.options.disable_default_providers) {
+    delete config.options.disable_default_providers
+  }
   if (!config.providers || typeof config.providers !== 'object') config.providers = {}
   config.providers[providerId] = {
     name: 'Free Coding Models',
@@ -189,10 +354,11 @@ function writeCrushConfig(model, apiKey, baseUrl, providerId) {
     ],
   }
   // 📖 Crush expects structured selected models at config.models.{large,small}.
-  // 📖 Root `crush` reads these defaults in interactive mode, unlike `crush run --model`.
+  // 📖 Setting both large AND small ensures Crush auto-selects the model in interactive mode.
   config.models = {
     ...(config.models && typeof config.models === 'object' ? config.models : {}),
     large: { model: model.modelId, provider: providerId },
+    small: { model: model.modelId, provider: providerId },
   }
   writeJson(filePath, config)
   return { filePath, backupPath }
@@ -252,6 +418,73 @@ function writePiConfig(model, apiKey, baseUrl) {
   return { filePath: modelsFilePath, backupPath: modelsBackupPath, settingsFilePath, settingsBackupPath }
 }
 
+// 📖 writeGooseConfig: Install/update the provider in Goose's custom_providers/, set the
+// 📖 API key in secrets.yaml, and update config.yaml with GOOSE_PROVIDER + GOOSE_MODEL
+// 📖 so Goose auto-selects the model on launch.
+function writeGooseConfig(model, apiKey, baseUrl, providerKey) {
+  const home = homedir()
+  const providerId = `fcm-${providerKey}`
+  const providerLabel = PROVIDER_METADATA[providerKey]?.label || sources[providerKey]?.name || providerKey
+  const secretEnvName = `FCM_${providerKey.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`
+
+  // 📖 Step 1: Write custom provider JSON (same format as endpoint-installer)
+  const providerDir = join(home, '.config', 'goose', 'custom_providers')
+  const providerFilePath = join(providerDir, `${providerId}.json`)
+  ensureDir(providerFilePath)
+  const providerConfig = {
+    name: providerId,
+    engine: 'openai',
+    display_name: `FCM ${providerLabel}`,
+    description: `Managed by free-coding-models for ${providerLabel}`,
+    api_key_env: secretEnvName,
+    base_url: baseUrl?.endsWith('/chat/completions') ? baseUrl : (baseUrl || ''),
+    models: [{ name: model.modelId, context_limit: 128000 }],
+    supports_streaming: true,
+    requires_auth: true,
+  }
+  writeFileSync(providerFilePath, JSON.stringify(providerConfig, null, 2) + '\n')
+
+  // 📖 Step 2: Write API key to secrets.yaml (simple key: value format)
+  const secretsPath = join(home, '.config', 'goose', 'secrets.yaml')
+  let secretsContent = ''
+  if (existsSync(secretsPath)) {
+    secretsContent = readFileSync(secretsPath, 'utf8')
+  }
+  // 📖 Replace existing secret or append new one
+  const secretLine = `${secretEnvName}: ${JSON.stringify(apiKey)}`
+  const secretRegex = new RegExp(`^${secretEnvName}:.*$`, 'm')
+  if (secretRegex.test(secretsContent)) {
+    secretsContent = secretsContent.replace(secretRegex, secretLine)
+  } else {
+    secretsContent = secretsContent.trimEnd() + '\n' + secretLine + '\n'
+  }
+  ensureDir(secretsPath)
+  writeFileSync(secretsPath, secretsContent)
+
+  // 📖 Step 3: Update config.yaml — set GOOSE_PROVIDER and GOOSE_MODEL at top level
+  const configPath = join(home, '.config', 'goose', 'config.yaml')
+  let configContent = ''
+  if (existsSync(configPath)) {
+    configContent = readFileSync(configPath, 'utf8')
+  }
+  // 📖 Replace or add GOOSE_PROVIDER line
+  if (/^GOOSE_PROVIDER:.*/m.test(configContent)) {
+    configContent = configContent.replace(/^GOOSE_PROVIDER:.*/m, `GOOSE_PROVIDER: ${providerId}`)
+  } else {
+    configContent = `GOOSE_PROVIDER: ${providerId}\n` + configContent
+  }
+  // 📖 Replace or add GOOSE_MODEL line
+  if (/^GOOSE_MODEL:.*/m.test(configContent)) {
+    configContent = configContent.replace(/^GOOSE_MODEL:.*/m, `GOOSE_MODEL: ${model.modelId}`)
+  } else {
+    // 📖 Insert after GOOSE_PROVIDER line
+    configContent = configContent.replace(/^(GOOSE_PROVIDER:.*)/m, `$1\nGOOSE_MODEL: ${model.modelId}`)
+  }
+  writeFileSync(configPath, configContent)
+
+  return { providerFilePath, secretsPath, configPath }
+}
+
 function writeAmpConfig(model, baseUrl) {
   const filePath = join(homedir(), '.config', 'amp', 'settings.json')
   const backupPath = backupIfExists(filePath)
@@ -268,6 +501,10 @@ function printConfigResult(toolName, result) {
   if (result.backupPath) console.log(chalk.dim(`  💾 Backup: ${result.backupPath}`))
 }
 
+function printExperimentalProxyNote() {
+  console.log(chalk.dim(`  ${EXPERIMENTAL_PROXY_TOOLS_NOTE}`))
+}
+
 export async function startExternalTool(mode, model, config) {
   const meta = getToolMeta(mode)
   const { env, apiKey, baseUrl } = buildToolEnv(mode, model, config)
@@ -315,40 +552,119 @@ export async function startExternalTool(mode, model, config) {
   }
 
   if (mode === 'goose') {
-    let gooseBaseUrl = baseUrl
+    let gooseBaseUrl = sources[model.providerKey]?.url || baseUrl || ''
     let gooseApiKey = apiKey
     let gooseModelId = resolveLauncherModelId(model, false)
+    let gooseProviderKey = model.providerKey
 
     if (proxySettings.enabled) {
       const started = await ensureProxyRunning(config)
       gooseApiKey = started.proxyToken
-      gooseBaseUrl = `http://127.0.0.1:${started.port}/v1`
+      gooseBaseUrl = `http://127.0.0.1:${started.port}/v1/chat/completions`
       gooseModelId = resolveLauncherModelId(model, true)
-      applyOpenAiCompatEnv(env, gooseApiKey, gooseBaseUrl, gooseModelId)
+      gooseProviderKey = 'proxy'
       console.log(chalk.dim(`  📖 Goose will use the local FCM proxy on :${started.port} for this launch.`))
     }
 
-    env.OPENAI_HOST = gooseBaseUrl
-    env.OPENAI_BASE_PATH = 'v1/chat/completions'
-    env.OPENAI_MODEL = gooseModelId
-    console.log(chalk.dim(`  📖 Goose uses env-based OpenAI-compatible configuration for ${proxySettings.enabled ? 'the proxy' : 'this provider'} launch.`))
+    // 📖 Write Goose config: custom provider JSON + secrets.yaml + config.yaml (GOOSE_PROVIDER/GOOSE_MODEL)
+    const gooseResult = writeGooseConfig({ ...model, modelId: gooseModelId }, gooseApiKey, gooseBaseUrl, gooseProviderKey)
+    console.log(chalk.dim(`  📄 Goose config updated: ${gooseResult.configPath}`))
+    console.log(chalk.dim(`  📄 Provider installed: ${gooseResult.providerFilePath}`))
+
+    // 📖 Also set env vars as belt-and-suspenders
+    env.GOOSE_PROVIDER = `fcm-${gooseProviderKey}`
+    env.GOOSE_MODEL = gooseModelId
+    applyOpenAiCompatEnv(env, gooseApiKey, gooseBaseUrl.replace(/\/chat\/completions$/, ''), gooseModelId)
     return spawnCommand('goose', [], env)
   }
 
+  // 📖 Claude Code, Codex, and Gemini require the FCM Proxy V2 background service.
+  // 📖 Without it, these tools cannot connect to the free providers (protocol mismatch / no direct support).
+  if (mode === 'claude-code' || mode === 'codex' || mode === 'gemini') {
+    if (!proxySettings.enabled) {
+      console.log()
+      console.log(chalk.red(`  ✖ ${meta.label} requires FCM Proxy V2 to work with free providers.`))
+      console.log()
+      console.log(chalk.yellow('  The proxy translates between provider protocols and handles key rotation,'))
+      console.log(chalk.yellow('  which is required for this tool to connect.'))
+      console.log(chalk.dim(`  ${EXPERIMENTAL_PROXY_TOOLS_NOTE}`))
+      console.log()
+      console.log(chalk.white('  To enable it:'))
+      console.log(chalk.dim('    1. Press ') + chalk.bold.white('J') + chalk.dim(' to open FCM Proxy V2 settings'))
+      console.log(chalk.dim('    2. Enable ') + chalk.bold.white('Proxy mode') + chalk.dim(' and install the ') + chalk.bold.white('background service'))
+      console.log(chalk.dim('    3. Come back and select your model again'))
+      console.log()
+      return 1
+    }
+  }
+
   if (mode === 'claude-code') {
-    console.log(chalk.yellow('  ⚠ Claude Code expects an Anthropic/Bedrock/Vertex-compatible gateway.'))
-    console.log(chalk.dim('  This launch passes proxy env vars, but your endpoint must support Claude Code wire semantics.'))
-    return spawnCommand('claude', ['--model', model.modelId], env)
+    // 📖 Claude Code needs Anthropic-compatible wire format (POST /v1/messages).
+    // 📖 Mirror free-claude-code: one auth env only (`ANTHROPIC_AUTH_TOKEN`) plus base URL.
+    const started = await ensureProxyRunning(config)
+    const { env: proxyEnv } = buildToolEnv(mode, model, config, {
+      sanitize: true,
+      includeCompatDefaults: false,
+      includeProviderEnv: false,
+    })
+    const proxyBase = `http://127.0.0.1:${started.port}`
+    const launchModelId = resolveLauncherModelId(model, true)
+    proxyEnv.ANTHROPIC_BASE_URL = proxyBase
+    proxyEnv.ANTHROPIC_AUTH_TOKEN = started.proxyToken
+    proxyEnv.ANTHROPIC_MODEL = launchModelId
+    console.log(chalk.dim(`  📖 Claude Code routed through FCM proxy on :${started.port} (Anthropic translation enabled)`))
+    return spawnCommand('claude', ['--model', launchModelId], proxyEnv)
   }
 
   if (mode === 'codex') {
-    console.log(chalk.dim('  📖 Codex CLI is launched with proxy env vars for this session.'))
-    return spawnCommand('codex', ['--model', model.modelId], env)
+    const started = await ensureProxyRunning(config)
+    const { env: proxyEnv } = buildToolEnv(mode, model, config, {
+      sanitize: true,
+      includeCompatDefaults: false,
+      includeProviderEnv: false,
+    })
+    const launchModelId = resolveLauncherModelId(model, true)
+    const proxyBaseUrl = `http://127.0.0.1:${started.port}/v1`
+    proxyEnv.FCM_PROXY_API_KEY = started.proxyToken
+    console.log(chalk.dim(`  📖 Codex routed through FCM proxy on :${started.port}`))
+    return spawnCommand('codex', [...buildCodexProxyArgs(proxyBaseUrl), '--model', launchModelId], proxyEnv)
   }
 
   if (mode === 'gemini') {
-    printConfigResult(meta.label, writeGeminiConfig(model))
-    return spawnCommand('gemini', ['--model', model.modelId], env)
+    const geminiSupport = inspectGeminiCliSupport()
+    if (geminiSupport.configError) {
+      console.log()
+      console.log(chalk.red('  ✖ Gemini CLI configuration is invalid, so the proxy launch is blocked before auth.'))
+      console.log(chalk.dim(`  ${geminiSupport.configError.split('\n').join('\n  ')}`))
+      printExperimentalProxyNote()
+      console.log(chalk.dim('  Fix ~/.gemini/settings.json, then try again.'))
+      console.log()
+      return 1
+    }
+    if (!geminiSupport.supportsProxyBaseUrl) {
+      console.log()
+      const versionLabel = geminiSupport.version ? `v${geminiSupport.version}` : 'this installed version'
+      console.log(chalk.red(`  ✖ Gemini CLI ${versionLabel} is not proxy-compatible in FCM yet.`))
+      console.log(chalk.yellow('  This build does not expose the custom base-URL contract we need, so launching it through the proxy would be misleading.'))
+      printExperimentalProxyNote()
+      console.log(chalk.dim(`  Expected: Gemini CLI ${GEMINI_PROXY_MIN_VERSION}+ with stable proxy base URL support.`))
+      console.log()
+      return 1
+    }
+
+    const started = await ensureProxyRunning(config)
+    const launchModelId = resolveLauncherModelId(model, true)
+    const { env: proxyEnv } = buildToolEnv(mode, model, config, {
+      sanitize: true,
+      includeCompatDefaults: false,
+      includeProviderEnv: false,
+    })
+    proxyEnv.GEMINI_API_KEY = started.proxyToken
+    proxyEnv.GOOGLE_API_KEY = started.proxyToken
+    proxyEnv.GOOGLE_GEMINI_BASE_URL = `http://127.0.0.1:${started.port}/v1`
+    printConfigResult(meta.label, writeGeminiConfig({ ...model, modelId: launchModelId }))
+    console.log(chalk.dim(`  📖 Gemini routed through FCM proxy on :${started.port}`))
+    return spawnCommand('gemini', ['--model', launchModelId], proxyEnv)
   }
 
   if (mode === 'qwen') {
@@ -375,7 +691,8 @@ export async function startExternalTool(mode, model, config) {
     const piResult = writePiConfig(model, apiKey, baseUrl)
     printConfigResult(meta.label, { filePath: piResult.filePath, backupPath: piResult.backupPath })
     printConfigResult(meta.label, { filePath: piResult.settingsFilePath, backupPath: piResult.settingsBackupPath })
-    return spawnCommand('pi', [], env)
+    // 📖 Pi supports --provider and --model flags for guaranteed auto-selection
+    return spawnCommand('pi', ['--provider', 'freeCodingModels', '--model', model.modelId, '--api-key', apiKey], env)
   }
 
   console.log(chalk.red(`  X Unsupported external tool mode: ${mode}`))

package/src/utils.js

@@ -386,16 +386,16 @@ export function findBestModel(results) {
 // 📖 Slices from index 2 to get user-provided arguments only.
 //
 // 📖 Argument types:
-//   - API key: first positional arg that doesn't start with "--" (e.g., "nvapi-xxx")
+//   - API key: first positional arg that does not look like a CLI flag (e.g., "nvapi-xxx")
 //   - Boolean flags: --best, --fiable, --opencode, --opencode-desktop, --openclaw,
 //     --aider, --crush, --goose, --claude-code, --codex, --gemini, --qwen,
-//     --openhands, --amp, --pi, --no-telemetry, --json (case-insensitive)
+//     --openhands, --amp, --pi, --no-telemetry, --json, --help/-h (case-insensitive)
 //   - Value flag: --tier <letter> (the next non-flag arg is the tier value)
 //
 // 📖 Returns:
 //   { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openClawMode,
 //     aiderMode, crushMode, gooseMode, claudeCodeMode, codexMode, geminiMode,
-//     qwenMode, openHandsMode, ampMode, piMode, noTelemetry, jsonMode, tierFilter }
+//     qwenMode, openHandsMode, ampMode, piMode, noTelemetry, jsonMode, helpMode, tierFilter }
 //
 // 📖 Note: apiKey may be null here — the main CLI falls back to env vars and saved config.
 export function parseArgs(argv) {
@@ -420,7 +420,7 @@ export function parseArgs(argv) {
   if (profileValueIdx !== -1) skipIndices.add(profileValueIdx)
 
   for (const [i, arg] of args.entries()) {
-    if (arg.startsWith('--')) {
+    if (arg.startsWith('--') || arg === '-h') {
       flags.push(arg.toLowerCase())
     } else if (skipIndices.has(i)) {
       // 📖 Skip — this is a value for --tier or --profile, not an API key
@@ -447,6 +447,7 @@ export function parseArgs(argv) {
   const noTelemetry = flags.includes('--no-telemetry')
   const cleanProxyMode = flags.includes('--clean-proxy') || flags.includes('--proxy-clean')
   const jsonMode = flags.includes('--json')
+  const helpMode = flags.includes('--help') || flags.includes('-h')
 
   let tierFilter = tierValueIdx !== -1 ? args[tierValueIdx].toUpperCase() : null
 
@@ -475,6 +476,7 @@ export function parseArgs(argv) {
     noTelemetry,
     cleanProxyMode,
     jsonMode,
+    helpMode,
     tierFilter,
     profileName,
     recommendMode
@@ -707,17 +709,31 @@ export function getProxyStatusInfo(proxyStartupStatus, isProxyActive, isProxyEna
 }
 
 /**
- * 📖 getVersionStatusInfo turns the settings update-check state into a compact,
+ * 📖 getVersionStatusInfo turns startup + manual update-check state into a compact,
  * 📖 render-friendly footer descriptor for the main table.
  *
- * 📖 Only an explicit `available` state should mark the local install as outdated.
- * 📖 This avoids showing a scary warning before the user has actually checked npm.
+ * 📖 Priority:
+ * 📖   1. Manual Settings check found an update (`available`)
+ * 📖   2. Startup auto-check already found a newer npm version
+ * 📖   3. Otherwise stay quiet
+ * 📖
+ * 📖 `versionAlertsEnabled` lets the CLI suppress npm-specific warnings in dev checkouts,
+ * 📖 where telling contributors to run a global npm update would be bogus.
  *
  * @param {'idle'|'checking'|'available'|'up-to-date'|'error'|'installing'} updateState
  * @param {string|null} latestVersion
+ * @param {string|null} [startupLatestVersion=null]
+ * @param {boolean} [versionAlertsEnabled=true]
  * @returns {{ isOutdated: boolean, latestVersion: string|null }}
  */
-export function getVersionStatusInfo(updateState, latestVersion) {
+export function getVersionStatusInfo(updateState, latestVersion, startupLatestVersion = null, versionAlertsEnabled = true) {
+  if (!versionAlertsEnabled) {
+    return {
+      isOutdated: false,
+      latestVersion: null,
+    }
+  }
+
   if (updateState === 'available' && typeof latestVersion === 'string' && latestVersion.trim()) {
     return {
       isOutdated: true,
@@ -725,6 +741,13 @@ export function getVersionStatusInfo(updateState, latestVersion) {
     }
   }
 
+  if (typeof startupLatestVersion === 'string' && startupLatestVersion.trim()) {
+    return {
+      isOutdated: true,
+      latestVersion: startupLatestVersion.trim(),
+    }
+  }
+
   return {
     isOutdated: false,
     latestVersion: null,