free-coding-models 0.5.36 → 0.5.37

package/changelog/v0.5.37.md

@@ -0,0 +1,14 @@
+# Changelog v0.5.37 - 2026-06-20
+
+### Changed
+- **Router `score` is now a pure latency+uptime composite (issue #120 hardening).** Previously the routing score was `0.4*latency + 0.4*uptime + 0.2*priorityBonus` — mixing explicit priority into the score could mislead tiebreakers and dashboards, because the routing comparator in `getRoutingCandidates` already enforces priority authoritatively. `scoreCandidates()` now exposes `score = 0.5*latency + 0.5*uptime` (pure model quality, normalized to `[0, 1]`), and `priorityBonus` is kept as a separate field for back-compat dashboards and legacy UIs. The remaining `latencyWeight` / `uptimeWeight` were rebalanced to `0.5 / 0.5` so the score stays in `[0, 1]` after priority is removed. Applies uniformly to CLI, Web Dashboard, and Desktop surfaces because the change lives in shared core (`src/core/router-daemon.js` + `src/core/config.js`).
+
+### Fixed
+- **HALF_OPEN recovery is now respected by the priority-first comparator (issue #120 regression test).** The v0.5.36 fix changed `getRoutingCandidates` to sort by explicit priority before circuit state, but had no test for the exact scenario from the issue screenshot: a high-priority model sitting in `HALF_OPEN` recovery vs. a lower-priority `CLOSED` model. Added a regression test that pins `runtime.circuit.get(key).state = 'HALF_OPEN'` for priority `#1` while priority `#5` stays `CLOSED`, then verifies both `/stats.routingOrder[0]` and the actual chat-completions response target the HALF_OPEN priority-#1 model — locking in the fix so it can't silently regress.
+- **Score tiebreaker is deterministic when two models share the same priority (issue #120 regression test).** Added a second regression test that puts two models at the same explicit priority (rare but reachable via direct API or auto-heal) with deliberately asymmetric probe data — fast groq (80 ms) vs. slow nvidia (2000 ms) — and verifies that the higher-score model wins `routingOrder[0]`. This locks in the new pure-latency+uptime score as the deterministic tiebreaker for same-priority same-state candidates, preventing future regressions where Map iteration order or stale priority data could leak back into routing.
+
+### Docs
+- **`DEFAULT_ROUTER_SETTINGS.scoring.priorityWeight` marked as preserved-for-back-compat.** The field still round-trips through `normalizeRouterScoring()` so user configs that customize it are not silently dropped on next save, but it is now ignored by the runtime `scoreCandidates()`. Will be removed in a future major bump. Comment block in `src/core/config.js` documents the rationale.
+
+### Tests
+- **+2 new tests for issue #120** (`test/test.js`, `router daemon integration hardening` suite): `keeps a higher-priority HALF_OPEN model above a lower-priority CLOSED one` and `breaks score ties deterministically by latency/uptime, not priority`. Test count moves from 540 → 542, all passing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.36",
+  "version": "0.5.37",
   "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",

package/src/core/config.js

@@ -167,8 +167,15 @@ export const DEFAULT_ROUTER_SETTINGS = Object.freeze({
     requestTimeoutMs: 15000,
   }),
   scoring: Object.freeze({
-    latencyWeight: 0.4,
-    uptimeWeight: 0.4,
+    latencyWeight: 0.5,
+    uptimeWeight: 0.5,
+    // 📖 priorityWeight is preserved for back-compat with user configs that
+    // 📖 set a custom value, but is no longer mixed into the routing score
+    // 📖 (issue #120 fix, v0.5.37). Priority is now enforced authoritatively
+    // 📖 by the comparator in getRoutingCandidates; folding it into score
+    // 📖 could only mislead tiebreakers and dashboards. The remaining
+    // 📖 latency+uptime weights are rebalanced to 0.5/0.5 so the score stays
+    // 📖 in [0, 1] after priority is removed (previously 0.4/0.4/0.2).
     priorityWeight: 0.2,
   }),
   logLevel: 'info',
@@ -377,6 +384,10 @@ function normalizeRouterScoring(scoring) {
     const numeric = Number(value)
     return Number.isFinite(numeric) && numeric >= 0 ? numeric : fallback
   }
+  // 📖 priorityWeight is normalized but currently IGNORED by the runtime
+  // 📖 scoreCandidates() (issue #120, v0.5.37). Kept here so existing user
+  // 📖 configs that customize this field round-trip cleanly and don't lose
+  // 📖 their setting on next save. Will be removed in a future major bump.
   return {
     latencyWeight: numberOrDefault(safeScoring.latencyWeight, DEFAULT_ROUTER_SETTINGS.scoring.latencyWeight),
     uptimeWeight: numberOrDefault(safeScoring.uptimeWeight, DEFAULT_ROUTER_SETTINGS.scoring.uptimeWeight),

package/src/core/router-daemon.js

@@ -1149,15 +1149,27 @@ class RouterRuntime {
       const hasData = stats.total > 0
       const latencyScore = stats.p95 === null ? 0.5 : Math.max(0, 1 - (stats.p95 / maxP95))
       const uptimeScore = stats.uptime === null ? 0.5 : stats.uptime
+      // 📖 priorityBonus - kept as a separate field for dashboards/legacy UIs
+      // 📖 that previously rendered a single composite "score". Priority is
+      // 📖 NOT folded into `score` anymore (issue #120): the routing comparator
+      // 📖 in getRoutingCandidates sorts by explicit priority authoritatively,
+      // 📖 so mixing priority into the score only confused tiebreakers.
       const priorityBonus = 1 - ((entry.priority - 1) / setSize)
+      // 📖 score - pure latency+uptime composite. Used only as the FINAL
+      // 📖 tiebreaker between candidates that share the same priority AND
+      // 📖 same circuit state (see getRoutingCandidates). A model with no
+      // 📖 probe data yet scores neutral (0.5) - we deliberately do NOT use
+      // 📖 priorityBonus as a cold-start fallback, because that would re-
+      // 📖 introduce the priority-in-score confusion this refactor removes.
       const score = hasData
-        ? (weights.latencyWeight * latencyScore) + (weights.uptimeWeight * uptimeScore) + (weights.priorityWeight * priorityBonus)
-        : priorityBonus
+        ? (weights.latencyWeight * latencyScore) + (weights.uptimeWeight * uptimeScore)
+        : 0.5
       const state = this.updateCircuitForCooldown(key) || {}
       return {
         ...entry,
         key,
         score,
+        priorityBonus,
         stats,
         circuit: state,
         catalog: this.modelCatalog.get(key) || null,