free-coding-models 0.5.10 → 0.5.11

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 |
@@ -510,6 +545,8 @@ When a tool mode is active (via `Z`), models incompatible with that tool are hig
 - **Keyless latency** — models ping even without an API key (show 🔑 NO KEY)
 - **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.
+- **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "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,14 @@ export const DEFAULT_ROUTER_SETTINGS = Object.freeze({
     priorityWeight: 0.2,
   }),
   logLevel: 'info',
+  // 📖 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 +394,41 @@ export function normalizeRouterConfig(router) {
     failover: normalizeRouterFailover(router.failover),
     scoring: normalizeRouterScoring(router.scoring),
     logLevel,
+    prePrompt: normalizeRouterPrePrompt(router.prePrompt),
+  }
+}
+
+/**
+ * 📖 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) {