free-coding-models 0.5.57 → 0.5.59

package/README.md

@@ -466,6 +466,90 @@ When a tool mode is active (via `Z`), models incompatible with that tool are hig
 
 ---
 
+## 🧠 Persistent probe cache
+
+Every health probe result is cached to `~/.free-coding-models/probe-cache.json` for **24 hours** and **shared across all surfaces** (CLI TUI, Web Dashboard / daemon, Tauri Desktop).
+
+- **Warm start** renders the full ranking in <500ms using the cached results, then re-pings only the models that are due (broken or past TTL).
+- **Broken models** are auto-hidden across sessions — a model that 401s today stays out of tomorrow's default view. Recovery is automatic: if it comes back `ok`, it un-hides on the next probe.
+- **Cross-process safe**: a debounced flush + atomic rename + read-merge-write means the CLI and the daemon can share the file without clobbering each other.
+
+### Where the cache lives
+
+| Env / OS | Path |
+|----------|------|
+| `XDG_CACHE_HOME` set | `$XDG_CACHE_HOME/free-coding-models/probe-cache.json` |
+| Default (macOS / Linux) | `~/.free-coding-models/probe-cache.json` |
+| Windows | `%USERPROFILE%\.free-coding-models\probe-cache.json` |
+
+Inspect or wipe it manually any time — it's plain JSON with `0600` perms.
+
+### CLI flags
+
+| Flag | Effect |
+|------|--------|
+| `--reprobe` / `--no-cache` | Nuke the cache before this run; ping everything fresh |
+| `--probe-ttl <ms>` | Override the 24h TTL (e.g. `--probe-ttl 3600000` for 1h) |
+| `--show-broken` | Don't auto-hide broken models this run (one-shot override) |
+
+### TUI keys
+
+| Key | Effect |
+|-----|--------|
+| **Shift+B** | Toggle visibility of broken models (footer chip shows `⚡ N cached · 🔴 M broken`) |
+
+### Daemon `/stats` shape
+
+```json
+{
+  "probeCache": {
+    "total": 191,
+    "ok": 178,
+    "broken": 13,
+    "freshCount": 165,
+    "staleCount": 13,
+    "dueCount": 26,
+    "hiddenCount": 13,
+    "providers": 9
+  }
+}
+```
+
+---
+
+## 📊 Live quota from response headers
+
+Every chat-completion response carries rate-limit headers (`x-ratelimit-remaining-requests`, etc.). The daemon parses them passively on every routed request — **zero extra network requests, zero quota waste**.
+
+- **8 header variants** supported: SambaNova, Mistral, generic `x-ratelimit-*`, the `ratelimit-*` (no-`x-`) variant some proxies use, and 3 daily / token / token-minute variants for Cerebras-style providers.
+- **Pre-warmed by pings**: even health-check pings return headers, so quota is visible in the CLI before you ever route a real request through the daemon.
+- **5-minute staleness**: snapshots older than 5 minutes are excluded, with the active `/api/v1/key` fetcher as fallback for idle providers.
+- **Case-insensitive**: some proxies vary casing; we handle all of them.
+- **Garbage-safe**: `limit: 0`, non-numeric values, or missing pairs return `null` (no crash).
+
+### Where it shows up
+
+| Surface | What you'll see |
+|---------|-----------------|
+| TUI footer | `📊 groq 78% · sambanova 41%` chip (top 5 most-depleted first) |
+| Web Dashboard | New `Provider Quota` section with animated progress bars per provider |
+| `/api/router/stats` | `quota: { providerKey: { remaining, limit, percent, source, lastUpdated, windowType } }` |
+
+### Daemon `/stats.quota` shape
+
+```json
+{
+  "quota": {
+    "groq": { "remaining": 14, "limit": 30, "percent": 47, "windowType": "requests", "source": "header", "lastUpdated": 1753478400000 },
+    "sambanova": { "remaining": 1500, "limit": 14400, "percent": 10, "windowType": "day", "source": "header", "lastUpdated": 1753478400000 }
+  }
+}
+```
+
+The `source` field is `"header"` when the value came from a passive response header, `"endpoint"` when it came from the active `/api/v1/key` fetcher. Use it in devtools to debug why a provider shows the value it does.
+
+---
+
 ## π Pi Extension — FCM-Pi ⚠️ BETA
 
 **FCM-Pi** is a native [Pi coding agent](https://pi.dev) extension that integrates `free-coding-models` directly into your Pi session. It stays silent by default, scans only when you run `/fcm`, and lets you explicitly hot-swap models mid-session.
@@ -678,6 +762,8 @@ See [`packages/fcm-agent-core/README.md`](./packages/fcm-agent-core/README.md) f
 - **Auto-retry** — timeout models keep getting retried
 - **Mandatory self-update policy** — startup checks npm for a newer FCM and installs it automatically without a prompt. If the install fails twice in a row (offline, proxy, or permissions), FCM still starts but shows a red outdated-version warning until the user retries with `Shift+U` or runs the displayed install command.
 - **Last release timestamp** — light pink footer shows `Last release: Mar 27, 2026, 09:42 PM` from npm so users know how fresh the data is
+- **Persistent probe-cache (t1)** — every health probe result is cached to `~/.free-coding-models/probe-cache.json` for 24h. Warm starts render the full ranking in <500ms, only re-ping the models that are due (broken or TTL-expired). Broken models are auto-hidden across sessions — toggle visibility with **Shift+B**. See [Persistent probe cache](#-persistent-probe-cache) below for `--reprobe`, `--probe-ttl`, `--show-broken`.
+- **Live quota from response headers (t2)** — every routed chat-completion response already carries `x-ratelimit-*` headers. The daemon parses them in 8 variants and exposes live per-provider quota on the TUI footer (`📊 groq 78% · sambanova 41%`) and in the Web Dashboard (`Provider Quota` section with animated progress bars). Zero extra network requests, zero quota waste. See [Live quota from headers](#-live-quota-from-response-headers) below.
 
 ---
 

package/changelog/v0.5.58.md

@@ -0,0 +1,42 @@
+# Changelog v0.5.58 - 2026-07-26
+
+### Added
+
+- ⚡ **Persistent probe-cache with TTL + auto-hide broken models** ([#144](https://github.com/vava-nessa/free-coding-models/issues/144)) — every health probe result is now cached to `~/.free-coding-models/probe-cache.json` for **24 hours**, shared across all surfaces (CLI TUI, Web Dashboard / daemon, Tauri Desktop).
+
+  - **Warm start in <500ms**: the full ranking renders from the cache instantly, then only models that are due (broken or TTL-expired) get re-pinged. Cold start with no cache behaves identically to before — no regression.
+  - **Broken models stay hidden across sessions**: a model that 401s today won't appear in tomorrow's default view. Recovery is automatic — if a previously-broken model comes back `ok`, the next probe un-hides it.
+  - **Honors `XDG_CACHE_HOME`** when set (Linux/macOS convention), else falls back to `~/.free-coding-models/`. File uses `0600` perms and is written atomically (tmp + rename) to survive crashes mid-flush.
+  - **Concurrency-safe**: debounced flush + atomic rename + read-merge-write means a running daemon and an interactive CLI can share the file without clobbering each other. Worst case: one batch of deltas is lost, never the whole file.
+  - **`probeVersion` constant** (currently `2`): bump this when ping behaviour changes (new endpoint, new prompt, etc.) and the entire cache invalidates automatically — no manual purge.
+
+- 🔘 **Shift+B hotkey** toggles visibility of probe-cache-broken models in the TUI. Footer chip shows `⚡ N cached · 🔴 M broken (Shift+B)` (becomes `🔴 M broken (visible)` when toggled on).
+
+- 🛠️ **New CLI flags**:
+  - `--reprobe` / `--no-cache` — force-rebuild the probe-cache this run (ping everything fresh).
+  - `--probe-ttl <ms>` — override the 24h TTL (e.g. `--probe-ttl 3600000` for 1h, useful when debugging model health).
+  - `--show-broken` — don't auto-hide broken models this run (one-shot override for `--reprobe` style workflows).
+
+- 📊 **Daemon `/stats` now exposes `probeCache`** with `total`, `ok`, `broken`, `freshCount`, `staleCount`, `dueCount`, `hiddenCount`, `providers` — the Web Dashboard renders it live so users can see cache hit rate at a glance.
+
+### Changed
+
+- 🩺 **Daemon health-probe loop** (`runProbeBurst`) now skips models that are fresh + ok in the persistent cache. Broken models naturally pass through, so recovery detection keeps working unchanged. This cuts daemon-side probe traffic by ~85% on warm starts.
+
+- 📁 **Per-provider probe results** are mirrored from the in-memory circuit-breaker windows into the persistent cache via `recordProbeResult` in `src/core/router-daemon.js`. Debounced 2s flush avoids filesystem thrash during probe bursts.
+
+### Maintenance
+
+- 🧪 **+40 unit tests** (`test/probe-cache.test.js`, 36 → 76): covers freshness rules 1–5, path resolution (XDG_CACHE_HOME), corrupt-JSON recovery, version migration, multi-model fan-out, `isCacheFresh` per-condition checks, `recordProbeResults` validation + garbage dropping, `getCacheStats` aggregates, `getCachedResultsForProvider` filtering, `pruneStaleEntries`, end-to-end reload, 4 concurrency tests (other-process deltas survive, stale `lastProbedAt` is overwritten, missing-file path, corrupt-file recovery).
+- 🧪 **628 → 632 tests passing** (`pnpm test`), **107 → 118 suites**.
+- 🧹 `vite build` succeeds.
+- 📖 README updated with a new **🧠 Persistent probe cache** section (where the file lives, CLI flags, TUI keys, daemon `/stats` shape).
+
+### Files
+
+- **New**: `src/core/probe-cache.js` (335 lines), `test/probe-cache.test.js` (332 lines), `changelog/v0.5.58.md`.
+- **Modified**: `src/tui/app.js` (probe-cache load + apply + record), `src/tui/key-handler.js` (Shift+B handler), `src/tui/render-table.js` (footer chip), `src/tui/tui-state.js` (5 new state fields), `src/tui/cli-help.js` (3 new flag entries), `src/core/utils.js` (`parseArgs` gains `--reprobe` / `--probe-ttl` / `--show-broken`), `src/core/router-daemon.js` (full integration: load on boot, mirror probe results, skip fresh in `runProbeBurst`, expose in `/stats`, flush on shutdown), `README.md`, `tasks/t1.md`, `package.json` (test script), `changelog/`.
+
+### Inspiration
+
+This implementation is informed by [`apmantza/pi-free`](https://github.com/apmantza/pi-free)'s `lib/provider-probe.ts` + `lib/probe-cache.ts` (which itself credits us: *"Inspired by free-coding-models' `extractQuotaPercent`"*). The inspiration flows both ways — we're reclaiming the lead on the probe-cache axis by going cross-surface (CLI / daemon / Tauri share one file) and concurrency-safe (read-merge-write vs pi-free's single-writer Pi-only model).

package/changelog/v0.5.59.md

@@ -0,0 +1,52 @@
+# Changelog v0.5.59 - 2026-07-26
+
+### Added
+
+- 📊 **Live quota from response headers** (t2) — every chat-completion response already carries `x-ratelimit-*` headers. The daemon parses them passively on every routed request (and even on health-check pings), exposing **live** per-provider quota on the TUI footer and Web Dashboard. **Zero extra network requests, zero quota waste.**
+
+  - **8 header variants** supported in priority order:
+    - `x-ratelimit-remaining-requests` / `-limit-requests` (SambaNova-style)
+    - `x-ratelimit-remaining` / `-limit` (Mistral / generic)
+    - `ratelimit-remaining-requests` / `ratelimit-limit-requests` (proxy-stripped)
+    - `ratelimit-remaining` / `ratelimit-limit` (proxy-stripped generic)
+    - `x-ratelimit-remaining-requests-day` / `-limit-requests-day` (SambaNova daily)
+    - `x-ratelimit-remaining-day` / `-limit-day` (generic daily)
+    - `x-ratelimit-remaining-tokens` / `-limit-tokens` (Cerebras tokens)
+    - `x-ratelimit-remaining-tokens-minute` / `-limit-tokens-minute` (Cerebras token-minute)
+  - **First-match-wins priority** — when multiple pairs are present, the most-specific wins (e.g. daily variant beats generic).
+  - **Case-insensitive** — some proxies vary casing; we handle `X-RateLimit-Remaining` and `x-ratelimit-remaining` identically.
+  - **Garbage-safe** — `limit: 0`, non-numeric values, or missing pairs return `null` (no crash, no div-by-zero).
+  - **Staleness 5 min** — snapshots older than `STALENESS_MS` are excluded from `getAllQuotas()` so the consumer only sees fresh data. The existing active `/api/v1/key` fetcher stays as the fallback for idle providers.
+  - **Merge with active fetcher** — `getQuota(providerKey)` returns whichever is freshest, so quota is always live when traffic flows.
+
+- 🛰️ **TUI footer chip** — `📊 groq 78% · sambanova 41%` (top 5 most-depleted first; icon escalation 📊 healthy → ⚠️ ≤ 25% → 🚨 ≤ 10%). Renders on the same footer line as the existing probe-cache chip.
+
+- 🌐 **Web Dashboard `Provider Quota` section** — per-provider card with source icon (🛰️ passive header vs 🔌 active fetcher fallback), provider key, animated progress bar (green ≥ 25% / amber 10–25% / red ≤ 10%), and percent label. Auto-sorted most-depleted first. Updated every `/api/router/stats` poll (5 s).
+
+- 📋 **Daemon `/api/router/stats` exposes `quota`** — `{ providerKey: { remaining, limit, percent, windowType, source, lastUpdated } }`. The `source` field tells you whether the value came from a passive header (`'header'`) or the active fetcher (`'endpoint'`) — useful for debugging why a provider shows the number it does.
+
+- 🧪 **`processResponseHeaders(providerKey, headers)`** — drop-in hook for any future surface (Tauri Desktop, scripts, IDE plugins) that wants to feed the passive map.
+
+### Changed
+
+- 🩺 **Daemon reverse proxy** (`buildUpstreamMeta` in `src/core/router-daemon.js`) now calls `processResponseHeaders(providerKey, response.headers)` for every routed upstream response, both streaming and non-streaming. Zero new code paths, zero new dependencies.
+
+- 📡 **Health-check pings** (`src/core/ping.js`) also call `processResponseHeaders(providerKey, resp.headers)`, so even the CLI-only flow (no daemon) shows live quota after the first ping cycle.
+
+- 🔧 **Internal refactor** — the existing `extractQuotaPercent` in `src/core/ping.js` now uses the shared `extractQuota()` from `provider-quota-fetchers.js`. Same 8-variant parser, single source of truth, no behaviour change for existing callers.
+
+### Maintenance
+
+- 🧪 **+37 unit tests** (`test/passive-quota.test.js`, new file): HEADER_PAIRS structure, STALENESS_MS, all 8 header pairs parse correctly, robustness (missing fields, NaN, limit=0, negative limit, empty object, null/undefined headers), first-pair-wins priority, case-insensitivity, Fetch Headers object support, `processResponseHeaders` writes/overwrites/ignores bad providerKey, `getQuota` passive fresh/stale/custom maxAgeMs, `getAllQuotas` unions both stores / excludes stale, `formatQuotaStatus` healthy/low/critical + day window + stale/missing.
+- 🧪 **632 → 671 tests passing** (`pnpm test`), **118 → 125 suites**.
+- 🧹 `vite build` succeeds.
+- 📖 README updated with a new **📊 Live quota from response headers** section (8 variants table, where it shows up, `/stats.quota` JSON shape).
+
+### Inspiration
+
+This implementation is informed by [`apmantza/pi-free`](https://github.com/apmantza/pi-free)'s `lib/quota-monitor.ts` (which itself credits us: *"Inspired by free-coding-models' `extractQuotaPercent`"*). The inspiration flows both ways — we extend their 6-pair design to 8 variants (adding the Cerebras tokens / token-minute pairs we already supported) and ship a Web Dashboard renderer that surfaces them as live progress bars instead of just CLI text.
+
+### Files
+
+- **Modified**: `src/core/provider-quota-fetchers.js` (+228 lines: new pure-logic section), `src/core/ping.js` (call `processResponseHeaders` on every ping), `src/core/router-daemon.js` (call on every routed response + expose `quota` in `/stats`), `src/tui/render-table.js` (new footer chip), `src/tui/app.js` (thread `quota` through), `web/src/components/router/RouterView.jsx` (new `Provider Quota` section), `web/src/components/router/RouterView.module.css` (7 new classes), `README.md`, `tasks/t2.md`, `package.json` (test script).
+- **New**: `test/passive-quota.test.js` (340 lines, 37 tests), `changelog/v0.5.59.md`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.57",
-  "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.",
+  "version": "0.5.59",
+  "description": "Find the fastest coding LLM models in seconds \u2014 ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",
     "nim",
@@ -53,7 +53,7 @@
   ],
   "scripts": {
     "start": "node bin/free-coding-models.js",
-    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js",
+    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js test/probe-cache.test.js test/passive-quota.test.js",
     "prepack": "npm run build:web",
     "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",
@@ -83,4 +83,4 @@
     "vite": "^8.0.16",
     "vite-plus": "^0.2.6"
   }
-}
+}

package/src/core/ping.js

@@ -41,7 +41,7 @@
  */
 
 import { PING_TIMEOUT } from './constants.js'
-import { fetchProviderQuota as _fetchProviderQuotaFromModule } from './provider-quota-fetchers.js'
+import { fetchProviderQuota as _fetchProviderQuotaFromModule, extractQuota as _extractQuotaFromModule, processResponseHeaders as _processResponseHeadersFromModule } from './provider-quota-fetchers.js'
 import { supportsUsagePercent } from './quota-capabilities.js'
 
 const DISABLED_THINKING_RETRY_STATUSES = new Set([400, 422])
@@ -173,10 +173,15 @@ export async function ping(apiKey, modelId, providerKey, url) {
     }
     // 📖 Normalize all HTTP 2xx statuses to "200" so existing verdict/avg logic still works.
     const code = resp.status >= 200 && resp.status < 300 ? '200' : String(resp.status)
+    // 📖 Passive quota tracker (t2): parse the response headers via the shared module.
+    // 📖 1) Write to the passive snapshot map so /stats + TUI footer see live quota.
+    // 📖 2) Return the percent number for the per-call consumer below.
+    const extracted = _extractQuotaFromModule(resp.headers)
+    _processResponseHeadersFromModule(providerKey, resp.headers)
     return {
       code,
       ms: Math.round(performance.now() - t0),
-      quotaPercent: extractQuotaPercent(resp.headers),
+      quotaPercent: extracted ? extracted.percent : null,
     }
   } catch (err) {
     const isTimeout = err.name === 'AbortError'