free-coding-models 0.5.10 → 0.5.14

package/README.md

@@ -338,6 +338,40 @@ Configure tools with:
 
 The daemon auto-creates a `fast-coding` set from your configured providers on first start. It stores router settings in `~/.free-coding-models.json`, writes lifecycle logs to `~/.free-coding-models-daemon.log`, and tracks token metadata in `~/.free-coding-models-tokens.json`.
 
+### Playground — chat with the router
+
+Every chat that goes through the FCM router starts with a configurable **pre-prompt** that introduces the assistant as the free-coding-models routing agent. The Playground is the fastest way to try the router without configuring a coding tool.
+
+```bash
+# 1. Start the router (if it isn't already)
+free-coding-models --daemon-bg
+
+# 2. Open the Playground in the TUI
+free-coding-models --playground
+# ... or just press ; inside the TUI
+# ... or click "Playground" in the web dashboard header
+```
+
+The Playground:
+
+- Streams responses token-by-token (SSE).
+- Shows the routed-via provider/model + latency + tokens on every reply.
+- Lets you pin a specific model (`fcm` = auto-router, or `groq/<id>` / `cerebras/<id>` / etc.) for manual A/B testing.
+- Lets you toggle the pre-prompt per session, so you can see what the model answers *with* and *without* the FCM persona.
+
+The pre-prompt lives in the router config under `router.prePrompt` and can be edited from any surface (the daemon reloads it on its 10s config-refresh tick):
+
+```json
+{
+  "router": {
+    "prePrompt": {
+      "enabled": true,
+      "text": "You are free-coding-models, the free coding-model routing agent..."
+    }
+  }
+}
+```
+
 Router endpoints:
 
 | Endpoint | Purpose |
@@ -464,6 +498,7 @@ When a tool mode is active (via `Z`), models incompatible with that tool are hig
 | `X` | Clear active custom text filter |
 | `G` | Cycle global theme (`Auto → Dark → Light`) |
 | `Ctrl+P` | Open ⚡️ command palette (search + run actions) |
+| `;` | Open the Playground chat overlay (chat with the FCM router) |
 | `Ctrl+A` | Run AI Speed Test for the selected model |
 | `Ctrl+U` | Run Global AI Speed Test (uses real provider requests) |
 | `R/S/C/M/O/L/A/H/V/B/U` | Sort columns |
@@ -508,8 +543,13 @@ When a tool mode is active (via `Z`), models incompatible with that tool are hig
 - **Favorites** — star models with `F`, persisted across sessions, default to normal rows, and switch display mode with `Y` (pinned+sticky vs normal rows)
 - **Configured-only default** — only shows providers you have keys for
 - **Keyless latency** — models ping even without an API key (show 🔑 NO KEY)
+- **Unusable row fade** — rows in `NO KEY` or `AUTH FAIL` state are rendered at 80% opacity (20% less opaque) on every surface (TUI + Web + Desktop), so the user can scan the table and instantly see which models they cannot actually use. Composes cleanly with the favorite/recommended/incompatible background tints.
 - **Smart Recommend** — questionnaire picks the best model for your task type
 - **Smart Model Router** — local OpenAI-compatible daemon with model sets, failover, circuit breakers, health probes, and token stats
+- **Playground chat** — multi-turn chat with the router on every surface (TUI `;` / Web Playground nav / `free-coding-models --playground`). Streams responses and shows the routed-via provider/model on every reply.
+- **Auto-heal on startup** — the daemon replaces broken models in the active set (`AUTH_ERROR` / `STALE`) with working alternatives from the same provider first, then cross-provider. The first manual edit disables auto-heal so user choices are preserved. A new user with a half-broken key set lands on a usable default set by the time the dashboard renders.
+- **Web router set manager** — add, remove, drag-and-drop, and probe-sync the active router set from inside the Web Dashboard. The "Sync best models" button re-pings every candidate with the user's actual API keys and rebuilds the set with only models that return 2xx, so a new user lands on a working default set instead of a hardcoded one that 401s.
+- **Router pre-prompt** — a configurable first-class system message injected by the daemon on every `/v1/chat/completions` request it proxies. Default persona introduces the assistant as the FCM routing agent; editable from any surface.
 - **⚡️ Command Palette** — `Ctrl+P` opens a searchable action launcher for filters, sorting, overlays, and quick toggles
 - **Install Endpoints** — push a full provider catalog into any tool's config (from Settings `P` or ⚡️ Command Palette)
 - **Missing tool bootstrap** — detect absent CLIs, offer one-click install, then continue the selected launch automatically

