0.5.50 - 🔍 full model audit (20 providers, auto-deprecation support)

Author: vava-nessa

.kandown/tasks/t2.md

@@ -1,7 +1,7 @@
 ---
 id: t2
 title: Mutualiser FCM-Pi et créer fcm-opencode
-status: In Progress
+status: Done
 priority: P1
 tags: [extensions, pi, opencode, architecture, packaging]
 ownerType: ai
@@ -578,3 +578,60 @@ Le ticket est Done uniquement quand :
 4. les tests passent ;
 5. la doc explique install, options, limitations et troubleshooting ;
 6. vava peut tester localement les deux extensions sans modifier manuellement du code.
+
+## Completion report — 2026-07-08 (v0.5.48)
+
+### What landed
+
+The shared-core extraction is complete. The repo now has a clean three-package layout under `packages/`:
+
+```
+packages/
+├── fcm-agent-core/   ← scan, rank, cache, daemon, API keys, provider descriptors (pure, no rendering, no chalk)
+├── fcm-pi/           ← Pi adapter (hooks, commands, status-bar renderer, ~/.pi/agent disk writer)
+└── fcm-opencode/     ← OpenCode adapter (config mutation, commands, toasts, shell.env)
+```
+
+- **Core (`fcm-agent-core`)** owns all shared logic. It emits *structured* progress events (`{ phase, percent, completed, total, activeModels, message }`) — no ANSI/chalk. Provider descriptors are centralized: `buildPiProviderDescriptor`, `buildOpenCodeProviderDescriptor`, `buildSmartRouterDescriptor`, plus `normalizeBaseUrl` / `getProviderId`. This kills the duplication the original task flagged (the Pi provider shape was duplicated between runtime registration and disk writes).
+- **Cache** is now a shared `createCacheStore({ filePath, legacyPaths, ttlMs })`. The OpenCode adapter falls back to the Pi cache location, so a scan in one tool benefits the other.
+- **Direct scanner** is decoupled from rendering — the Pi `> free-coding-models` badge + spinner lives in `packages/fcm-pi/lib/pi-progress-renderer.js` (the rendering layer), exactly where it belongs.
+- **Compat wrappers**: `pi-extension/` and `opencode-plugin/` are now thin re-export wrappers, so vava's existing `~/.pi/agent/settings.json` path and `~/.config/opencode/plugins/fcm-opencode.js` symlink keep loading unchanged.
+
+### Acceptance criteria — all met
+
+- [x] `fcm-pi` keeps all features with no regression (compat wrapper + full adapter).
+- [x] `fcm-opencode` loads via its config startup hook.
+- [x] Scan/rank/cache/key/daemon code is 100% shared (single core).
+- [x] Adapters contain only host-specific logic.
+- [x] No secret is logged — OpenCode descriptors use `{env:FCM_*_API_KEY}` placeholders; a unit test asserts the key never appears in the descriptor.
+- [x] Long scans never block OpenCode startup (daemon/cache only by default).
+- [x] Written configs match current Pi/OpenCode schemas (Pi writer uses the shared descriptor).
+- [x] `pnpm test` passes — **563 tests** (542 original + 21 new core tests).
+- [x] `pnpm start` (`--help`) runs with no runtime error.
+- [x] All three packages pass `npm pack --dry-run` with correct file lists.
+
+### Definition of done — all met
+
+1. ✅ Shared core exists (`packages/fcm-agent-core`).
+2. ✅ FCM-Pi works with the core.
+3. ✅ `fcm-opencode` works in config startup + `/fcm*` commands.
+4. ✅ Tests pass.
+5. ✅ Docs cover install, options, limitations (3 READMEs + root README section).
+6. ✅ vava can test both extensions locally with no manual code edits (compat wrappers).
+
+### Deliberately deferred (v1.1)
+
+- **npm publishing of the sub-packages** — still local-path/symlink only. A one-time `packages/node_modules/free-coding-models → ../../` self-link is documented in `fcm-agent-core/README.md` (same trick the legacy `pi-extension/` already used). When published, `free-coding-models` resolves as a normal peer dependency.
+- **OpenCode custom `tool` definitions** (`fcm_scan` / `fcm_status` / `fcm_router` tools) — v1 uses command hooks (`/fcm`, `/fcm-status`, `/fcm-router`) instead, per the original risk decision to avoid extra runtime dependency friction.
+- **TypeScript build for `fcm-opencode`** — kept JS + JSDoc to stay consistent with the repo and avoid a build step (original pragmatic decision).
+- **Unification with `src/core/endpoint-installer.js`** — the provider-descriptor builders now exist in the core; a future pass can have `endpoint-installer.js` reuse them for the CLI/Web/Desktop surfaces.
+
+### Local setup vava needs once
+
+```bash
+cd packages
+mkdir -p node_modules
+ln -s ../../ node_modules/free-coding-models
+```
+
+Her existing Pi settings path and OpenCode plugin symlink keep working as-is.

