free-coding-models 0.1.83 → 0.1.84

package/src/telemetry.js

@@ -0,0 +1,382 @@
+/**
+ * @file telemetry.js
+ * @description Anonymous usage telemetry and Discord feedback webhooks.
+ *              Extracted from bin/free-coding-models.js to keep the main entry point lean.
+ *
+ * @details
+ *   All telemetry is strictly opt-in-by-default, fire-and-forget, and anonymous:
+ *   - A stable `anonymousId` (UUID prefixed with "anon_") is generated once and stored
+ *     in ~/.free-coding-models.json.  No personal data is ever collected.
+ *   - PostHog is used for product analytics (app_start events, mode, platform).
+ *   - Discord webhooks carry anonymous feature requests (J key) and bug reports (I key).
+ *   - `isTelemetryEnabled()` checks: CLI flag → env var → default (enabled).
+ *   - `telemetryDebug()` writes to stderr only when FREE_CODING_MODELS_TELEMETRY_DEBUG=1.
+ *   - `sendUsageTelemetry()` has a hard 1.2 s timeout so it never blocks startup.
+ *
+ *   ⚙️ Configuration (env vars, all optional):
+ *   - FREE_CODING_MODELS_TELEMETRY=0|false|off  — disable telemetry globally
+ *   - FREE_CODING_MODELS_TELEMETRY_DEBUG=1       — print debug traces to stderr
+ *   - FREE_CODING_MODELS_POSTHOG_KEY             — override the PostHog project key
+ *   - FREE_CODING_MODELS_POSTHOG_HOST            — override the PostHog host
+ *   - POSTHOG_PROJECT_API_KEY / POSTHOG_HOST     — standard PostHog env vars (fallback)
+ *
+ * @functions
+ *   → parseTelemetryEnv(value)                    — Convert env string to boolean or null
+ *   → isTelemetryDebugEnabled()                   — Check debug flag from env
+ *   → telemetryDebug(message, meta)               — Conditional debug trace to stderr
+ *   → ensureTelemetryConfig(config)               — Ensure telemetry shape in config object
+ *   → getTelemetryDistinctId(config)              — Get/create stable anonymous ID
+ *   → getTelemetrySystem()                        — Convert platform to human label
+ *   → getTelemetryTerminal()                      — Infer terminal family from env hints
+ *   → isTelemetryEnabled(config, cliArgs)         — Resolve effective enabled state
+ *   → sendUsageTelemetry(config, cliArgs, payload)— Fire-and-forget PostHog ping
+ *   → sendFeatureRequest(message)                 — Post anonymous feature request to Discord
+ *   → sendBugReport(message)                      — Post anonymous bug report to Discord
+ *
+ * @exports
+ *   parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug,
+ *   ensureTelemetryConfig, getTelemetryDistinctId,
+ *   getTelemetrySystem, getTelemetryTerminal,
+ *   isTelemetryEnabled, sendUsageTelemetry,
+ *   sendFeatureRequest, sendBugReport
+ *
+ * @see src/config.js  — saveConfig is imported here to persist the generated anonymousId
+ * @see bin/free-coding-models.js — calls sendUsageTelemetry on startup and on key events
+ */
+
+import { randomUUID } from 'crypto'
+import { createRequire } from 'module'
+import { saveConfig } from './config.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+const LOCAL_VERSION = pkg.version
+
+// 📖 PostHog capture endpoint and defaults.
+// 📖 These are public ingest tokens — safe to publish in open-source code.
+const TELEMETRY_TIMEOUT          = 1_200
+const POSTHOG_CAPTURE_PATH       = '/i/v0/e/'
+const POSTHOG_DEFAULT_HOST       = 'https://eu.i.posthog.com'
+const POSTHOG_PROJECT_KEY_DEFAULT = 'phc_5P1n8HaLof6nHM0tKJYt4bV5pj2XPb272fLVigwf1YQ'
+const POSTHOG_HOST_DEFAULT       = 'https://eu.i.posthog.com'
+
+// 📖 Discord feature request webhook configuration (anonymous feedback system).
+const DISCORD_WEBHOOK_URL   = 'https://discord.com/api/webhooks/1476709155992764427/hmnHNtpducvi5LClhv8DynENjUmmg9q8HI1Bx1lNix56UHqrqZf55rW95LGvNJ2W4j7D'
+const DISCORD_BOT_NAME      = 'TUI - Feature Requests'
+const DISCORD_EMBED_COLOR   = 0x39FF14  // Vert fluo (RGB: 57, 255, 20)
+
+// 📖 Discord bug report webhook configuration (anonymous bug reports).
+const DISCORD_BUG_WEBHOOK_URL  = 'https://discord.com/api/webhooks/1476715954409963743/5cOLf7U_891f1jwxRBLIp2RIP9xYhr4rWtOhipzKKwVdFVl1Bj89X_fB6I_uGXZiGT9E'
+const DISCORD_BUG_BOT_NAME     = 'TUI Bug Report'
+const DISCORD_BUG_EMBED_COLOR  = 0xFF5733  // Rouge (RGB: 255, 87, 51)
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * 📖 parseTelemetryEnv: Convert env var strings into booleans.
+ * 📖 Returns true/false when value is recognized, otherwise null.
+ * @param {unknown} value
+ * @returns {boolean|null}
+ */
+export function parseTelemetryEnv(value) {
+  if (typeof value !== 'string') return null
+  const normalized = value.trim().toLowerCase()
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false
+  return null
+}
+
+/**
+ * 📖 Optional debug switch for telemetry troubleshooting (disabled by default).
+ * @returns {boolean}
+ */
+export function isTelemetryDebugEnabled() {
+  return parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY_DEBUG) === true
+}
+
+/**
+ * 📖 Writes telemetry debug traces to stderr only when explicitly enabled.
+ * @param {string} message
+ * @param {unknown} [meta]
+ */
+export function telemetryDebug(message, meta = null) {
+  if (!isTelemetryDebugEnabled()) return
+  const prefix = '[telemetry-debug]'
+  if (meta === null) {
+    process.stderr.write(`${prefix} ${message}\n`)
+    return
+  }
+  try {
+    process.stderr.write(`${prefix} ${message} ${JSON.stringify(meta)}\n`)
+  } catch {
+    process.stderr.write(`${prefix} ${message}\n`)
+  }
+}
+
+/**
+ * 📖 Ensure telemetry config shape exists even on old config files.
+ * @param {Record<string, unknown>} config
+ */
+export function ensureTelemetryConfig(config) {
+  if (!config.telemetry || typeof config.telemetry !== 'object') {
+    config.telemetry = { enabled: true, anonymousId: null }
+  }
+  // 📖 Only default enabled when unset; do not override a user's explicit opt-out
+  if (typeof config.telemetry.enabled !== 'boolean') {
+    config.telemetry.enabled = true
+  }
+  if (typeof config.telemetry.anonymousId !== 'string' || !config.telemetry.anonymousId.trim()) {
+    config.telemetry.anonymousId = null
+  }
+}
+
+/**
+ * 📖 Create or reuse a persistent anonymous distinct_id for PostHog.
+ * 📖 Stored locally in config so one user is stable over time without personal data.
+ * @param {Record<string, unknown>} config
+ * @returns {string}
+ */
+export function getTelemetryDistinctId(config) {
+  ensureTelemetryConfig(config)
+  if (config.telemetry.anonymousId) return config.telemetry.anonymousId
+
+  config.telemetry.anonymousId = `anon_${randomUUID()}`
+  saveConfig(config)
+  return config.telemetry.anonymousId
+}
+
+/**
+ * 📖 Convert Node platform to human-readable system name for analytics segmentation.
+ * @returns {string}
+ */
+export function getTelemetrySystem() {
+  if (process.platform === 'darwin') return 'macOS'
+  if (process.platform === 'win32') return 'Windows'
+  if (process.platform === 'linux') return 'Linux'
+  return process.platform
+}
+
+/**
+ * 📖 Infer terminal family from environment hints for coarse usage segmentation.
+ * 📖 Never sends full env dumps; only a normalized terminal label is emitted.
+ * @returns {string}
+ */
+export function getTelemetryTerminal() {
+  const termProgramRaw = (process.env.TERM_PROGRAM || '').trim()
+  const termProgram = termProgramRaw.toLowerCase()
+  const term = (process.env.TERM || '').toLowerCase()
+
+  if (termProgram === 'apple_terminal') return 'Terminal.app'
+  if (termProgram === 'iterm.app') return 'iTerm2'
+  if (termProgram === 'warpterminal' || process.env.WARP_IS_LOCAL_SHELL_SESSION) return 'Warp'
+  if (process.env.WT_SESSION) return 'Windows Terminal'
+  if (process.env.KITTY_WINDOW_ID || term.includes('kitty')) return 'kitty'
+  if (process.env.GHOSTTY_RESOURCES_DIR || term.includes('ghostty')) return 'Ghostty'
+  if (process.env.WEZTERM_PANE || termProgram === 'wezterm') return 'WezTerm'
+  if (process.env.KONSOLE_VERSION || termProgram === 'konsole') return 'Konsole'
+  if (process.env.GNOME_TERMINAL_SCREEN || termProgram === 'gnome-terminal') return 'GNOME Terminal'
+  if (process.env.TERMINAL_EMULATOR === 'JetBrains-JediTerm') return 'JetBrains Terminal'
+  if (process.env.TABBY_CONFIG_DIRECTORY || termProgram === 'tabby') return 'Tabby'
+  if (termProgram === 'vscode' || process.env.VSCODE_GIT_IPC_HANDLE) return 'VS Code Terminal'
+  if (process.env.ALACRITTY_SOCKET || term.includes('alacritty') || termProgram === 'alacritty') return 'Alacritty'
+  if (term.includes('foot') || termProgram === 'foot') return 'foot'
+  if (termProgram === 'hyper' || process.env.HYPER) return 'Hyper'
+  if (process.env.TMUX) return 'tmux'
+  if (process.env.STY) return 'screen'
+  // 📖 Generic fallback for many terminals exposing TERM_PROGRAM (e.g., Rio, Contour, etc.).
+  if (termProgramRaw) return termProgramRaw
+  if (term) return term
+
+  return 'unknown'
+}
+
+/**
+ * 📖 Resolve telemetry effective state with clear precedence:
+ * 📖 CLI flag > env var > enabled by default (forced for all users).
+ * @param {Record<string, unknown>} config
+ * @param {{ noTelemetry?: boolean }} cliArgs
+ * @returns {boolean}
+ */
+export function isTelemetryEnabled(config, cliArgs) {
+  if (cliArgs.noTelemetry) return false
+  const envTelemetry = parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY)
+  if (envTelemetry !== null) return envTelemetry
+  ensureTelemetryConfig(config)
+  return true
+}
+
+/**
+ * 📖 Fire-and-forget analytics ping: never blocks UX, never throws.
+ * @param {Record<string, unknown>} config
+ * @param {{ noTelemetry?: boolean }} cliArgs
+ * @param {{ event?: string, version?: string, mode?: string, ts?: string }} payload
+ */
+export async function sendUsageTelemetry(config, cliArgs, payload) {
+  if (!isTelemetryEnabled(config, cliArgs)) {
+    telemetryDebug('skip: telemetry disabled', {
+      cliNoTelemetry: cliArgs.noTelemetry === true,
+      envTelemetry: process.env.FREE_CODING_MODELS_TELEMETRY || null,
+      configEnabled: config?.telemetry?.enabled ?? null,
+    })
+    return
+  }
+
+  const apiKey = (
+    process.env.FREE_CODING_MODELS_POSTHOG_KEY ||
+    process.env.POSTHOG_PROJECT_API_KEY ||
+    POSTHOG_PROJECT_KEY_DEFAULT ||
+    ''
+  ).trim()
+  if (!apiKey) {
+    telemetryDebug('skip: missing api key')
+    return
+  }
+
+  const host = (
+    process.env.FREE_CODING_MODELS_POSTHOG_HOST ||
+    process.env.POSTHOG_HOST ||
+    POSTHOG_HOST_DEFAULT ||
+    POSTHOG_DEFAULT_HOST
+  ).trim().replace(/\/+$/, '')
+  if (!host) {
+    telemetryDebug('skip: missing host')
+    return
+  }
+
+  try {
+    const endpoint = `${host}${POSTHOG_CAPTURE_PATH}`
+    const distinctId = getTelemetryDistinctId(config)
+    const timestamp = typeof payload?.ts === 'string' ? payload.ts : new Date().toISOString()
+    const signal = (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function')
+      ? AbortSignal.timeout(TELEMETRY_TIMEOUT)
+      : undefined
+
+    const posthogBody = {
+      api_key: apiKey,
+      event: payload?.event || 'app_start',
+      distinct_id: distinctId,
+      timestamp,
+      properties: {
+        $process_person_profile: false,
+        source: 'cli',
+        app: 'free-coding-models',
+        version: payload?.version || LOCAL_VERSION,
+        app_version: payload?.version || LOCAL_VERSION,
+        mode: payload?.mode || 'opencode',
+        system: getTelemetrySystem(),
+        terminal: getTelemetryTerminal(),
+      },
+    }
+
+    await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(posthogBody),
+      signal,
+    })
+    telemetryDebug('sent', {
+      event: posthogBody.event,
+      endpoint,
+      mode: posthogBody.properties.mode,
+      system: posthogBody.properties.system,
+      terminal: posthogBody.properties.terminal,
+    })
+  } catch {
+    // 📖 Ignore failures silently: analytics must never break the CLI.
+    telemetryDebug('error: send failed')
+  }
+}
+
+/**
+ * 📖 sendFeatureRequest: Send anonymous feature request to Discord via webhook.
+ * 📖 Called when user presses J key, types message, and presses Enter.
+ * 📖 Returns success/error status for UI feedback.
+ * @param {string} message
+ * @returns {Promise<{ success: boolean, error: string|null }>}
+ */
+export async function sendFeatureRequest(message) {
+  try {
+    // 📖 Collect anonymous telemetry for context (no personal data)
+    const system = getTelemetrySystem()
+    const terminal = getTelemetryTerminal()
+    const nodeVersion = process.version
+    const arch = process.arch
+    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'Unknown'
+
+    // 📖 Build Discord embed with rich metadata in footer (compact format)
+    const embed = {
+      description: message,
+      color: DISCORD_EMBED_COLOR,
+      timestamp: new Date().toISOString(),
+      footer: {
+        text: `v${LOCAL_VERSION} • ${system} • ${terminal} • ${nodeVersion} • ${arch} • ${timezone}`
+      }
+    }
+
+    const response = await fetch(DISCORD_WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        username: DISCORD_BOT_NAME,
+        embeds: [embed]
+      }),
+      signal: AbortSignal.timeout(10000) // 📖 10s timeout for webhook
+    })
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+
+    return { success: true, error: null }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return { success: false, error: message }
+  }
+}
+
+/**
+ * 📖 sendBugReport: Send anonymous bug report to Discord via webhook.
+ * 📖 Called when user presses I key, types message, and presses Enter.
+ * 📖 Returns success/error status for UI feedback.
+ * @param {string} message
+ * @returns {Promise<{ success: boolean, error: string|null }>}
+ */
+export async function sendBugReport(message) {
+  try {
+    // 📖 Collect anonymous telemetry for context (no personal data)
+    const system = getTelemetrySystem()
+    const terminal = getTelemetryTerminal()
+    const nodeVersion = process.version
+    const arch = process.arch
+    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'Unknown'
+
+    // 📖 Build Discord embed with rich metadata in footer (compact format)
+    const embed = {
+      description: message,
+      color: DISCORD_BUG_EMBED_COLOR,
+      timestamp: new Date().toISOString(),
+      footer: {
+        text: `v${LOCAL_VERSION} • ${system} • ${terminal} • ${nodeVersion} • ${arch} • ${timezone}`
+      }
+    }
+
+    const response = await fetch(DISCORD_BUG_WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        username: DISCORD_BUG_BOT_NAME,
+        embeds: [embed]
+      }),
+      signal: AbortSignal.timeout(10000) // 📖 10s timeout for webhook
+    })
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+
+    return { success: true, error: null }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return { success: false, error: message }
+  }
+}

