free-coding-models 0.3.6 → 0.3.11

package/src/proxy-foreground.js

@@ -0,0 +1,234 @@
+/**
+ * @file src/proxy-foreground.js
+ * @description Foreground proxy mode — starts the FCM Proxy V2 in the current terminal
+ * with a live dashboard showing status, accounts, and incoming requests.
+ *
+ * 📖 This is the `--proxy` flag handler. Unlike the daemon, it runs in the foreground
+ *    with a live-updating terminal UI that shows proxy health and request activity.
+ *    Perfect for debugging, dev testing (no .git check), and monitoring.
+ *
+ * @functions
+ *   → startForegroundProxy(config, chalk) — main entry point, starts proxy + dashboard
+ *
+ * @exports startForegroundProxy
+ *
+ * @see src/proxy-server.js — ProxyServer implementation
+ * @see src/proxy-topology.js — topology builder
+ * @see bin/fcm-proxy-daemon.js — headless daemon equivalent
+ */
+
+import { loadConfig, getProxySettings } from './config.js'
+import { ProxyServer } from './proxy-server.js'
+import { buildProxyTopologyFromConfig, buildMergedModelsForDaemon } from './proxy-topology.js'
+import { sources } from '../sources.js'
+import { syncProxyToTool, resolveProxySyncToolMode } from './proxy-sync.js'
+import { buildMergedModels } from './model-merger.js'
+import { createHash, randomBytes } from 'node:crypto'
+
+// 📖 Default foreground proxy port — same as daemon
+const DEFAULT_PORT = 18045
+
+/**
+ * 📖 Start the proxy in foreground mode with a live terminal dashboard.
+ * 📖 No .git check, no daemon install — just starts the proxy and shows activity.
+ *
+ * @param {object} config — loaded FCM config
+ * @param {object} chalk — chalk instance for terminal colors
+ */
+export async function startForegroundProxy(config, chalk) {
+  const proxySettings = getProxySettings(config)
+  const port = proxySettings.preferredPort || DEFAULT_PORT
+
+  // 📖 Ensure a stable token exists — generate one if missing (dev-friendly)
+  let token = proxySettings.stableToken
+  if (!token) {
+    token = 'fcm_' + randomBytes(16).toString('hex')
+    console.log(chalk.yellow('  ⚠ No stableToken in config — generated a temporary one for this session'))
+  }
+
+  console.log()
+  console.log(chalk.bold('  📡 FCM Proxy V2 — Foreground Mode'))
+  console.log(chalk.dim('  ─────────────────────────────────────────────'))
+  console.log()
+
+  // 📖 Build topology
+  console.log(chalk.dim('  Building merged model catalog...'))
+  let mergedModels
+  try {
+    mergedModels = await buildMergedModelsForDaemon()
+  } catch (err) {
+    console.error(chalk.red(`  ✗ Failed to build model catalog: ${err.message}`))
+    process.exit(1)
+  }
+
+  const topology = buildProxyTopologyFromConfig(config, mergedModels, sources)
+  const { accounts, proxyModels, anthropicRouting } = topology
+
+  if (accounts.length === 0) {
+    console.error(chalk.red('  ✗ No API keys configured — no accounts to serve.'))
+    console.error(chalk.dim('  Add keys via the TUI first (run free-coding-models without --proxy)'))
+    process.exit(1)
+  }
+
+  // 📖 Start proxy server
+  const proxy = new ProxyServer({
+    port,
+    accounts,
+    proxyApiKey: token,
+    anthropicRouting,
+  })
+
+  let listeningPort
+  try {
+    const result = await proxy.start()
+    listeningPort = result.port
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      console.error(chalk.red(`  ✗ Port ${port} already in use.`))
+      console.error(chalk.dim('  Another FCM proxy or process may be running on that port.'))
+      process.exit(2)
+    }
+    console.error(chalk.red(`  ✗ Failed to start proxy: ${err.message}`))
+    process.exit(1)
+  }
+
+  const modelCount = Object.keys(proxyModels).length
+
+  // 📖 Sync env file for claude-code if it's a syncable tool
+  try {
+    const baseUrl = `http://127.0.0.1:${listeningPort}/v1`
+    const proxyInfo = { baseUrl, token }
+    syncProxyToTool('claude-code', proxyInfo, mergedModels)
+  } catch { /* best effort */ }
+
+  // 📖 Dashboard header
+  console.log(chalk.green('  ✓ Proxy running'))
+  console.log()
+  console.log(chalk.bold('  Status'))
+  console.log(chalk.dim('  ─────────────────────────────────────────────'))
+  console.log(`  ${chalk.cyan('Endpoint')}     http://127.0.0.1:${listeningPort}`)
+  console.log(`  ${chalk.cyan('Token')}        ${token.slice(0, 12)}...${token.slice(-4)}`)
+  console.log(`  ${chalk.cyan('Accounts')}     ${accounts.length}`)
+  console.log(`  ${chalk.cyan('Models')}       ${modelCount}`)
+  console.log()
+
+  // 📖 Show provider breakdown
+  const byProvider = {}
+  for (const acct of accounts) {
+    byProvider[acct.providerKey] = (byProvider[acct.providerKey] || 0) + 1
+  }
+  console.log(chalk.bold('  Providers'))
+  console.log(chalk.dim('  ─────────────────────────────────────────────'))
+  for (const [provider, count] of Object.entries(byProvider).sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${chalk.cyan(provider.padEnd(20))} ${count} account${count > 1 ? 's' : ''}`)
+  }
+  console.log()
+
+  // 📖 Claude Code quick-start hint
+  console.log(chalk.bold('  Quick Start'))
+  console.log(chalk.dim('  ─────────────────────────────────────────────'))
+  console.log(chalk.dim('  Claude Code:'))
+  console.log(`    ${chalk.cyan(`ANTHROPIC_BASE_URL=http://127.0.0.1:${listeningPort} ANTHROPIC_API_KEY=${token} claude`)}`)
+  console.log()
+  console.log(chalk.dim('  curl test:'))
+  console.log(`    ${chalk.cyan(`curl -s -H "x-api-key: ${token}" http://127.0.0.1:${listeningPort}/v1/models | head`)}`)
+  console.log()
+
+  console.log(chalk.bold('  Live Requests'))
+  console.log(chalk.dim('  ─────────────────────────────────────────────'))
+  console.log(chalk.dim('  Waiting for incoming requests... (Ctrl+C to stop)'))
+  console.log()
+
+  // 📖 Monkey-patch tokenStats.record to intercept and display live requests
+  const originalRecord = proxy._tokenStats.record.bind(proxy._tokenStats)
+  let requestCount = 0
+  proxy._tokenStats.record = (entry) => {
+    originalRecord(entry)
+    requestCount++
+
+    const now = new Date().toLocaleTimeString()
+    const status = entry.success ? chalk.green(`${entry.statusCode}`) : chalk.red(`${entry.statusCode}`)
+    const latency = entry.latencyMs ? chalk.dim(`${entry.latencyMs}ms`) : ''
+    const tokens = (entry.promptTokens + entry.completionTokens) > 0
+      ? chalk.dim(`${entry.promptTokens}+${entry.completionTokens}tok`)
+      : ''
+    const reqType = entry.requestType || 'unknown'
+    const model = entry.requestedModelId || entry.modelId || '?'
+    const provider = entry.providerKey || '?'
+    const switched = entry.switched ? chalk.yellow(' ↻') : ''
+
+    console.log(
+      `  ${chalk.dim(now)}  ${status}  ${chalk.cyan(reqType.padEnd(20))}  ` +
+      `${chalk.white(model)}  →  ${chalk.dim(provider)}${switched}  ${latency}  ${tokens}`
+    )
+  }
+
+  // 📖 Also intercept errors on the _handleRequest level to show auth failures etc.
+  const originalHandleRequest = proxy._handleRequest.bind(proxy)
+  proxy._handleRequest = (req, res) => {
+    const origEnd = res.end.bind(res)
+    const method = req.method
+    const url = req.url
+    let logged = false
+
+    res.end = function (...args) {
+      if (!logged && res.statusCode >= 400) {
+        logged = true
+        const now = new Date().toLocaleTimeString()
+        const status = chalk.red(`${res.statusCode}`)
+        const ua = req.headers['user-agent'] || ''
+        // 📖 Try to detect the client tool from user-agent
+        const tool = detectClientTool(ua, req.headers)
+        const toolLabel = tool ? chalk.magenta(` [${tool}]`) : ''
+        console.log(
+          `  ${chalk.dim(now)}  ${status}  ${chalk.cyan(`${method} ${url}`.padEnd(20))}  ` +
+          `${chalk.dim('rejected')}${toolLabel}`
+        )
+        // 📖 Debug: show auth headers on 401 to help diagnose auth issues
+        if (res.statusCode === 401) {
+          const authHeader = req.headers.authorization ? `Bearer ${req.headers.authorization.slice(0, 20)}...` : 'none'
+          const xApiKeyHeader = req.headers['x-api-key'] ? `${req.headers['x-api-key'].slice(0, 20)}...` : 'none'
+          console.log(chalk.dim(`         auth: ${authHeader}  |  x-api-key: ${xApiKeyHeader}`))
+        }
+      }
+      return origEnd(...args)
+    }
+
+    return originalHandleRequest(req, res)
+  }
+
+  // 📖 Graceful shutdown
+  const shutdown = async (signal) => {
+    console.log()
+    console.log(chalk.dim(`  Received ${signal} — shutting down...`))
+    try { await proxy.stop() } catch { /* best effort */ }
+    console.log(chalk.green(`  ✓ Proxy stopped. ${requestCount} request${requestCount !== 1 ? 's' : ''} served this session.`))
+    console.log()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', () => shutdown('SIGINT'))
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+}
+
+/**
+ * 📖 Detect which client tool sent the request based on User-Agent or custom headers.
+ * 📖 Claude Code, Codex, OpenCode etc. each have distinctive UA patterns.
+ */
+function detectClientTool(ua, headers) {
+  if (!ua && !headers) return null
+  const uaLower = (ua || '').toLowerCase()
+
+  if (uaLower.includes('claude') || uaLower.includes('anthropic')) return 'Claude Code'
+  if (headers?.['anthropic-version'] || headers?.['x-api-key']) return 'Anthropic SDK'
+  if (uaLower.includes('codex')) return 'Codex'
+  if (uaLower.includes('opencode')) return 'OpenCode'
+  if (uaLower.includes('cursor')) return 'Cursor'
+  if (uaLower.includes('aider')) return 'Aider'
+  if (uaLower.includes('goose')) return 'Goose'
+  if (uaLower.includes('openclaw')) return 'OpenClaw'
+  if (uaLower.includes('node-fetch') || uaLower.includes('undici')) return 'Node.js'
+  if (uaLower.includes('python')) return 'Python'
+  if (uaLower.includes('curl')) return 'curl'
+  return null
+}

package/src/proxy-server.js

@@ -175,20 +175,42 @@ function resolveAnthropicMappedModel(modelId, anthropicRouting) {
   return fallbackModel
 }
 
-function parseProxyAuthorizationHeader(authorization, expectedToken) {
+// 📖 Accepts both standard Bearer auth and Anthropic SDK x-api-key header
+// 📖 Claude Code sends credentials via x-api-key, not Authorization: Bearer
+function parseProxyAuthorizationHeader(authorization, expectedToken, xApiKey = null) {
   if (!expectedToken) return { authorized: true, modelHint: null }
-  if (typeof authorization !== 'string' || !authorization.startsWith('Bearer ')) {
-    return { authorized: false, modelHint: null }
+
+  // 📖 Check standard Bearer auth first
+  if (typeof authorization === 'string' && authorization.startsWith('Bearer ')) {
+    const rawToken = authorization.slice('Bearer '.length).trim()
+    if (rawToken === expectedToken) return { authorized: true, modelHint: null }
+    if (rawToken.startsWith(`${expectedToken}:`)) {
+      const modelHint = normalizeRequestedModel(rawToken.slice(expectedToken.length + 1))
+      return modelHint ? { authorized: true, modelHint } : { authorized: false, modelHint: null }
+    }
+  }
+
+  // 📖 Fallback: Anthropic SDK x-api-key header
+  if (typeof xApiKey === 'string' && xApiKey.trim()) {
+    const trimmed = xApiKey.trim()
+    if (trimmed === expectedToken) return { authorized: true, modelHint: null }
+    if (trimmed.startsWith(`${expectedToken}:`)) {
+      const modelHint = normalizeRequestedModel(trimmed.slice(expectedToken.length + 1))
+      return modelHint ? { authorized: true, modelHint } : { authorized: false, modelHint: null }
+    }
   }
 
-  const rawToken = authorization.slice('Bearer '.length).trim()
-  if (rawToken === expectedToken) return { authorized: true, modelHint: null }
-  if (!rawToken.startsWith(`${expectedToken}:`)) return { authorized: false, modelHint: null }
+  // 📖 Accept real Anthropic API keys (sk-ant-*) — Claude Code uses its own stored key
+  // 📖 even when ANTHROPIC_BASE_URL is overridden to point at the proxy.
+  // 📖 The proxy is bound to 127.0.0.1 only, so accepting these keys is safe.
+  const candidateToken = (typeof authorization === 'string' && authorization.startsWith('Bearer '))
+    ? authorization.slice('Bearer '.length).trim()
+    : (typeof xApiKey === 'string' ? xApiKey.trim() : '')
+  if (candidateToken.startsWith('sk-ant-')) {
+    return { authorized: true, modelHint: null }
+  }
 
-  const modelHint = normalizeRequestedModel(rawToken.slice(expectedToken.length + 1))
-  return modelHint
-    ? { authorized: true, modelHint }
-    : { authorized: false, modelHint: null }
+  return { authorized: false, modelHint: null }
 }
 
 // ─── ProxyServer ─────────────────────────────────────────────────────────────
@@ -211,7 +233,7 @@ export class ProxyServer {
   constructor({
     port = 0,
     accounts = [],
-    retries = 3,
+    retries = 8,
     proxyApiKey = null,
     anthropicRouting = null,
     accountManagerOpts = {},
@@ -284,7 +306,7 @@ export class ProxyServer {
   }
 
   _getAuthContext(req) {
-    return parseProxyAuthorizationHeader(req.headers.authorization, this._proxyApiKey)
+    return parseProxyAuthorizationHeader(req.headers.authorization, this._proxyApiKey, req.headers['x-api-key'])
   }
 
   _isAuthorized(req) {
@@ -312,6 +334,13 @@ export class ProxyServer {
       }
     }
 
+    // 📖 Last resort: when the requested model is a Claude virtual model and no routing resolved,
+    // 📖 fall back to the first available account's model (free-claude-code behavior)
+    if (!requestedModel || classifyClaudeVirtualModel(requestedModel) || requestedModel.toLowerCase().startsWith('claude-')) {
+      const firstModel = this._accounts[0]?.modelId
+      if (firstModel) return firstModel
+    }
+
     return requestedModel
   }
 

package/src/proxy-sync.js

@@ -32,13 +32,33 @@ import { getToolMeta } from './tool-metadata.js'
 // 📖 Provider ID used for all proxy entries — replaces per-provider fcm-{providerKey} IDs
 const PROXY_PROVIDER_ID = 'fcm-proxy'
 
+// 📖 Ensures the env file is sourced in the user's shell profile (.zshrc, .bashrc, .bash_profile)
+// 📖 Only adds the source line if not already present — idempotent
+function ensureShellSourceLine(envFilePath) {
+  const home = homedir()
+  const candidates = ['.zshrc', '.bashrc', '.bash_profile']
+  let profilePath = null
+  for (const c of candidates) {
+    const p = join(home, c)
+    if (existsSync(p)) { profilePath = p; break }
+  }
+  if (!profilePath) return // 📖 No shell profile found — skip silently
+
+  try {
+    const content = readFileSync(profilePath, 'utf8')
+    if (content.includes(envFilePath)) return // 📖 Already sourced
+    const sourceLine = `\n# 📖 FCM Proxy — Claude Code env vars\n[ -f "${envFilePath}" ] && source "${envFilePath}"\n`
+    writeFileSync(profilePath, content + sourceLine)
+  } catch { /* best effort */ }
+}
+
 // 📖 Tools that support proxy sync (have base URL + API key config)
 // 📖 Gemini is excluded — it only stores a model name, no URL/key fields.
 // 📖 Claude proxy integration is
 // 📖 runtime-only now, with fake Claude ids handled by the proxy itself.
 export const PROXY_SYNCABLE_TOOLS = [
   'opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose', 'pi',
-  'aider', 'amp', 'qwen', 'codex', 'openhands',
+  'aider', 'amp', 'qwen', 'codex', 'openhands', 'claude-code',
 ]
 
 const PROXY_SYNCABLE_CANONICAL = new Set(PROXY_SYNCABLE_TOOLS.map(tool => tool === 'opencode-desktop' ? 'opencode' : tool))