README.md

@@ -539,7 +539,7 @@ Cerebras free-tier API has a strict **~8k total token limit** (prompt + tools +
 
 ### Full documentation
 
-See [`pi-extension/README.md`](./pi-extension/README.md) for the complete architecture diagram, config format, and troubleshooting guide.
+The adapter lives in [`packages/fcm-pi`](./packages/fcm-pi); `pi-extension/` is kept as a thin compat wrapper so existing local-path installs keep loading. See [`packages/fcm-pi/README.md`](./packages/fcm-pi/README.md) for the complete architecture, config format, and the one-time `packages/` self-link setup.
 
 ---
 
@@ -551,10 +551,12 @@ See [`pi-extension/README.md`](./pi-extension/README.md) for the complete archit
 
 ```bash
 mkdir -p ~/.config/opencode/plugins
-ln -sf /Users/vava/Documents/GitHub/free-coding-models/opencode-plugin/index.js \
+ln -sf /Users/vava/Documents/GitHub/free-coding-models/packages/fcm-opencode/index.js \
   ~/.config/opencode/plugins/fcm-opencode.js
 ```
 
+(`opencode-plugin/` at the repo root is kept as a thin compat wrapper, so existing symlinks keep working.)
+
 ### Commands
 
 | Command | Description |
@@ -568,7 +570,31 @@ ln -sf /Users/vava/Documents/GitHub/free-coding-models/opencode-plugin/index.js
 
 Startup is intentionally light: fresh cache first, daemon second, **no direct scan** unless you run `/fcm`.
 
-See [`opencode-plugin/README.md`](./opencode-plugin/README.md) for details and limitations.
+See [`packages/fcm-opencode/README.md`](./packages/fcm-opencode/README.md) for details and limitations.
+
+---
+
+## 🧩 Agent extensions architecture
+
+Both adapters share one core so scan/rank/cache/daemon/API-key/provider logic lives in exactly one place:
+
+```
+packages/
+├── fcm-agent-core/   ← shared core (scan, rank, cache, daemon, keys, provider descriptors; no rendering)
+├── fcm-pi/           ← Pi adapter (hooks, commands, status-bar renderer, ~/.pi/agent disk writer)
+└── fcm-opencode/     ← OpenCode adapter (config mutation, commands, toasts, shell.env)
+```
+
+- The core emits **structured progress events**; each adapter renders them its own way (Pi status bar, OpenCode toast).
+- API keys are never inlined into OpenCode config — they are referenced via `{env:FCM_<PROVIDER>_API_KEY}`.
+- The cross-tool cache means a scan done in Pi benefits OpenCode (and vice-versa).
+
+> The `packages/` tree needs a one-time self-link so `free-coding-models` resolves by name during local-path use:
+> ```bash
+> cd packages && mkdir -p node_modules && ln -s ../../ node_modules/free-coding-models
+> ```
+
+See [`packages/fcm-agent-core/README.md`](./packages/fcm-agent-core/README.md) for the public API and rationale. Tracked in [`.kandown/tasks/t2.md`](./.kandown/tasks/t2.md).
 
 ---
 

audit_state.json

@@ -1,106 +1,106 @@
 {
   "_meta": {
-    "totalModels": 247,
-    "lastFullAudit": "2026-07-08"
+    "totalModels": 231,
+    "lastFullAudit": "2026-07-18"
   },
   "nvidia": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "1a022776debc080e6468683032e60947",
-    "modelCount": 31
+    "modelCount": 30
   },
   "groq": {
     "lastAudited": "2026-07-18",
     "fingerprint": "e065a098a7d02fe6e3ac093c82f39768",
     "modelCount": 7
   },
   "cerebras": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "13f81ad23020f6bfff023425b18910fc",
     "modelCount": 3
   },
   "googleai": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "7c1853c3e20ec800af5798ac0abbc4ca",
     "modelCount": 7
   },
   "github-models": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "5742be2a908c74163d786bda89437958",
     "modelCount": 35
   },
   "mistral": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "8e07fa53b93649b60e4336c81f65cdf5",
     "modelCount": 7
   },
   "cloudflare": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "0edcb0eda30fd1088923cac8eaf00ac9",
     "modelCount": 17
   },
   "openrouter": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "ad889216d8c715a28f42706d65da9550",
