free-coding-models 0.5.56 → 0.5.58

package/README.md

@@ -466,6 +466,57 @@ 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
+  }
+}
+```
+
+---
+
 ## π 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 +729,7 @@ 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`.
 
 ---
 

package/changelog/v0.5.57.md

@@ -0,0 +1,20 @@
+# Changelog v0.5.57 - 2026-07-25
+
+### Fixed
+- 📦 **`patch-openclaw.js` now finds `sources.js` in more locations** ([#35](https://github.com/vava-nessa/free-coding-models/issues/35)) — when users copy just `patch-openclaw.js` to another directory (e.g. `~/.free-coding-models/`) and run it, the static `import './sources.js'` failed with `ERR_MODULE_NOT_FOUND` because ESM resolves imports relative to the importer file at parse time. Switched to a runtime search over multiple candidate paths:
+
+  1. Same directory as the script (primary — FCM source / global install layout)
+  2. Parent directory (covers `tools/`-style subdirs)
+  3. Two levels up
+  4. Three levels up
+  5. `process.cwd()` (last-resort fallback)
+
+  If none resolve, the script now prints a clear error pointing to the script's actual location and how to fix it, instead of a cryptic `ERR_MODULE_NOT_FOUND`.
+
+### Maintenance
+- 🧪 **+1 unit test** (`test/patch-openclaw.test.js`) locking in the search order so any future reordering is caught.
+- 🧪 **592/592 tests pass** (`pnpm test`).
+- 🧹 `vite build` succeeds.
+
+### Why a top-level `await import()`?
+ESM `import './sources.js'` is resolved at parse-time relative to the importer file's directory. There's no way to fall back at parse time, so the only way to support multiple candidate paths is to compute the path at runtime and use dynamic `import(pathToFileURL(sourcesPath).href)`. Top-level `await` keeps the rest of the script's top-level statements unchanged.

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.56",
-  "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.58",
+  "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",
     "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/patch-openclaw.js

@@ -9,8 +9,39 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs'
 import { homedir } from 'os'
-import { join } from 'path'
-import { nvidiaNim } from './sources.js'
+import { join, dirname } from 'path'
+import { fileURLToPath, pathToFileURL } from 'url'
+
+// 📖 Issue #35: when users copy just patch-openclaw.js to another directory
+// 📖 (e.g. ~/.free-coding-models/) and try to run it, the relative import of
+// 📖 sources.js fails with ERR_MODULE_NOT_FOUND. Look up the tree + check CWD
+// 📖 before giving up with a helpful message.
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+
+function findSourcesPath() {
+  const candidates = [
+    join(SCRIPT_DIR, 'sources.js'),
+    join(SCRIPT_DIR, '..', 'sources.js'),
+    join(SCRIPT_DIR, '..', '..', 'sources.js'),
+    join(SCRIPT_DIR, '..', '..', '..', 'sources.js'),
+    join(process.cwd(), 'sources.js'),
+  ]
+  for (const p of candidates) {
+    if (existsSync(p)) return p
+  }
+  return null
+}
+
+const sourcesPath = findSourcesPath()
+if (!sourcesPath) {
+  console.error('  ✖ Could not locate sources.js next to this script.')
+  console.error(`    Script location: ${SCRIPT_DIR}`)
+  console.error('    Make sure sources.js is in the same directory as patch-openclaw.js,')
+  console.error('    or run this from the free-coding-models repo root.')
+  process.exit(1)
+}
+
+const { nvidiaNim } = await import(pathToFileURL(sourcesPath).href)
 
 const MODELS_JSON = join(homedir(), '.openclaw', 'agents', 'main', 'agent', 'models.json')
 const OPENCLAW_JSON = join(homedir(), '.openclaw', 'openclaw.json')