@@ -343,7 +363,7 @@ function syncEnvTool(proxyInfo, mergedModels, toolMode) {
   // 📖 Claude Code: Anthropic-specific env vars
   if (toolMode === 'claude-code') {
     const proxyBase = proxyInfo.baseUrl.replace(/\/v1$/, '')
-    envLines.push(`export ANTHROPIC_AUTH_TOKEN="${proxyInfo.token}"`)
+    envLines.push(`export ANTHROPIC_API_KEY="${proxyInfo.token}"`)
     envLines.push(`export ANTHROPIC_BASE_URL="${proxyBase}"`)
   }
 
@@ -352,6 +372,12 @@ function syncEnvTool(proxyInfo, mergedModels, toolMode) {
     try { copyFileSync(envFilePath, envFilePath + '.bak') } catch { /* best effort */ }
   }
   writeFileSync(envFilePath, envLines.join('\n') + '\n')
+
+  // 📖 Auto-source the env file in the shell profile so Claude Code picks it up
+  if (toolMode === 'claude-code') {
+    ensureShellSourceLine(envFilePath)
+  }
+
   return { path: envFilePath, modelCount: models.length }
 }
 

package/src/render-table.js

@@ -12,7 +12,7 @@
  *   - Hotkey-aware header lettering so highlighted letters always match live sort/filter keys
  *   - Emoji-aware padding via padEndDisplay for aligned verdict/status cells
  *   - Viewport clipping with above/below indicators
