free-coding-models 0.1.82 → 0.1.83

package/lib/request-transformer.js

@@ -0,0 +1,180 @@
+/**
+ * request-transformer.js
+ *
+ * Utilities for transforming outgoing API request bodies before they are
+ * forwarded to a model provider:
+ *   - applyThinkingBudget  — control Anthropic-style "thinking" budget
+ *   - compressContext      — reduce prompt size at increasing compression levels
+ */
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Count the total characters contributed by a single message.
+ * Handles both plain-string content and array-of-blocks content.
+ *
+ * @param {object} msg
+ * @returns {number}
+ */
+function messageCharCount(msg) {
+  if (typeof msg.content === 'string') return msg.content.length
+  if (Array.isArray(msg.content)) {
+    return msg.content.reduce((sum, block) => {
+      if (typeof block === 'string') return sum + block.length
+      if (block.type === 'text') return sum + (block.text?.length || 0)
+      if (block.type === 'thinking') return sum + (block.thinking?.length || 0)
+      return sum
+    }, 0)
+  }
+  return 0
+}
+
+// ---------------------------------------------------------------------------
+// applyThinkingBudget
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach (or omit) an Anthropic-style "thinking" budget to the request body.
+ *
+ * Modes:
+ *   'passthrough' — return a shallow copy of body with no changes
+ *   'custom'      — add thinking: { budget_tokens: config.budget_tokens }
+ *   'auto'        — add thinking only when the total prompt is > 2 000 chars;
+ *                   budget is proportional: min(totalChars * 2, 32 000)
+ *
+ * The original body is NEVER mutated.
+ *
+ * @param {object} body        - The request body (OpenAI-compatible shape)
+ * @param {{ mode: string, budget_tokens?: number }} config
+ * @returns {object}           - A new body object
+ */
+export function applyThinkingBudget(body, config) {
+  const { mode } = config
+
+  if (mode === 'passthrough') {
+    return { ...body }
+  }
+
+  if (mode === 'custom') {
+    return { ...body, thinking: { budget_tokens: config.budget_tokens } }
+  }
+
+  if (mode === 'auto') {
+    const messages = Array.isArray(body.messages) ? body.messages : []
+    const totalChars = messages.reduce((sum, msg) => {
+      if (typeof msg.content === 'string') return sum + msg.content.length
+      if (Array.isArray(msg.content)) {
+        return sum + msg.content.reduce((s, block) => {
+          if (typeof block === 'string') return s + block.length
+          return s + (block.text?.length || 0) + (block.thinking?.length || 0)
+        }, 0)
+      }
+      return sum
+    }, 0)
+
+    if (totalChars > 2000) {
+      const budget_tokens = Math.min(Math.floor(totalChars * 2), 32000)
+      return { ...body, thinking: { budget_tokens } }
+    }
+
+    return { ...body }
+  }
+
+  // Unknown mode — return shallow copy unchanged
+  return { ...body }
+}
+
+// ---------------------------------------------------------------------------
+// compressContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Reduce the size of the messages array at increasing compression levels.
+ *
+ * Levels:
+ *   0 — no change (shallow copy of array)
+ *   1 — truncate tool-result messages whose content exceeds toolResultMaxChars
+ *   2 — L1 + truncate thinking blocks in assistant messages
+ *   3 — L2 + drop oldest non-system messages when total chars exceed maxTotalChars
+ *
+ * The original messages array and its objects are NEVER mutated.
+ *
+ * @param {object[]} messages
+ * @param {{
+ *   level?: number,
+ *   toolResultMaxChars?: number,
+ *   thinkingMaxChars?: number,
+ *   maxTotalChars?: number
+ * }} opts
+ * @returns {object[]}
+ */
+export function compressContext(messages, opts = {}) {
+  const {
+    level = 0,
+    toolResultMaxChars = 4000,
+    thinkingMaxChars = 1000,
+    maxTotalChars = 100000,
+  } = opts
+
+  if (level === 0) {
+    return [...messages]
+  }
+
+  // L1: trim oversized tool results
+  let result = messages.map(msg => {
+    if (msg.role === 'tool' && typeof msg.content === 'string') {
+      if (msg.content.length > toolResultMaxChars) {
+        return {
+          ...msg,
+          content: msg.content.slice(0, toolResultMaxChars) + '\n[truncated]',
+        }
+      }
+    }
+    return msg
+  })
+
+  if (level === 1) {
+    return result
+  }
+
+  // L2: trim thinking blocks in assistant messages
+  result = result.map(msg => {
+    if (msg.role === 'assistant' && Array.isArray(msg.content)) {
+      const newContent = msg.content.map(block => {
+        if (
+          block.type === 'thinking' &&
+          typeof block.thinking === 'string' &&
+          block.thinking.length > thinkingMaxChars
+        ) {
+          return { ...block, thinking: block.thinking.slice(0, thinkingMaxChars) }
+        }
+        return block
+      })
+      // Only create a new message object when something actually changed
+      const changed = newContent.some((b, i) => b !== msg.content[i])
+      return changed ? { ...msg, content: newContent } : msg
+    }
+    return msg
+  })
+
+  if (level === 2) {
+    return result
+  }
+
+  // L3: drop oldest non-system messages until total chars is within budget
+  // Always preserve: every 'system' message, and the last message in the array.
+  const totalChars = () => result.reduce((sum, msg) => sum + messageCharCount(msg), 0)
+
+  while (totalChars() > maxTotalChars && result.length > 1) {
+    // Find the first droppable message: not 'system', not the last one
+    const dropIdx = result.findIndex(
+      (msg, idx) => msg.role !== 'system' && idx !== result.length - 1
+    )
+    if (dropIdx === -1) break // nothing left to drop
+    result = [...result.slice(0, dropIdx), ...result.slice(dropIdx + 1)]
+  }
+
+  return result
+}