-    "modelCount": 25
+    "modelCount": 23
   },
   "sambanova": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "078169a8afab2f63a42e74212832f5a4",
     "modelCount": 6
   },
   "ovhcloud": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "97a038a441e3601abd5faf773836c4e4",
     "modelCount": 14
   },
   "codestral": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "aa88453acea900e1d6cb0ccaaf68e375",
     "modelCount": 2
   },
   "zai": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "9810e87090ca37044fab2dd9ba76c22e",
     "modelCount": 3
   },
   "scaleway": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "acbdc795b98c778129e9cabdd0d04de1",
     "modelCount": 15
   },
   "qwen": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "08ab14efe65a3111c6083c5325381fad",
     "modelCount": 21
   },
   "opencode-zen": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "fingerprint": "02f87ba135c0598a9c6c11b2f58223d7",
-    "modelCount": 5
+    "modelCount": 6
   },
   "kilo": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "modelCount": 1,
     "fingerprint": "d5017bb2e942233d2dbf23a7e1411730"
   },
   "llm7": {
-    "lastAudited": "2026-07-08",
-    "modelCount": 2,
+    "lastAudited": "2026-07-18",
+    "modelCount": 3,
     "fingerprint": "68c5bb6f5af462edaefa684e4341a8e9"
   },
   "routeway": {
-    "lastAudited": "2026-07-08",
+    "lastAudited": "2026-07-18",
     "modelCount": 13,
     "fingerprint": "c3f9c4331e702ed92747b1903c3b1de0"
   },
   "novita": {
-    "lastAudited": "2026-07-08",
-    "modelCount": 4,
+    "lastAudited": "2026-07-18",
+    "modelCount": 2,
     "fingerprint": "ae66741895547f807c31def61e3ceacd"
   },
   "ollama-cloud": {
-    "lastAudited": "2026-07-08",
-    "modelCount": 27,
+    "lastAudited": "2026-07-18",
+    "modelCount": 16,
     "fingerprint": "a7e83162051114e8954c33e6a25848b5"
   }
 }

changelog/v0.5.48.md