package/src/tier-colors.js

@@ -0,0 +1,37 @@
+/**
+ * @file tier-colors.js
+ * @description Chalk colour functions for each tier level, extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   The tier system maps model quality tiers (S+, S, A+, A, A-, B+, B, C) to a
+ *   green → yellow → orange → red gradient.  Keeping these colour definitions in their
+ *   own module allows the renderer, overlays, and any future CLI tools to share a
+ *   single, consistent visual language without depending on the whole TUI entry point.
+ *
+ *   The gradient is deliberately designed so that the higher the tier the more
+ *   "neon" and attention-grabbing the colour, while lower tiers fade toward dark red.
+ *   `chalk.rgb()` is used for fine-grained control — terminal 256-colour and truecolour
+ *   modes both support this; on terminals that don't, chalk gracefully degrades.
+ *
+ * @exports
+ *   TIER_COLOR — object mapping tier string → chalk colouring function
+ *
+ * @see src/constants.js   — TIER_CYCLE ordering that drives the T-key filter
+ * @see bin/free-coding-models.js — renderTable() uses TIER_COLOR per row
+ */
+
+import chalk from 'chalk'
+
+// 📖 Tier colors: green gradient (best) → yellow → orange → red (worst).
+// 📖 Uses chalk.rgb() for fine-grained color control across 8 tier levels.
+// 📖 Each entry is a function (t) => styled string so it can be applied to any text.
+export const TIER_COLOR = {
+  'S+': t => chalk.bold.rgb(0,   255,  80)(t),   // 🟢 bright neon green  — elite
+  'S':  t => chalk.bold.rgb(80,  220,   0)(t),   // 🟢 green              — excellent
+  'A+': t => chalk.bold.rgb(170, 210,   0)(t),   // 🟡 yellow-green       — great
+  'A':  t => chalk.bold.rgb(240, 190,   0)(t),   // 🟡 yellow             — good
+  'A-': t => chalk.bold.rgb(255, 130,   0)(t),   // 🟠 amber              — decent
+  'B+': t => chalk.bold.rgb(255,  70,   0)(t),   // 🟠 orange-red         — average
+  'B':  t => chalk.bold.rgb(210,  20,   0)(t),   // 🔴 red                — below avg
+  'C':  t => chalk.bold.rgb(140,   0,   0)(t),   // 🔴 dark red           — lightweight
+}