package/lib/token-stats.js

@@ -0,0 +1,242 @@
+/**
+ * @file lib/token-stats.js
+ * @description Persistent token usage tracking for the multi-account proxy.
+ *
+ * Records per-account and per-model token usage, hourly/daily aggregates,
+ * an in-memory ring buffer of the 100 most-recent requests, and an
+ * append-only JSONL log file for detailed history.
+ *
+ * Storage locations:
+ *   ~/.free-coding-models/token-stats.json  — aggregated stats (auto-saved every 10 records)
+ *   ~/.free-coding-models/request-log.jsonl — timestamped per-request log (pruned after 30 days)
+ *
+ * @exports TokenStats
+ */
+
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const DEFAULT_DATA_DIR = join(homedir(), '.free-coding-models')
+const MAX_RING_BUFFER = 100
+const RETENTION_DAYS = 30
+
+function timestampToMillis(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const numeric = Number(value)
+    if (Number.isFinite(numeric)) return numeric
+    const parsed = Date.parse(value)
+    if (!Number.isNaN(parsed)) return parsed
+  }
+  return null
+}
+
+export class TokenStats {
+  /**
+   * @param {{ dataDir?: string }} [opts]
+   *   dataDir  — override the default ~/.free-coding-models directory (used in tests)
+   */
+  constructor({ dataDir } = {}) {
+    this._dataDir = dataDir || DEFAULT_DATA_DIR
+    this._statsFile = join(this._dataDir, 'token-stats.json')
+    this._logFile = join(this._dataDir, 'request-log.jsonl')
+    this._stats = {
+      byAccount: {},
+      byModel: {},
+      hourly: {},
+      daily: {},
+      quotaSnapshots: { byAccount: {}, byModel: {}, byProvider: {} },
+    }
+    this._ringBuffer = []
+    this._recordsSinceLastSave = 0
+    this._load()
+    setImmediate(() => this._pruneOldLogs())
+  }
+
+  _load() {
+    try {
+      mkdirSync(this._dataDir, { recursive: true })
+      if (existsSync(this._statsFile)) {
+        const loaded = JSON.parse(readFileSync(this._statsFile, 'utf8'))
+        this._stats = loaded
+      }
+    } catch { /* start fresh */ }
+    // Ensure quotaSnapshots always exists (backward compat for old files)
+    if (!this._stats.quotaSnapshots || typeof this._stats.quotaSnapshots !== 'object') {
+      this._stats.quotaSnapshots = { byAccount: {}, byModel: {}, byProvider: {} }
+    }
+    if (!this._stats.quotaSnapshots.byAccount) this._stats.quotaSnapshots.byAccount = {}
+    if (!this._stats.quotaSnapshots.byModel) this._stats.quotaSnapshots.byModel = {}
+    if (!this._stats.quotaSnapshots.byProvider) this._stats.quotaSnapshots.byProvider = {}
+  }
+
+  _pruneOldLogs() {
+    try {
+      if (!existsSync(this._logFile)) return
+      const cutoff = Date.now() - RETENTION_DAYS * 86400000
+      const lines = readFileSync(this._logFile, 'utf8').split('\n').filter(Boolean)
+      const kept = lines.filter(line => {
+        try {
+          const millis = timestampToMillis(JSON.parse(line).timestamp)
+          return millis !== null && millis >= cutoff
+        } catch {
+          return false
+        }
+      })
+      writeFileSync(this._logFile, kept.join('\n') + (kept.length ? '\n' : ''))
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * Record a single request's token usage.
+   *
+   * @param {{ accountId: string, modelId: string, providerKey?: string, statusCode?: number|string, requestType?: string, promptTokens?: number, completionTokens?: number, latencyMs?: number, success?: boolean }} entry
+   */
+  record(entry) {
+    const {
+      accountId,
+      modelId,
+      providerKey = 'unknown',
+      statusCode = 200,
+      requestType = 'chat.completions',
+      promptTokens = 0,
+      completionTokens = 0,
+      latencyMs = 0,
+      success = true,
+    } = entry
+    const totalTokens = promptTokens + completionTokens
+    const now = new Date()
+    const hourKey = now.toISOString().slice(0, 13)
+    const dayKey = now.toISOString().slice(0, 10)
+
+    // By account
+    const acct = this._stats.byAccount[accountId] ||= { requests: 0, tokens: 0, errors: 0 }
+    acct.requests++
+    acct.tokens += totalTokens
+    if (!success) acct.errors++
+
+    // By model
+    const model = this._stats.byModel[modelId] ||= { requests: 0, tokens: 0 }
+    model.requests++
+    model.tokens += totalTokens
+
+    // Hourly
+    this._stats.hourly[hourKey] ||= { requests: 0, tokens: 0 }
+    this._stats.hourly[hourKey].requests++
+    this._stats.hourly[hourKey].tokens += totalTokens
+
+    // Daily
+    this._stats.daily[dayKey] ||= { requests: 0, tokens: 0 }
+    this._stats.daily[dayKey].requests++
+    this._stats.daily[dayKey].tokens += totalTokens
+
+    // Ring buffer (newest at end)
+    this._ringBuffer.push({ ...entry, timestamp: now.toISOString() })
+    if (this._ringBuffer.length > MAX_RING_BUFFER) this._ringBuffer.shift()
+
+    // JSONL log
+    try {
+      const logEntry = {
+        timestamp: now.toISOString(),
+        accountId,
+        modelId,
+        providerKey,
+        statusCode,
+        requestType,
+        promptTokens,
+        completionTokens,
+        latencyMs,
+        success,
+      }
+      appendFileSync(this._logFile, JSON.stringify(logEntry) + '\n')
+    } catch { /* ignore */ }
+
+    // Auto-save every 10 records
+    this._recordsSinceLastSave++
+    if (this._recordsSinceLastSave >= 10) this.save()
+  }
+
+  save() {
+    try {
+      mkdirSync(this._dataDir, { recursive: true })
+      writeFileSync(this._statsFile, JSON.stringify(this._stats, null, 2))
+      this._recordsSinceLastSave = 0
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * Persist a quota snapshot for a single account.
+   * Also recomputes the per-model aggregate quota if modelId is provided.
+   * Tracks latest provider-level quota snapshot when providerKey is provided.
+   *
+   * Quota snapshots are lightweight (not per-request) and are written to
+   * token-stats.json immediately so the TUI can read them without waiting
+   * for the next 10-record auto-save cycle.
+   *
+   * @param {string} accountId
+   * @param {{ quotaPercent: number, providerKey?: string, modelId?: string, updatedAt?: string }} opts
+   */
+  updateQuotaSnapshot(accountId, { quotaPercent, providerKey, modelId, updatedAt } = {}) {
+    const snap = {
+      quotaPercent,
+      updatedAt: updatedAt || new Date().toISOString(),
+    }
+    if (providerKey !== undefined) snap.providerKey = providerKey
+    if (modelId !== undefined) snap.modelId = modelId
+
+    this._stats.quotaSnapshots.byAccount[accountId] = snap
+
+    if (modelId !== undefined) {
+      this._recomputeModelQuota(modelId)
+    }
+
+    if (providerKey !== undefined) {
+      this._stats.quotaSnapshots.byProvider[providerKey] = {
+        quotaPercent,
+        updatedAt: snap.updatedAt,
+      }
+    }
+
+    // Persist immediately (quota data must be fresh for TUI reads)
+    this.save()
+  }
+
+  /**
+   * Recompute the per-model quota snapshot by averaging all account snapshots
+   * that share the given modelId.
+   *
+   * @param {string} modelId
+   */
+  _recomputeModelQuota(modelId) {
+    const accountSnaps = Object.values(this._stats.quotaSnapshots.byAccount)
+      .filter(s => s.modelId === modelId)
+
+    if (accountSnaps.length === 0) return
+
+    const avgPercent = Math.round(
+      accountSnaps.reduce((sum, s) => sum + s.quotaPercent, 0) / accountSnaps.length
+    )
+    const latestUpdatedAt = accountSnaps.reduce(
+      (latest, s) => (s.updatedAt > latest ? s.updatedAt : latest),
+      accountSnaps[0].updatedAt
+    )
+
+    this._stats.quotaSnapshots.byModel[modelId] = {
+      quotaPercent: avgPercent,
+      updatedAt: latestUpdatedAt,
+    }
+  }
+
+  /**
+   * Return a summary snapshot including the 10 most-recent requests.
+   *
+   * @returns {{ byAccount: object, byModel: object, hourly: object, daily: object, recentRequests: object[] }}
+   */
+  getSummary() {
+    return {
+      ...this._stats,
+      recentRequests: this._ringBuffer.slice(-10),
+    }
+  }
+}

package/lib/usage-reader.js

@@ -0,0 +1,203 @@
+/**
+ * @file lib/usage-reader.js
+ * @description Pure functions to read model quota usage from token-stats.json.
+ *
+ * Designed for TUI consumption: reads the pre-computed `quotaSnapshots.byModel`
+ * section from the JSON file written by TokenStats.  Never reads the JSONL log.
+ *
+ * All functions are pure (no shared mutable state) and handle missing/malformed
+ * files gracefully by returning safe fallback values.
+ *
+ * Default path: ~/.free-coding-models/token-stats.json
+ *
+ * ## Freshness contract
+ * Usage snapshots carry an `updatedAt` ISO timestamp.  Any entry whose
+ * `updatedAt` is older than SNAPSHOT_TTL_MS (30 minutes) is excluded and
+ * treated as `N/A` by the UI.  Entries that predate this feature (no
+ * `updatedAt` field) are included for backward compatibility.
+ *
+ * ## Parse cache
+ * `loadUsageSnapshot` maintains a module-level in-memory cache keyed by the
+ * resolved stats-file path.  Each cache entry is valid for CACHE_TTL_MS
+ * (500 ms – 1 000 ms).  This avoids redundant synchronous disk reads when the
+ * TUI rerenders multiple times within the same tick or across a few frames.
+ * The 30-minute data-freshness filter (SNAPSHOT_TTL_MS) is applied every time
+ * the snapshot is parsed — caching never bypasses it.
+ *
+ * Use `clearUsageCache()` to evict all entries (useful in tests).
+ *
+ * @exports SNAPSHOT_TTL_MS
+ * @exports CACHE_TTL_MS
+ * @exports clearUsageCache
+ * @exports loadUsageSnapshot
+ * @exports loadUsageMap
+ * @exports usageForModelId
+ * @exports usageForRow
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const DEFAULT_STATS_FILE = join(homedir(), '.free-coding-models', 'token-stats.json')
+
+/**
+ * Freshness TTL for quota snapshots in milliseconds (30 minutes).
+ * Snapshots older than this are treated as stale and excluded from results.
+ * The UI renders stale/missing entries as `N/A`.
+ */
+export const SNAPSHOT_TTL_MS = 30 * 60 * 1000
+
+/**
+ * TTL for the module-level parse cache in milliseconds (750 ms).
+ * Within this window repeated calls to loadUsageSnapshot with the same path
+ * return the already-parsed result without touching the filesystem.
+ */
+export const CACHE_TTL_MS = 750
+
+/**
+ * Module-level cache: path → { snapshot, expiresAt }
+ * @type {Map<string, { snapshot: { byModel: Record<string, number>, byProvider: Record<string, number> }, expiresAt: number }>}
+ */
+const _cache = new Map()
+
+/**
+ * Evict all cached parse results.  Subsequent calls to loadUsageSnapshot will
+ * re-read from disk.  Primarily intended for use in tests.
+ */
+export function clearUsageCache() {
+  _cache.clear()
+}
+
+/**
+ * Returns true when the snapshot entry is considered fresh enough to display.
+ *
+ * Rules:
+ * - If `updatedAt` is absent (older format): include for backward compatibility.
+ * - If `updatedAt` parses to a time older than SNAPSHOT_TTL_MS ago: exclude (stale).
+ * - If `updatedAt` is within TTL (strictly less than TTL ms ago): include.
+ *
+ * @param {{ updatedAt?: string }} entry
+ * @param {number} [nowMs] - optional current time (ms) for testability
+ * @returns {boolean}
+ */
+function isSnapshotFresh(entry, nowMs = Date.now()) {
+  if (!entry || typeof entry.updatedAt !== 'string') return true // backward compat
+  const updatedMs = Date.parse(entry.updatedAt)
+  if (!Number.isFinite(updatedMs)) return true // unparseable: be generous
+  return nowMs - updatedMs < SNAPSHOT_TTL_MS
+}
+
+/**
+ * Load token-stats.json and return model/provider usage maps.
+ * Entries with stale `updatedAt` (older than SNAPSHOT_TTL_MS) are excluded.
+ *
+ * Results are cached in memory for CACHE_TTL_MS to avoid repeated disk reads.
+ * The 30-minute data freshness filter is re-applied on every cache miss (parse).
+ *
+ * @param {string} [statsFile]
+ * @returns {{ byModel: Record<string, number>, byProvider: Record<string, number> }}
+ */
+export function loadUsageSnapshot(statsFile = DEFAULT_STATS_FILE) {
+  const now = Date.now()
+
+  // Return cached result if still valid
+  const cached = _cache.get(statsFile)
+  if (cached && now < cached.expiresAt) {
+    return cached.snapshot
+  }
+
+  // Cache miss — parse from disk
+  const snapshot = _parseSnapshot(statsFile, now)
+  _cache.set(statsFile, { snapshot, expiresAt: now + CACHE_TTL_MS })
+  return snapshot
+}
+
+/**
+ * Internal: read and parse token-stats.json without caching.
+ *
+ * @param {string} statsFile
+ * @param {number} now - current time in ms (for freshness checks)
+ * @returns {{ byModel: Record<string, number>, byProvider: Record<string, number> }}
+ */
+function _parseSnapshot(statsFile, now) {
+  try {
+    if (!existsSync(statsFile)) return { byModel: {}, byProvider: {} }
+    const raw = readFileSync(statsFile, 'utf8')
+    const data = JSON.parse(raw)
+
+    const byModelSrc = data?.quotaSnapshots?.byModel
+    const byProviderSrc = data?.quotaSnapshots?.byProvider
+
+    const byModel = {}
+    if (byModelSrc && typeof byModelSrc === 'object') {
+      for (const [modelId, entry] of Object.entries(byModelSrc)) {
+        if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
+          if (isSnapshotFresh(entry, now)) {
+            byModel[modelId] = entry.quotaPercent
+          }
+        }
+      }
+    }
+
+    const byProvider = {}
+    if (byProviderSrc && typeof byProviderSrc === 'object') {
+      for (const [providerKey, entry] of Object.entries(byProviderSrc)) {
+        if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
+          if (isSnapshotFresh(entry, now)) {
+            byProvider[providerKey] = entry.quotaPercent
+          }
+        }
+      }
+    }
+
+    return { byModel, byProvider }
+  } catch {
+    return { byModel: {}, byProvider: {} }
+  }
+}
+
+/**
+ * Load token-stats.json and return a plain object mapping modelId → quotaPercent.
+ *
+ * Only includes models whose `quotaPercent` is a finite number and whose
+ * snapshot is fresh (within SNAPSHOT_TTL_MS).
+ * Returns an empty object on any error (missing file, bad JSON, missing keys).
+ *
+ * @param {string} [statsFile] - Path to token-stats.json (defaults to ~/.free-coding-models/token-stats.json)
+ * @returns {Record<string, number>}  e.g. { 'claude-3-5': 80, 'gpt-4o': 45 }
+ */
+export function loadUsageMap(statsFile = DEFAULT_STATS_FILE) {
+  return loadUsageSnapshot(statsFile).byModel
+}
+
+/**
+ * Return the quota percent remaining for a specific model.
+ * Returns null if the model has no snapshot or its snapshot is stale.
+ *
+ * @param {string} modelId
+ * @param {string} [statsFile] - Path to token-stats.json (defaults to ~/.free-coding-models/token-stats.json)
+ * @returns {number | null}  quota percent (0–100), or null if unknown/stale
+ */
+export function usageForModelId(modelId, statsFile = DEFAULT_STATS_FILE) {
+  const map = loadUsageMap(statsFile)
+  const value = map[modelId]
+  return value !== undefined ? value : null
+}
+
+/**
+ * Return quota percent for a table row with model-first, provider fallback.
+ * Both model and provider snapshots are checked for freshness independently.
+ * Returns null when both are absent or stale.
+ *
+ * @param {string} providerKey
+ * @param {string} modelId
+ * @param {string} [statsFile]
+ * @returns {number | null}
+ */
+export function usageForRow(providerKey, modelId, statsFile = DEFAULT_STATS_FILE) {
+  const { byModel, byProvider } = loadUsageSnapshot(statsFile)
+  if (byModel[modelId] !== undefined) return byModel[modelId]
+  if (byProvider[providerKey] !== undefined) return byProvider[providerKey]
+  return null
+}

package/lib/utils.js

@@ -310,6 +310,12 @@ export const sortResults = (results, sortColumn, sortDirection) => {
         // 📖 Models with no data (-1) sort to the bottom
         cmp = getStabilityScore(a) - getStabilityScore(b)
         break
+      case 'usage':
+        // 📖 Sort by quota usage percent (usagePercent numeric field, 0–100)
+        // 📖 Models with no usage data (undefined/null) are treated as 0 — stable tie-break
+        // 📖 via JS stable sort preserving original order when values are equal
+        cmp = (a.usagePercent ?? 0) - (b.usagePercent ?? 0)
+        break
     }
 
     // 📖 Flip comparison for descending order
@@ -598,3 +604,52 @@ export function getTopRecommendations(results, taskType, priority, contextBudget
 
   return scored.slice(0, topN)
 }
+
+/**
+ * 📖 getProxyStatusInfo: Pure function that maps startup proxy status + active proxy state
+ * 📖 to a normalised descriptor object consumed by the TUI footer indicator.
+ *
+ * 📖 Priority of evaluation:
+ *   1. proxyStartupStatus.phase === 'starting' → state:'starting'
+ *   2. proxyStartupStatus.phase === 'running'  → state:'running' with port/accountCount
+ *   3. proxyStartupStatus.phase === 'failed'   → state:'failed' with truncated reason
+ *   4. isProxyActive (legacy activeProxy flag)  → state:'running' (no port detail)
+ *   5. otherwise                               → state:'stopped'
+ *
+ * 📖 Reason is clamped to 80 characters to keep footer readable (no stack traces).
+ *
+ * @param {object|null} proxyStartupStatus — state.proxyStartupStatus value
+ * @param {boolean} isProxyActive — truthy when the module-level activeProxy is non-null
+ * @returns {{ state: string, port?: number, accountCount?: number, reason?: string }}
+ */
+export function getProxyStatusInfo(proxyStartupStatus, isProxyActive) {
+  const MAX_REASON = 80
+
+  if (proxyStartupStatus) {
+    const { phase } = proxyStartupStatus
+    if (phase === 'starting') {
+      return { state: 'starting' }
+    }
+    if (phase === 'running') {
+      return {
+        state: 'running',
+        port: proxyStartupStatus.port,
+        accountCount: proxyStartupStatus.accountCount,
+      }
+    }
+    if (phase === 'failed') {
+      const raw = proxyStartupStatus.reason ?? 'unknown error'
+      return {
+        state: 'failed',
+        reason: raw.length > MAX_REASON ? raw.slice(0, MAX_REASON - 1) + '…' : raw,
+      }
+    }
+  }
+
+  // 📖 Legacy fallback: activeProxy set directly (e.g. from manual proxy start without startup status)
+  if (isProxyActive) {
+    return { state: 'running' }
+  }
+
+  return { state: 'stopped' }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",