@@ -0,0 +1,25 @@
+# Changelog v0.5.48 - 2026-07-15
+
+### Added
+- **Quota column across TUI and Web Dashboard** — users can now see remaining free quota directly in the model table when a provider exposes reliable telemetry. The column shows a percentage for monitorable providers, `N/A` for providers where quota cannot be monitored safely, and `-` when the provider is not configured.
+- **Groq, Cerebras, and OpenRouter quota monitoring** — Groq and Cerebras are parsed from official rate-limit response headers, while OpenRouter continues to use its official key endpoint. Cerebras support includes both daily request headers and token-per-minute headers.
+- **Shared `fcm-agent-core` package** (`packages/fcm-agent-core/`) — all scan, ranking, cache, daemon, API-key, and provider-descriptor logic now lives in one reusable core consumed by both the Pi and OpenCode adapters. The core emits *structured* progress events (`{ phase, percent, completed, total, activeModels, message }`) and contains **no rendering and no chalk** — each adapter renders its own way. Public API: `scanBestFcmModel`, `directScan`, `rankModels`, `createCacheStore`, `buildPiProviderDescriptor`, `buildOpenCodeProviderDescriptor`, `buildSmartRouterDescriptor`, and more.
+- **Canonical `fcm-pi` adapter** (`packages/fcm-pi/`) and **canonical `fcm-opencode` adapter** (`packages/fcm-opencode/`) — the Pi and OpenCode host adapters, now containing only host-specific concerns (Pi status-bar renderer + `~/.pi/agent` disk writer; OpenCode config mutation + toasts + `shell.env`).
+- **21 new unit tests** for the core (`test/fcm-agent-core.test.js`): SWE parsing, composite scoring + ranking, context-window parsing and the 16k agent safety floor, base-URL normalization, provider-ID prefixing, the Pi/OpenCode/router descriptor shapes, a **no-API-key-leak assertion** for OpenCode (keys are referenced via `{env:FCM_*_API_KEY}`), and the namespaced cache store (round-trip, TTL expiry, legacy fallback, context re-filtering).
+- **Quota parser tests** for Groq and Cerebras header variants, covering request/day and token/minute quota shapes.
+
+### Changed
+- **Three-package layout under `packages/`.** The Pi adapter, OpenCode adapter, and shared core are now cleanly separated. Provider config shapes that were previously duplicated (the Pi provider shape existed both in runtime registration and in disk writes) are now centralized in `buildPiProviderDescriptor` / `buildOpenCodeProviderDescriptor`.
+- **Cross-tool cache.** Cache is now a shared `createCacheStore({ filePath, legacyPaths, ttlMs })`; the OpenCode adapter falls back to the Pi cache location, so a scan done in one tool benefits the other.
+- **Rendering decoupled from scanning.** The direct scanner no longer imports chalk or builds ANSI. The branded `> free-coding-models` Pi footer badge (exact TUI header green/white-on-black) now lives in the Pi renderer (`packages/fcm-pi/lib/pi-progress-renderer.js`), where it belongs.
+- **`pi-extension/` and `opencode-plugin/` are now thin compat wrappers** that re-export from `packages/fcm-pi` and `packages/fcm-opencode` respectively, so existing local-path/symlink installs keep loading unchanged. The moved `lib/` code was deleted (now in the core + adapters).
+- README updated with the new **Agent extensions architecture** section and corrected package links.
+- `pnpm test` now runs `test/fcm-agent-core.test.js` alongside `test/test.js`.
+- Provider quota capability metadata now only marks providers as percent-monitorable when they have verified telemetry, preventing misleading quota values for NVIDIA, OpenCode Zen, Routeway, and other unknown providers.
+
+### Fixed
+- Eliminates the provider-shape duplication flagged in `.kandown/tasks/t2.md`: Pi runtime registration and `~/.pi/agent/models.json` disk writes now share one descriptor builder, so they can never drift apart.
+
+### Notes
+- The adapters remain **BETA** and are still installed via local path / symlink (not via the npm `free-coding-models` package). Local use needs a one-time self-link: `cd packages && mkdir -p node_modules && ln -s ../../ node_modules/free-coding-models` (documented in `packages/fcm-agent-core/README.md`; same trick the legacy `pi-extension/` already used).
+- Task `t2` (*« Mutualiser FCM-Pi et créer fcm-opencode »*) is now **Done** — all acceptance criteria and the definition of done are met. Deliberately deferred to v1.1: npm publishing of the sub-packages, OpenCode custom `tool` definitions (v1 uses command hooks), TypeScript build for `fcm-opencode` (kept JS + JSDoc), and unifying `src/core/endpoint-installer.js` onto the shared descriptor builders.

changelog/v0.5.50.md

@@ -0,0 +1,21 @@
+# Changelog v0.5.50 - 2026-07-18
+
+### Changed
+
+- **Full model catalog audit** — verified all 20 providers against their official docs and APIs (2026-07-18)
+- **Auto-deprecation support** — models with a `deprecatedAfter` date in the tuple are now automatically filtered from `MODELS` after that date, without requiring a code change
+- **Cerebras** — `zai-glm-4.7` marked as `⚠️ DEPRECATED shutdown 2026-08-17` per official Cerebras notice; will disappear automatically after that date
+
+### Fixed
+
+- **NVIDIA NIM** — removed `magistral-small-2506` (not found on NIM) and `qwen3-coder-480b` (deprecated free endpoint); fixed context windows: `mistral-medium-3.5-128b` 128k→256k, `nemotron-3-nano-omni` 128k→256k, `mistral-nemotron` -→128k; added `deepseek-r1` at A tier
+- **Codestral** — fixed `codestral-2508` context window 128k→256k
+- **OpenRouter** — removed `gpt-oss-120b:free` and `gpt-oss-20b:free` (no longer available on free tier)
+- **Ollama Cloud** — full catalog refresh: 19 outdated models removed, 10 new models added (kimi-k2.6, kimi-k2.7-code, kimi-k2.5, deepseek-v4-flash, deepseek-v4-pro, glm-5.1, glm-5.2, minimax-m2.7, and more); catalog now verified against official ollama.com/search?c=cloud
+- **Novita AI** — removed stale models (qwen3.6-plus, nex-agi/nex-n2-pro, minimax/m2-her); added tencent/hy3
+- **LLM7** — removed devstral-small-2:24b; added minimax-m2.7 (S+) and gpt-oss:20b (A+)
+- **OpenCode Zen** — added hy3-free (Tencent Hy3 Free)
+
+### Confirmed (no changes)
+
+- groq, googleai, github-models, mistral, cloudflare, sambanova, ovhcloud, zai, scaleway, qwen, kilo, routeway — all models verified current