- *   - Smart badges (mode, tier filter, origin filter, profile)
+ *   - Smart badges (mode, tier filter, origin filter)
  *   - Footer J badge: green "Proxy On" / red "Proxy Off" indicator with direct overlay access
  *   - Install-endpoints shortcut surfaced directly in the footer hints
  *   - Full-width red outdated-version banner when a newer npm release is known
@@ -93,7 +93,7 @@ export function setActiveProxy(proxyInstance) {
 }
 
 // ─── renderTable: mode param controls footer hint text (opencode vs openclaw) ─────────
-export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '', proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, startupLatestVersion = null, versionAlertsEnabled = true, disableWidthsWarning = false) {
+export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, startupLatestVersion = null, versionAlertsEnabled = true, disableWidthsWarning = false) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -172,11 +172,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     }
   }
 
-  // 📖 Profile badge — shown when a named profile is active (Shift+P to cycle, Shift+S to save)
-  let profileBadge = ''
-  if (activeProfile) {
-    profileBadge = chalk.bold.rgb(200, 150, 255)(` [📋 ${activeProfile}]`)
-  }
+
 
   // 📖 Column widths (generous spacing with margins)
   const W_RANK = 6
@@ -230,7 +226,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   const sorted = sortResultsWithPinnedFavorites(visibleResults, sortColumn, sortDirection)
 
   const lines = [
-    `  ${chalk.cyanBright.bold(`🚀 free-coding-models v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${profileBadge}${chalk.reset('')}   ` +
+    `  ${chalk.cyanBright.bold(`🚀 free-coding-models v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${chalk.reset('')}   ` +
       chalk.dim('📦 ') + chalk.cyanBright.bold(`${completedPings}/${totalVisible}`) + chalk.dim('  ') +
       chalk.greenBright(`✅ ${up}`) + chalk.dim(' up  ') +
       chalk.yellow(`⏳ ${timeout}`) + chalk.dim(' timeout  ') +
@@ -590,12 +586,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     lines.push(chalk.dim(`  ... ${sorted.length - vp.endIdx} more below ...`))
   }
 
-   // 📖 Profile save inline prompt — shown when Shift+S is pressed, replaces spacer line
-   if (profileSaveMode) {
-     lines.push(chalk.bgRgb(40, 20, 60)(`  📋 Save profile as: ${chalk.cyanBright(profileSaveBuffer + '▏')}  ${chalk.dim('Enter save  •  Esc cancel')}`))
-   } else {
-     lines.push('')
-   }
+   lines.push('')
   // 📖 Footer hints keep only navigation and secondary actions now that the
   // 📖 active tool target is already visible in the header badge.
   const hotkey = (keyLabel, text) => chalk.yellow(keyLabel) + chalk.dim(text)
@@ -624,11 +615,9 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     chalk.dim(`  •  `) +
     hotkey('K', ' Help')
   )
-  // 📖 Line 2: profiles, install flow, recommend, proxy shortcut, feedback, and extended hints.
+  // 📖 Line 2: install flow, recommend, proxy shortcut, feedback, and extended hints.
   lines.push(
     chalk.dim(`  `) +
-    hotkey('⇧P', ' Cycle profile') + chalk.dim(`  •  `) +
-    hotkey('⇧S', ' Save profile') + chalk.dim(`  •  `) +
     hotkey('Y', ' Install endpoints') + chalk.dim(`  •  `) +
     hotkey('Q', ' Smart Recommend') + chalk.dim(`  •  `) +
     hotkey('I', ' Feedback, bugs & requests')

package/src/token-usage-reader.js

@@ -26,28 +26,70 @@
  * @see src/render-table.js
  */
 
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { loadRecentLogs } from './log-reader.js'
 
+const DEFAULT_DATA_DIR = join(homedir(), '.free-coding-models')
+const STATS_FILE = join(DEFAULT_DATA_DIR, 'token-stats.json')
+
 // 📖 buildProviderModelTokenKey keeps provider-scoped totals isolated even when
 // 📖 multiple Origins expose the same model ID.
 export function buildProviderModelTokenKey(providerKey, modelId) {
   return `${providerKey}::${modelId}`
 }
 
-// 📖 loadTokenUsageByProviderModel reads the full bounded log history available
-// 📖 through log-reader and sums tokens per exact provider+model pair.
-export function loadTokenUsageByProviderModel({ logFile, limit = 50_000 } = {}) {
-  const rows = loadRecentLogs({ logFile, limit })
+// 📖 loadTokenUsageByProviderModel prioritizes token-stats.json for accurate
+// 📖 historical totals. If missing, it falls back to parsing the bounded log history.
+export function loadTokenUsageByProviderModel({ logFile, statsFile = STATS_FILE, limit = 50_000 } = {}) {
+  // 📖 If a custom logFile is provided (Test Mode), ONLY use that file.
+  if (logFile) {
+    const testTotals = {}
+    const rows = loadRecentLogs({ logFile, limit })
+    for (const row of rows) {
+      const key = buildProviderModelTokenKey(row.provider, row.model)
+      testTotals[key] = (testTotals[key] || 0) + (Number(row.tokens) || 0)
+    }
+    return testTotals
+  }
+
   const totals = {}
 
-  for (const row of rows) {
-    const providerKey = typeof row.provider === 'string' ? row.provider : 'unknown'
-    const modelId = typeof row.model === 'string' ? row.model : 'unknown'
-    const tokens = Number(row.tokens) || 0
-    if (tokens <= 0) continue
+  // 📖 Phase 1: Try to load from the aggregated stats file (canonical source for totals)
+  try {
+    if (existsSync(statsFile)) {
+      const stats = JSON.parse(readFileSync(statsFile, 'utf8'))
+      // 📖 Aggregate byAccount entries (which use providerKey/slug/keyIdx as ID)
+      // 📖 into providerKey::modelId buckets.
+      if (stats.byAccount && typeof stats.byAccount === 'object') {
+        for (const [accountId, acct] of Object.entries(stats.byAccount)) {
+          const tokens = Number(acct.tokens) || 0
+          if (tokens <= 0) continue
+
+          // 📖 Extract providerKey and modelId from accountId (provider/model/index)
+          const parts = accountId.split('/')
+          if (parts.length >= 2) {
+            const providerKey = parts[0]
+            const modelId = parts[1]
+            const key = buildProviderModelTokenKey(providerKey, modelId)
+            totals[key] = (totals[key] || 0) + tokens
+          }
+        }
+      }
+    }
+  } catch (err) {
+    // 📖 Silently fall back to log parsing if stats file is corrupt or unreadable
+  }
 
-    const key = buildProviderModelTokenKey(providerKey, modelId)
-    totals[key] = (totals[key] || 0) + tokens
+  // 📖 Phase 2: Supplement with recent log entries if totals are still empty
+  // 📖 (e.g. fresh install or token-stats.json deleted)
+  if (Object.keys(totals).length === 0) {
+    const rows = loadRecentLogs({ limit })
+    for (const row of rows) {
+      const key = buildProviderModelTokenKey(row.provider, row.model)
+      totals[key] = (totals[key] || 0) + (Number(row.tokens) || 0)
+    }
   }
 
   return totals

package/src/utils.js

@@ -403,27 +403,40 @@ export function parseArgs(argv) {
   let apiKey = null
   const flags = []
 
-  // 📖 Determine which arg indices are consumed by --tier and --profile so we skip them
+  // 📖 Determine which arg indices are consumed by --tier so we skip them
   const tierIdx = args.findIndex(a => a.toLowerCase() === '--tier')
   const tierValueIdx = (tierIdx !== -1 && args[tierIdx + 1] && !args[tierIdx + 1].startsWith('--'))
     ? tierIdx + 1
     : -1
 
-  const profileIdx = args.findIndex(a => a.toLowerCase() === '--profile')
-  const profileValueIdx = (profileIdx !== -1 && args[profileIdx + 1] && !args[profileIdx + 1].startsWith('--'))
-    ? profileIdx + 1
+  // New value flags
+  const sortIdx = args.findIndex(a => a.toLowerCase() === '--sort')
+  const sortValueIdx = (sortIdx !== -1 && args[sortIdx + 1] && !args[sortIdx + 1].startsWith('--'))
+    ? sortIdx + 1
+    : -1
+
+  const originIdx = args.findIndex(a => a.toLowerCase() === '--origin')
+  const originValueIdx = (originIdx !== -1 && args[originIdx + 1] && !args[originIdx + 1].startsWith('--'))
+    ? originIdx + 1
+    : -1
+
+  const pingIntervalIdx = args.findIndex(a => a.toLowerCase() === '--ping-interval')
+  const pingIntervalValueIdx = (pingIntervalIdx !== -1 && args[pingIntervalIdx + 1] && !args[pingIntervalIdx + 1].startsWith('--'))
+    ? pingIntervalIdx + 1
     : -1
 
   // 📖 Set of arg indices that are values for flags (not API keys)
   const skipIndices = new Set()
   if (tierValueIdx !== -1) skipIndices.add(tierValueIdx)
-  if (profileValueIdx !== -1) skipIndices.add(profileValueIdx)
+  if (sortValueIdx !== -1) skipIndices.add(sortValueIdx)
+  if (originValueIdx !== -1) skipIndices.add(originValueIdx)
+  if (pingIntervalValueIdx !== -1) skipIndices.add(pingIntervalValueIdx)
 
   for (const [i, arg] of args.entries()) {
     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
+      // 📖 Skip — this is a value for --tier, not an API key
     } else if (!apiKey) {
       apiKey = arg
     }
@@ -446,12 +459,25 @@ export function parseArgs(argv) {
   const piMode = flags.includes('--pi')
   const noTelemetry = flags.includes('--no-telemetry')
   const cleanProxyMode = flags.includes('--clean-proxy') || flags.includes('--proxy-clean')
+  const proxyForegroundMode = flags.includes('--proxy')
   const jsonMode = flags.includes('--json')
   const helpMode = flags.includes('--help') || flags.includes('-h')
+  const premiumMode = flags.includes('--premium')
+
+  // New boolean flags
+  const sortDesc = flags.includes('--desc')
+  const sortAscFlag = flags.includes('--asc')
+  const hideUnconfigured = flags.includes('--hide-unconfigured')
+  const showUnconfigured = flags.includes('--show-unconfigured')
+  const disableWidthsWarning = flags.includes('--disable-widths-warning')
 
   let tierFilter = tierValueIdx !== -1 ? args[tierValueIdx].toUpperCase() : null
+  let sortColumn = sortValueIdx !== -1 ? args[sortValueIdx].toLowerCase() : null
+  let originFilter = originValueIdx !== -1 ? args[originValueIdx] : null
+  let pingInterval = pingIntervalValueIdx !== -1 ? parseInt(args[pingIntervalValueIdx], 10) : null
+  let sortDirection = sortDesc ? 'desc' : (sortAscFlag ? 'asc' : null)
 
-  const profileName = profileValueIdx !== -1 ? args[profileValueIdx] : null
+  // 📖 Profile system removed - API keys now persist permanently across all sessions
 
   // 📖 --recommend — launch directly into Smart Recommend mode (Q key equivalent)
   const recommendMode = flags.includes('--recommend')
@@ -478,8 +504,17 @@ export function parseArgs(argv) {
     jsonMode,
     helpMode,
     tierFilter,
-    profileName,
-    recommendMode
+    sortColumn,
+    sortDirection,
+    originFilter,
+    pingInterval,
+    hideUnconfigured,
+    showUnconfigured,
+    disableWidthsWarning,
+    premiumMode,
+    // 📖 Profile system removed - API keys now persist permanently across all sessions
+    recommendMode,
+    proxyForegroundMode,
   }
 }