package/{lib → src}/token-stats.js

@@ -6,6 +6,14 @@
  * an in-memory ring buffer of the 100 most-recent requests, and an
  * append-only JSONL log file for detailed history.
  *
+ * Quota snapshots are intentionally stored at two granularities:
+ * - byProviderModel: precise UI data for a specific Origin + model pair
+ * - byProvider: fallback when a provider exposes account-level remaining quota
+ *
+ * We still keep the legacy byModel aggregate for backward compatibility and
+ * debugging, but the TUI no longer trusts it for display because the same
+ * model ID can exist under multiple Origins with different limits.
+ *
  * 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)
@@ -46,7 +54,7 @@ export class TokenStats {
       byModel: {},
       hourly: {},
       daily: {},
-      quotaSnapshots: { byAccount: {}, byModel: {}, byProvider: {} },
+      quotaSnapshots: { byAccount: {}, byModel: {}, byProvider: {}, byProviderModel: {} },
     }
     this._ringBuffer = []
     this._recordsSinceLastSave = 0
@@ -64,11 +72,12 @@ export class TokenStats {
     } 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: {} }
+      this._stats.quotaSnapshots = { byAccount: {}, byModel: {}, byProvider: {}, byProviderModel: {} }
     }
     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 = {}
+    if (!this._stats.quotaSnapshots.byProviderModel) this._stats.quotaSnapshots.byProviderModel = {}
   }
 
   _pruneOldLogs() {
@@ -178,6 +187,7 @@ export class TokenStats {
    * @param {{ quotaPercent: number, providerKey?: string, modelId?: string, updatedAt?: string }} opts
    */
   updateQuotaSnapshot(accountId, { quotaPercent, providerKey, modelId, updatedAt } = {}) {
+    const previousSnap = this._stats.quotaSnapshots.byAccount[accountId]
     const snap = {
       quotaPercent,
       updatedAt: updatedAt || new Date().toISOString(),
@@ -187,9 +197,20 @@ export class TokenStats {
 
     this._stats.quotaSnapshots.byAccount[accountId] = snap
 
+    // 📖 Recompute the old aggregate buckets first when an account switches model/provider.
+    if (previousSnap?.modelId !== undefined) {
+      this._recomputeModelQuota(previousSnap.modelId)
+    }
+    if (previousSnap?.providerKey !== undefined && previousSnap?.modelId !== undefined) {
+      this._recomputeProviderModelQuota(previousSnap.providerKey, previousSnap.modelId)
+    }
+
     if (modelId !== undefined) {
       this._recomputeModelQuota(modelId)
     }
+    if (providerKey !== undefined && modelId !== undefined) {
+      this._recomputeProviderModelQuota(providerKey, modelId)
+    }
 
     if (providerKey !== undefined) {
       this._stats.quotaSnapshots.byProvider[providerKey] = {
@@ -202,6 +223,17 @@ export class TokenStats {
     this.save()
   }
 
+  /**
+   * Build a stable key for provider-scoped model quota snapshots.
+   *
+   * @param {string} providerKey
+   * @param {string} modelId
+   * @returns {string}
+   */
+  _providerModelKey(providerKey, modelId) {
+    return `${providerKey}::${modelId}`
+  }
+
   /**
    * Recompute the per-model quota snapshot by averaging all account snapshots
    * that share the given modelId.
@@ -212,7 +244,10 @@ export class TokenStats {
     const accountSnaps = Object.values(this._stats.quotaSnapshots.byAccount)
       .filter(s => s.modelId === modelId)
 
-    if (accountSnaps.length === 0) return
+    if (accountSnaps.length === 0) {
+      delete this._stats.quotaSnapshots.byModel[modelId]
+      return
+    }
 
     const avgPercent = Math.round(
       accountSnaps.reduce((sum, s) => sum + s.quotaPercent, 0) / accountSnaps.length
@@ -228,6 +263,39 @@ export class TokenStats {
     }
   }
 
+  /**
+   * Recompute the provider-scoped quota snapshot for one Origin + model pair.
+   * This is the canonical source used by the TUI Usage column.
+   *
+   * @param {string} providerKey
+   * @param {string} modelId
+   */
+  _recomputeProviderModelQuota(providerKey, modelId) {
+    const accountSnaps = Object.values(this._stats.quotaSnapshots.byAccount)
+      .filter((s) => s.providerKey === providerKey && s.modelId === modelId)
+
+    const key = this._providerModelKey(providerKey, modelId)
+    if (accountSnaps.length === 0) {
+      delete this._stats.quotaSnapshots.byProviderModel[key]
+      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.byProviderModel[key] = {
+      quotaPercent: avgPercent,
+      updatedAt: latestUpdatedAt,
+      providerKey,
+      modelId,
+    }
+  }
+
   /**
    * Return a summary snapshot including the 10 most-recent requests.
    *

package/src/token-usage-reader.js

@@ -0,0 +1,63 @@
+/**
+ * @file token-usage-reader.js
+ * @description Reads historical token usage from request-log.jsonl and aggregates it by exact provider + model pair.
+ *
+ * @details
+ *   The TUI already shows live latency and quota state, but that does not tell
+ *   you how much you've actually consumed on a given Origin. This module reads
+ *   the persistent JSONL request log once at startup and builds a compact
+ *   `provider::model -> totalTokens` map for table display.
+ *
+ *   Why this exists:
+ *   - `token-stats.json` keeps convenience aggregates, but not the exact
+ *     provider+model sum needed for the new table column.
+ *   - `request-log.jsonl` is the source of truth because every proxied request
+ *     records prompt and completion token counts with provider context.
+ *   - Startup-only parsing keeps runtime overhead negligible during TUI redraws.
+ *
+ * @functions
+ *   → `buildProviderModelTokenKey` — creates a stable aggregation key
+ *   → `loadTokenUsageByProviderModel` — reads request-log.jsonl and returns total tokens by provider+model
+ *   → `formatTokenTotalCompact` — renders totals as integer K / M strings for narrow columns
+ *
+ * @exports buildProviderModelTokenKey, loadTokenUsageByProviderModel, formatTokenTotalCompact
+ *
+ * @see src/log-reader.js
+ * @see src/render-table.js
+ */
+
+import { loadRecentLogs } from './log-reader.js'
+
+// 📖 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 })
+  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
+
+    const key = buildProviderModelTokenKey(providerKey, modelId)
+    totals[key] = (totals[key] || 0) + tokens
+  }
+
+  return totals
+}
+
+// 📖 formatTokenTotalCompact keeps the new column narrow and scannable:
+// 📖 0-999 => raw integer, 1k-999k => Nk, 1m+ => NM, no decimals.
+export function formatTokenTotalCompact(totalTokens) {
+  const safeTotal = Number(totalTokens) || 0
+  if (safeTotal >= 1_000_000) return `${Math.floor(safeTotal / 1_000_000)}M`
+  if (safeTotal >= 1_000) return `${Math.floor(safeTotal / 1_000)}k`
+  return String(Math.floor(safeTotal))
+}