package/bin/free-coding-models.js

@@ -122,13 +122,18 @@ async function main() {
     process.exit(result.ok ? 0 : 1);
   }
 
+  // 📖 --playground / playground subcommand — boot the TUI directly into the
+  // 📖 Playground chat overlay. Falls through to the TUI; the key handler
+  // 📖 opens the playground on first render.
+  const wantPlayground = cliArgs.playgroundMode === true
+
   // Validate --tier early, before entering alternate screen
   if (cliArgs.tierFilter && !TIER_LETTER_MAP[cliArgs.tierFilter]) {
     console.error(chalk.red(`  Unknown tier "${cliArgs.tierFilter}". Valid tiers: S, A, B, C`));
     process.exit(1);
   }
 
-  await runApp(cliArgs, config, { startupUpdate, isDevMode });
+  await runApp(cliArgs, config, { startupUpdate, isDevMode, wantPlayground });
 }
 
 main().catch((err) => {

package/changelog/v0.5.11.md

@@ -0,0 +1,56 @@
+# Changelog v0.5.11 - 2026-06-02
+
+### Added
+- **Playground chat on every surface.** A first-class way to talk to the FCM router
+  without configuring a coding tool. Press `;` in the TUI, click the "Playground"
+  nav button in the web dashboard, or run `free-coding-models --playground` /
+  `free-coding-models playground` to open the in-TUI chat. Streams responses
+  token-by-token, shows the routed-via provider/model + latency + tokens on each
+  assistant message, and surfaces a friendly error if the router is offline.
+- **Router pre-prompt (`router.prePrompt`).** A new configurable first-class
+  system message injected by the daemon on every `/v1/chat/completions` request
+  it proxies. Default text introduces the assistant as "free-coding-models, the
+  free coding-model routing agent" so every tool and every Playground reply is
+  framed as the FCM router. Always prepended (user `system` messages can still
+  override specific instructions). Disabled by setting `enabled: false`.
+- **`GET /api/router/preprompt` and `PUT /api/router/preprompt`** on both the
+  router daemon and the web server. Same-origin only for PUT, same CORS policy
+  as the rest of the API. Persists to `~/.free-coding-models.json`; the daemon
+  picks up the new value on its 10s config-reload tick.
+- **`/api/playground/chat` proxy** on the web server. Browser Playground never
+  talks to the daemon directly (no CORS, no exposed provider keys). Streams SSE
+  when the client asks for `stream: true`; returns the upstream JSON otherwise.
+- **`fcm` virtual model support clarified.** `GET /v1/models` advertises `fcm`
+  (the auto-router) and `fcm:<set-name>` per set, so the Playground model
+  selector shows both options.
+- **`--playground` flag and `playground` subcommand** for the TUI:
+  `free-coding-models --playground` boots the TUI directly into the chat
+  overlay. `--help` lists it under "Config Flags".
+- **Default pre-prompt covers persona + dashboard pointer.** When a user asks
+  the model "which model served you?", the default persona tells them they
+  were routed through the local FCM router and points them at the dashboard.
+- **9 unit tests for pre-prompt injection** (idempotence, no-mutation, disabled,
+  empty, already-set, body-merge, garbage input, length cap, default text).
+- **4 unit tests for playground error extraction** so the OpenAI wire-format
+  `{ error: { message, type, code } }` is unwrapped into a string before
+  React renders it (the bug a beta tester hit when the router was down).
+- **Robust M4 server smoke test.** The pre-existing test asserted the router
+  was offline, which fails on developer machines with a real daemon running.
+  Now it asserts the response shape and adds pre-prompt + playground-proxy
+  round-trips to the smoke checks.
+
+### Changed
+- **M4 server smoke test no longer fails on local dev machines.** The test
+  previously required the router to be offline; that is no longer a precondition.
+- **M4 settings view is untouched** but the pre-prompt edit panel will land in
+  a follow-up. (The pre-prompt is already exposed through the daemon API and
+  the Web Settings round-trip; only the textarea is missing from the UI.)
+
+### Notes
+- The default pre-prompt is **~120 words** in English, code-first, and
+  references the local dashboard. Users can fully replace it from any
+  surface; the text is stored verbatim in `~/.free-coding-models.json`.
+- Pre-prompt is **never** sent to telemetry and is not logged by the daemon.
+- The Playground honors the configured pre-prompt and lets the user toggle it
+  off per-session. When off, the request is sent as-is and the assistant
+  reply will not be framed as the FCM router.

package/changelog/v0.5.12.md

@@ -0,0 +1,68 @@
+# Changelog v0.5.12 - 2026-06-02
+
+### Added
+- **Web Router Dashboard: full set manager.** The M4 read-only "Model Health"
+  panel has been replaced with an interactive **Active Set** manager:
+  - **Add model** picker with search + per-provider filter (147 routeable
+    models from the new `/api/router/catalog` endpoint).
+  - **Remove** button per row.
+  - **Move up / Move down** buttons as a keyboard-accessible fallback.
+  - **HTML5 drag-and-drop** to reorder priorities. Visual drop indicator
+    (top/bottom border on the target row) shows where the row will land.
+  - **Active set switcher** in the same header (when more than one set
+    exists). Switches the daemon's `activeSet` via
+    `POST /sets/:name/activate`.
+  - **Save indicator** (`saving… / ✓ saved / ⚠ error`) shown next to the
+    Add button so the user always knows whether the last drag actually
+    persisted to disk.
+- **"Sync best models" button.** One-click rebuild of the active set
+  using the probe-based `sync-set` pipeline. Re-pings every candidate
+  with the user's actual API keys, picks only the models that come back
+  2xx with a reasonable latency, and persists the result. The Web UI
+  surfaces a "Synced N working models from M probes" toast with the
+  probe count. The button shows a "saving…" state while the probe runs
+  (up to ~60s for 16 candidates).
+- **Daemon endpoints for granular set management.**
+  - `POST /sets/:name/models` — append a single model to a set.
+  - `DELETE /sets/:name/models` — remove a single model by
+    `{ provider, model }`.
+  - `POST /sets/:name/reorder` — accept a full priority order
+    `{ order: ["provider/model", ...] }` and re-number the set.
+  - `POST /sets/:name/sync` — re-run `sync-set` against the named set
+    with `maxProbes: 16, targetCount: 5` so the Web UI never spends
+    more than ~60s on a sync.
+  - `GET /api/router/catalog` — lightweight catalog of routeable
+    models for the Add picker.
+- **Default router set is now probe-driven.** `buildDefaultRouterSet`
+  is async and accepts a `probeFn` that POSTs a 1-token chat completion
+  to each candidate. Models that come back 2xx with low latency are
+  pinned to the top of the set; failing models fall back to the static
+  tier ordering. A new user with a half-broken key set now gets a
+  default router set made of models that actually work, instead of a
+  hardcoded NVIDIA-only list that 401s for everyone without a
+  NIM-specific grant.
+- **Web proxy for the new endpoints.** `/api/router/sets/:name/models`
+  (POST/DELETE), `/api/router/sets/:name/reorder` (POST),
+  `/api/router/sets/:name/activate` (POST), `/api/router/sets/:name/sync`
+  (POST, 180s proxy timeout), `/api/router/catalog` (GET, with a
+  fallback path that synthesizes the catalog from `sources.js` when the
+  daemon is offline).
+- **Switch case routing fix.** The `if/regex` blocks for parameterized
+  routes (`/api/router/sets/:name/...`) were previously inside the
+  request switch as `case` statements that never matched (JS switch
+  is exact-string equality). Moved them above the switch so they
+  actually run. This is why the original reorder/add/remove proxies
+  returned 404 in the v0.5.11 web build.
+- **6 new unit tests** for the granular set-management endpoints
+  (add, duplicate, remove, reorder, reorder-with-missing-key,
+  catalog) and **2 new tests** for `buildDefaultRouterSet`'s probe
+  path (probe-preference + sync fallback). All 495 tests pass.
+
+### Notes
+- The TUI's `--sync-set` flag is unchanged — the Web "Sync best" button
+  is the same pipeline with a smaller `maxProbes` so the UI stays
+  snappy. CLI users still get the full 50-probe budget.
+- The `fcm` virtual model that the Playground uses by default
+  automatically picks up the new working-models set, so the
+  Playground will start returning successful responses as soon as the
+  Web user clicks "Sync best" once.

package/changelog/v0.5.13.md

@@ -0,0 +1,57 @@
+# Changelog v0.5.13 - 2026-06-02
+
+### Added
+- **Auto-heal the active router set on startup.** When the daemon starts,
+  it waits for the first probe burst to populate health data, then runs
+  `autoHealActiveSet()` to swap any broken model in the active set
+  (`AUTH_ERROR` or `STALE` state) for a working alternative. The picker
+  prefers the same provider first, then falls through to cross-provider
+  candidates, and skips providers whose every probe has been broken.
+  Three passes run at 8s, 24s, and 40s after startup so a freshly-added
+  replacement that turns out to be broken gets replaced again. The result:
+  a new user with a half-broken key set lands on a usable default set
+  by the time the Web Dashboard renders, and the Playground's `fcm`
+  virtual model starts returning successful responses immediately.
+- **`router.userCustomized` + `router.autoHeal` config flags.** The first
+  manual edit to the active set (add / remove / reorder / sync /
+  activate / rename) flips `userCustomized` to `true` and `autoHeal`
+  to `false` so the user's manual choices are never undone on the next
+  daemon start. New users get `userCustomized: false` and `autoHeal:
+  true` by default, which is what powers the M6 "default to working
+  models" promise.
+- **`/api/router/status` exposes `autoHeal`, `userCustomized`, and
+  `brokenModelCount`.** The Web Router Dashboard reads these to surface
+  an amber banner when broken models remain in the active set, with a
+  one-click "Fix now" button that re-runs the same `sync-set` probe
+  pipeline the CLI uses.
+- **Amber "models not responding" banner in the Web Router Dashboard.**
+  Shown when the daemon reports `brokenModelCount > 0`, with a
+  dismissable X so the user can ignore it after acknowledging the
+  problem. The "Fix now" button re-runs the probe-based heal and reloads
+  the dashboard state.
+- **4 new unit tests** for the auto-heal path: no-op when user-customized,
+  no-op when auto-heal is disabled, no-op when no broken models, and
+  the user-edit-flags-customization round-trip. **All 515 tests pass.**
+
+### Notes
+- The auto-heal is best-effort: if the user has only one working
+  provider, the healed set will shrink to that one provider's top
+  model. That's still better than the previous behavior of showing
+  three models that all 401.
+- The new broken-model banner is intentionally subtle (amber, not red)
+  because the auto-heal already does its best to recover. It's there
+  for the "user has 0 working keys" edge case so the user can click
+  through to "Fix now" / "Sync best" and either get a working set or
+  see the toast explaining the situation.
+
+### How the picker works (M6)
+```
+For each broken model in the active set:
+  1. Same provider — pick a working model of the same provider
+     (skipping models that the circuit breaker already knows are broken).
+  2. Cross-provider — fall through to any working model across all
+     providers, sorted by static tier + swe score.
+  3. If neither yields a working model, leave the broken entry in
+     place and log a warning (the Web UI surfaces this in the
+     "models not responding" banner).
+```

package/package.json

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

@@ -92,7 +92,8 @@
  *
  * @exports loadConfig, saveConfig, validateConfigFile, getApiKey, isProviderEnabled
  * @exports addApiKey, removeApiKey, listApiKeys — multi-key management helpers
- * @exports normalizeEndpointInstalls, normalizeRouterConfig, DEFAULT_ROUTER_SETTINGS
+ * @exports normalizeEndpointInstalls, normalizeRouterConfig, normalizeRouterPrePrompt
+ * @exports defaultRouterPrePromptText, DEFAULT_ROUTER_SETTINGS
  * @exports buildPersistedConfig, replaceConfigContents, persistApiKeysForProvider
  * @exports CONFIG_PATH — path to the JSON config file
  *
@@ -166,6 +167,20 @@ export const DEFAULT_ROUTER_SETTINGS = Object.freeze({
     priorityWeight: 0.2,
   }),
   logLevel: 'info',
+  // 📖 autoHeal — when true (default), the daemon replaces broken models
+  // 📖 in the active set on startup (AUTH_ERROR / TIMEOUT / 5xx) with
+  // 📖 working alternatives from the same provider. Disabled the moment
+  // 📖 the user manually edits the set (reorder/add/remove), so the
+  // 📖 user always has the final say.
+  autoHeal: true,
+  // 📖 Default pre-prompt injected as the first system message on every
+  // 📖 /v1/chat/completions request the router proxies. Frames the assistant
+  // 📖 as the FCM routing agent. Users can disable it or replace it from the
+  // 📖 Settings page on every surface (TUI / Web / Desktop).
+  prePrompt: Object.freeze({
+    enabled: true,
+    text: 'You are free-coding-models, a free coding-model routing agent. The user is talking to you through a local router at http://localhost:19280/v1 that picks the best free coding model in real time across Groq, Cerebras, NVIDIA NIM, GitHub Models, OpenRouter, Mistral, Cloudflare, SambaNova, and more.\n\nBe concise, code-first, and direct. Prefer minimal patches over rewrites. When you show code, make it runnable. When you explain, keep it short. If the user asks which model served them, say you were routed through the local FCM router and point them at the dashboard for the live model list.',
+  }),
 })
 
 function isPlainObject(value) {
@@ -385,7 +400,50 @@ export function normalizeRouterConfig(router) {
     failover: normalizeRouterFailover(router.failover),
     scoring: normalizeRouterScoring(router.scoring),
     logLevel,
+    prePrompt: normalizeRouterPrePrompt(router.prePrompt),
+    // 📖 autoHeal defaults to true. Once the user explicitly edits a set
+    // 📖 (reorder/add/remove/sync) the daemon flips this to false so the
+    // 📖 user's manual choices are not undone on the next start.
+    autoHeal: router.autoHeal !== false,
+    // 📖 userCustomized marks the active set as "edited by the user".
+    // 📖 It is set the first time any write to the active set goes
+    // 📖 through and disables auto-heal for that set. Cleared if the
+    // 📖 user explicitly resets the set.
+    userCustomized: router.userCustomized === true,
+  }
+}
+
+/**
+ * 📖 Normalize the pre-prompt sub-tree. The text is capped at 4000 chars to
+ * 📖 keep the per-request overhead sane and to make sure the pre-prompt is
+ * 📖 always smaller than a typical user message. A disabled pre-prompt
+ * 📖 (`enabled: false`) still preserves the text so toggling back on is a
+ * 📖 no-op rather than a destructive replace.
+ *
+ * @param {unknown} prePrompt
+ * @returns {{ enabled: boolean, text: string }}
+ */
+export function normalizeRouterPrePrompt(prePrompt) {
+  const fallback = DEFAULT_ROUTER_SETTINGS.prePrompt
+  if (!isPlainObject(prePrompt)) {
+    return { enabled: fallback.enabled, text: fallback.text }
   }
+  const rawText = typeof prePrompt.text === 'string' ? prePrompt.text : ''
+  const trimmedText = rawText.slice(0, 4000)
+  return {
+    enabled: prePrompt.enabled === true,
+    text: trimmedText,
+  }
+}
+
+/**
+ * 📖 Returns the default pre-prompt text. Surfaced by the Settings UI so the
+ * 📖 user can hit "Restore default" without retyping the whole persona.
+ *
+ * @returns {string}
+ */
+export function defaultRouterPrePromptText() {
+  return DEFAULT_ROUTER_SETTINGS.prePrompt.text
 }
 
 function normalizeProfileSettings(settings) {