coderouter-cli 2.7.3__tar.gz → 2.7.4__tar.gz

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/CHANGELOG.md

@@ -6,6 +6,49 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.7.4] — 2026-07-06 (Launcher provider auto-sync + /v1/models passthrough)
+
+Two PRs closing the "launcher started it, but nothing can route to it /
+nothing can *name* it" gap, driven by a real field failure (launcher on
+port 8085, providers.yaml pointing at 8080; external benchmark reports
+indistinguishable across loaded GGUFs). **PR #48** (models passthrough)
+and **PR #49** (launcher auto-sync). Fully backward compatible, no new
+dependencies. Verified end-to-end on real hardware (NucBox EVO-X2,
+llama.cpp + omnicoder-9b): zero-config launch → route via
+`X-CodeRouter-Profile: launcher` → response carries the real GGUF name.
+
+### Added
+
+- **`/v1/models` upstream passthrough** for empty-model providers.
+  A provider with `model: ""` (the launcher/llama-server pattern — the
+  upstream decides what is loaded) used to be listed by its static
+  provider name only. Now `/v1/models` queries the upstream's own
+  `/models` (2s timeout, 30s TTL cache) and surfaces the real loaded
+  model id(s) as `owned_by: coderouter/<provider>`. Any failure falls
+  back to the historic provider-name entry; providers with a configured
+  model keep the exact previous shape. External benchmarks (e.g.
+  SWE-bench harnesses with `model: auto`) can now tell GGUF swaps apart
+  without config edits. (PR #48)
+- **Launcher provider auto-sync.** A backend started from the embedded
+  launcher (`/api/launcher/start`) is auto-registered as a routable
+  provider named `launcher-<backend>-<port>` (restart on the same port
+  replaces, never duplicates) and placed at the FRONT of an on-demand
+  `launcher` profile. `default_profile` is never touched — routing is an
+  explicit opt-in via `X-CodeRouter-Profile: launcher` or body
+  `profile`. Registration is deliberately **in-memory only** (a YAML
+  rewrite would destroy operator comments; provider and process share
+  the server's lifetime). Sync failures never fail the start; the
+  result rides on the start response as `provider_sync`. New engine
+  API: `FallbackEngine.register_provider()`. (PR #49)
+
+### Docs
+
+- README (JA/EN) launcher feature table + `docs/backends/launcher.md`:
+  auto-sync semantics, verification curl recipes, and the desktop-GUI
+  caveat (launcher_gui.py runs out-of-process and is not synced).
+
+---
+
 ## [v2.7.3] — 2026-07-05 (Per-request empty-response fallback + L3 bench evidence)
 
 Two PRs: **PR #45** (`empty_response_action` — the fallback leg of the

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.7.3
+Version: 2.7.4
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -220,6 +220,8 @@ providers:
 | **オプションプロファイル** | `providers.yaml` に名前付きプリセットを定義 → ドロップダウンで選択するだけ |
 | **複数プロセス管理** | llama.cpp と vllm を同時に起動し、ポートごとに独立管理 |
 | **ログビューア** | 各プロセスの stdout/stderr をブラウザ内でリアルタイム確認 |
+| **provider 自動同期** (v2.7.4) | 起動したバックエンドを provider として自動登録(`launcher-llamacpp-8085` 等)。providers.yaml 無編集で `X-CodeRouter-Profile: launcher` からルーティング可能。メモリ内のみ・serve と同寿命 |
+| **モデル名パススルー** (v2.7.4) | `model: ""` の provider は `/v1/models` が上流のロード中モデル ID(gguf 名)をそのまま返す。gguf を差し替えても config 編集不要 — 外部ベンチからモデルを識別できる |
 
 ```yaml
 # providers.yaml に追記するだけで有効になる

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/README.en.md

@@ -156,6 +156,8 @@ Browser UI at `http://localhost:8088/launcher` for starting and managing local i
 | **Option profiles** | Name your flag presets in `providers.yaml` — select from a dropdown, no CLI needed |
 | **Multi-process** | Run llama.cpp and vllm side by side on different ports |
 | **Log viewer** | stdout/stderr of each process shown live in the browser |
+| **Provider auto-sync** (v2.7.4) | A started backend is auto-registered as a routable provider (`launcher-llamacpp-8085`); route to it with `X-CodeRouter-Profile: launcher` — zero providers.yaml edits. In-memory, shares the server's lifetime |
+| **Model-id passthrough** (v2.7.4) | Providers with `model: ""` make `/v1/models` surface the upstream's actually-loaded model id (the GGUF name). Swap models without touching config — external benchmarks can tell runs apart |
 
 ```yaml
 # Add to providers.yaml — no code changes needed

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/README.md

@@ -175,6 +175,8 @@ providers:
 | **オプションプロファイル** | `providers.yaml` に名前付きプリセットを定義 → ドロップダウンで選択するだけ |
 | **複数プロセス管理** | llama.cpp と vllm を同時に起動し、ポートごとに独立管理 |
 | **ログビューア** | 各プロセスの stdout/stderr をブラウザ内でリアルタイム確認 |
+| **provider 自動同期** (v2.7.4) | 起動したバックエンドを provider として自動登録(`launcher-llamacpp-8085` 等)。providers.yaml 無編集で `X-CodeRouter-Profile: launcher` からルーティング可能。メモリ内のみ・serve と同寿命 |
+| **モデル名パススルー** (v2.7.4) | `model: ""` の provider は `/v1/models` が上流のロード中モデル ID(gguf 名)をそのまま返す。gguf を差し替えても config 編集不要 — 外部ベンチからモデルを識別できる |
 
 ```yaml
 # providers.yaml に追記するだけで有効になる

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/coderouter/ingress/launcher_routes.py

@@ -655,6 +655,28 @@ async def api_backends(request: Request) -> dict[str, Any]:
     return {"backends": result}
 
 
+def _launcher_provider_config(backend: str, port: int) -> Any:
+    """Build the provider entry for a launcher-started backend.
+
+    ``model`` is left EMPTY on purpose: llama-server / vllm / mlx decide
+    which model is actually loaded, and the empty-model /v1/models
+    passthrough then surfaces the upstream's real model id to benchmark
+    clients — swap the GGUF, no config edit needed.
+
+    Name embeds backend + port (``launcher-llamacpp-8085``) so restarting
+    on the same port REPLACES the entry instead of piling up duplicates.
+    """
+    from coderouter.config.schemas import ProviderConfig
+
+    safe_backend = backend.replace(".", "")
+    return ProviderConfig(
+        name=f"launcher-{safe_backend}-{port}",
+        base_url=f"http://localhost:{port}/v1",
+        model="",
+        timeout_s=120.0,
+    )
+
+
 @router.post("/api/launcher/start")
 async def api_start(req: StartRequest, request: Request) -> dict[str, Any]:
     """Start a new backend process."""
@@ -717,7 +739,35 @@ async def api_start(req: StartRequest, request: Request) -> dict[str, Any]:
     _background_tasks.add(_task)
     _task.add_done_callback(_background_tasks.discard)
 
-    return {"id": proc_id, "pid": p.pid, "command": cmd}
+    # Provider auto-sync: register the just-started backend as a routable
+    # provider so requests can reach it without hand-editing providers.yaml
+    # (in-memory only — see FallbackEngine.register_provider docstring).
+    # Sync failure must never fail the start itself.
+    provider_sync: dict[str, Any] | None = None
+    engine = getattr(request.app.state, "engine", None)
+    if engine is not None and hasattr(engine, "register_provider"):
+        try:
+            provider_sync = engine.register_provider(
+                _launcher_provider_config(req.backend, req.port)
+            )
+            proc.log_tail.append(
+                "[launcher] provider sync: "
+                f"{provider_sync['provider']} -> profile "
+                f"'{provider_sync['profile']}' (in-memory)"
+            )
+        except Exception as exc:
+            logger.warning(
+                "launcher provider sync failed",
+                extra={"backend": req.backend, "port": req.port, "error": str(exc)},
+            )
+            proc.log_tail.append(f"[launcher] provider sync failed: {exc}")
+
+    return {
+        "id": proc_id,
+        "pid": p.pid,
+        "command": cmd,
+        "provider_sync": provider_sync,
+    }
 
 
 @router.post("/api/launcher/stop/{proc_id}")

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/coderouter/ingress/openai_routes.py

@@ -78,22 +78,99 @@ def _resolve_stream_timeout_s(engine: FallbackEngine, profile: str | None) -> fl
     return max(_STREAM_TIMEOUT_MIN_S, float(per_call) * _STREAM_TIMEOUT_MULTIPLIER)
 
 
+# --- /v1/models upstream passthrough -------------------------------------
+#
+# Providers with an *empty* ``model`` field are passthrough providers: the
+# upstream (llama-server, LM Studio, ...) decides which model is loaded and
+# CodeRouter never sends a model name. For those providers the historic
+# behaviour — returning the provider *name* — makes external benchmarks
+# indistinguishable across loaded GGUFs (the launcher_gui setup always
+# reported ``llama-cpp-local`` regardless of the selected model). We now ask
+# the upstream's own ``/models`` endpoint for its real model id(s) and
+# surface those instead.
+#
+# Guards: only for ``kind == "openai_compat"`` with ``model == ""``; a short
+# per-upstream TTL cache keeps repeated SDK probes cheap; ANY failure (refused
+# connection, timeout, unexpected shape) falls back to the historic
+# provider-name entry, so this is strictly additive. Providers with a
+# configured model keep the exact previous behaviour.
+
+_UPSTREAM_MODELS_TTL_S = 30.0
+_UPSTREAM_MODELS_TIMEOUT_S = 2.0
+# base_url -> (expires_monotonic, ids)
+_upstream_models_cache: dict[str, tuple[float, list[str]]] = {}
+
+
+async def _fetch_upstream_model_ids(base_url: str) -> list[str]:
+    """GET {base_url}/models and return the upstream model ids.
+
+    Raises on any transport / shape problem — the caller treats every
+    exception as "fall back to the provider-name entry".
+    """
+    import httpx  # local import keeps module import time flat
+
+    url = base_url.rstrip("/") + "/models"
+    async with httpx.AsyncClient(timeout=_UPSTREAM_MODELS_TIMEOUT_S) as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        payload = resp.json()
+    ids = [
+        str(item["id"])
+        for item in payload.get("data", [])
+        if isinstance(item, dict) and item.get("id")
+    ]
+    if not ids:
+        raise ValueError(f"upstream {url} returned no model ids")
+    return ids
+
+
+async def _upstream_model_ids_cached(base_url: str) -> list[str]:
+    """TTL-cached wrapper around :func:`_fetch_upstream_model_ids`."""
+    now = time.monotonic()
+    hit = _upstream_models_cache.get(base_url)
+    if hit is not None and hit[0] > now:
+        return hit[1]
+    ids = await _fetch_upstream_model_ids(base_url)
+    _upstream_models_cache[base_url] = (now + _UPSTREAM_MODELS_TTL_S, ids)
+    return ids
+
+
 @router.get("/models")
 async def list_models(request: Request) -> dict[str, object]:
-    """Minimal /v1/models so OpenAI SDKs that probe it don't choke."""
+    """/v1/models: provider names, with upstream passthrough for empty-model
+    providers (see the passthrough note above)."""
     config = request.app.state.config
-    return {
-        "object": "list",
-        "data": [
+    created = int(time.time())
+    data: list[dict[str, object]] = []
+    for p in config.providers:
+        if p.model == "" and p.kind == "openai_compat":
+            try:
+                ids = await _upstream_model_ids_cached(str(p.base_url))
+            except Exception:  # any failure means "no passthrough"
+                logger.debug(
+                    "models passthrough failed; falling back to provider name",
+                    extra={"provider": p.name},
+                )
+            else:
+                data.extend(
+                    {
+                        "id": model_id,
+                        "object": "model",
+                        "created": created,
+                        "owned_by": f"coderouter/{p.name}",
+                    }
+                    for model_id in ids
+                )
+                continue
+        data.append(
             {
                 "id": p.name,
                 "object": "model",
-                "created": int(time.time()),
+                "created": created,
                 "owned_by": "coderouter",
             }
-            for p in config.providers
-        ],
-    }
+        )
+    return {"object": "list", "data": data}
 
 
 @router.post("/chat/completions", response_model=None)

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/coderouter/routing/fallback.py

@@ -1173,6 +1173,80 @@ class FallbackEngine:
         # v2.0-K: persistent state store (None = in-memory only).
         self._state_store: StateStore | None = None
 
+    def register_provider(
+        self, provider: ProviderConfig, profile_name: str = "launcher"
+    ) -> dict[str, Any]:
+        """Register (or update) a provider at runtime — launcher auto-sync.
+
+        Motivation: the embedded launcher can start a llama.cpp / vllm /
+        mlx backend on an arbitrary port, but routing is driven entirely
+        by providers.yaml — historically the operator had to hand-edit the
+        config or the new backend was simply unreachable (observed in the
+        wild as "launcher started on 8085, providers.yaml pointed at
+        8080"). This method closes that gap in-process:
+
+        - the provider entry is appended to ``config.providers`` (or, when
+          a provider with the same *name* already exists, its config entry
+          and cached adapter are REPLACED — the launcher restarting a
+          backend on the same port lands here),
+        - an adapter is built and cached alongside the static ones,
+        - the ``profile_name`` chain is created on demand, and the
+          provider is moved to the FRONT of that chain (most recently
+          launched backend wins the launcher profile).
+
+        Deliberately **in-memory only** — no providers.yaml rewrite. A
+        YAML round-trip would destroy operator comments (and a
+        comment-preserving writer means a new dependency), and the
+        launcher's process registry is itself in-memory by design: both
+        the process and its provider entry share the lifetime of this
+        server process. ``default_profile`` is never touched — routing to
+        the launcher profile stays an explicit opt-in
+        (``X-CodeRouter-Profile: launcher`` or body ``profile``).
+
+        Returns a small summary dict for the launcher API response.
+        """
+        from coderouter.config.schemas import FallbackChain
+
+        replaced = False
+        for i, existing in enumerate(self.config.providers):
+            if existing.name == provider.name:
+                self.config.providers[i] = provider
+                replaced = True
+                break
+        if not replaced:
+            self.config.providers.append(provider)
+        self._adapters[provider.name] = build_adapter(provider)
+
+        try:
+            chain = self.config.profile_by_name(profile_name)
+        except KeyError:
+            chain = FallbackChain(name=profile_name, providers=[provider.name])
+            self.config.profiles.append(chain)
+        else:
+            if provider.name in chain.providers:
+                chain.providers.remove(provider.name)
+            chain.providers.insert(0, provider.name)
+
+        logger.info(
+            "launcher provider sync: registered %s -> %s (profile %r)",
+            provider.name,
+            provider.base_url,
+            profile_name,
+            extra={
+                "provider": provider.name,
+                "base_url": str(provider.base_url),
+                "profile": profile_name,
+                "replaced": replaced,
+            },
+        )
+        return {
+            "provider": provider.name,
+            "base_url": str(provider.base_url),
+            "profile": profile_name,
+            "replaced": replaced,
+            "persisted": False,  # in-memory only, by design (see docstring)
+        }
+
     @property
     def plugins(self) -> PluginRegistry:
         """Return the plugin registry, lazily building an empty one if absent.

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/docs/backends/launcher.md

@@ -110,6 +110,31 @@ Launcher の画面は「MODELS パネル」「LAUNCH フォーム」「PROCESSES
 
 `▶ 起動` でプロセスが起動し、PROCESSES テーブルに表示されます。バイナリが見つからない場合は**起動ボタンが自動的に無効化**され、理由が表示されます。「追加オプション」欄の横の **⚙ 推奨値** ボタンについては [メモリ推奨](#メモリ推奨) を参照してください。
 
+### provider 自動同期(v2.7.4、Web版のみ)
+
+Web 版で backend を起動すると、その backend が **provider として自動登録**されます(providers.yaml の編集不要)。
+
+- provider 名は `launcher-<backend>-<port>`(例: `launcher-llamacpp-8085`)。同名で再起動するとエントリは**置き換え**られ、重複しません
+- 登録先は `launcher` プロファイル(無ければ自動作成)。**最後に起動した backend が先頭**に来ます
+- ルーティングは明示オプトイン: `X-CodeRouter-Profile: launcher` ヘッダ、または body の `"profile": "launcher"`。**`default_profile` は変更されません**
+- 登録は**メモリ内のみ**です(providers.yaml には書き込みません — 手書きコメントを壊さないため)。serve を再起動すると消えますが、Launcher のプロセス自体も同寿命なので整合します。恒久化したい場合は providers.yaml に手で転記してください
+- provider は `model: ""` で登録されるため、`/v1/models` は**上流がロード中の実モデル ID(gguf 名)**を返します(モデル名パススルー、同 v2.7.4)。gguf を差し替えても config 編集は不要で、外部ベンチマークからモデルを識別できます(30 秒 TTL キャッシュあり)
+
+動作確認:
+
+```bash
+# 起動後
+curl http://localhost:8088/v1/models
+#   → "id": "<ロード中のgguf名>", "owned_by": "coderouter/launcher-llamacpp-8085"
+
+curl http://localhost:8088/v1/chat/completions \
+  -H 'Content-Type: application/json' -H 'X-CodeRouter-Profile: launcher' \
+  -d '{"model":"x","messages":[{"role":"user","content":"say hi"}]}'
+#   → coderouter_provider が launcher-llamacpp-<port> なら疎通OK
+```
+
+デスクトップ GUI 版(launcher_gui.py)は別プロセスで動くため自動同期の対象外です。従来どおり providers.yaml のエントリ(初回自動生成される `llama-cpp-local` など)の `base_url` を、起動ポートに合わせてください。
+
 ### PROCESSES テーブル
 
 起動した backend プロセスの一覧です。NAME / BACKEND(llama.cpp / vllm / mlx)/ MODEL / PORT / PID / STATUS(`starting` / `running` / `stopped` / `error` を色分け)を表示し、プロセスを選んで **停止**(SIGTERM)・**削除**(レジストリから除去)・**ログ表示**ができます。

{coderouter_cli-2.7.3 → coderouter_cli-2.7.4}/pyproject.toml

@@ -11,7 +11,7 @@
 # in plan.md §11.B; once granted, this name will become an alias and
 # `coderouter` will become the canonical distribution name.
 name = "coderouter-cli"
-version = "2.7.3"
+version = "2.7.4"
 description = "Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible."
 readme = "README.md"
 requires-python = ">=3.12"

coderouter_cli-2.7.4/tests/test_launcher_provider_sync.py

@@ -0,0 +1,124 @@
+"""Tests for launcher provider auto-sync (FallbackEngine.register_provider).
+
+The embedded launcher starts backends on arbitrary ports, but routing is
+config-driven — before this feature the operator had to hand-edit
+providers.yaml (the observed failure: launcher on 8085, config pointing at
+8080). register_provider closes the gap in-memory: provider entry + adapter
++ a "launcher" profile whose head is always the most recently started
+backend. default_profile must never be touched.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from coderouter.config.schemas import CodeRouterConfig, FallbackChain, ProviderConfig
+from coderouter.ingress.launcher_routes import _launcher_provider_config
+from coderouter.routing.fallback import FallbackEngine
+
+
+def _base_config() -> CodeRouterConfig:
+    return CodeRouterConfig(
+        allow_paid=False,
+        default_profile="default",
+        providers=[
+            ProviderConfig(
+                name="static-local",
+                base_url="http://localhost:11434/v1",
+                model="qwen2.5-coder:7b",
+            ),
+        ],
+        profiles=[FallbackChain(name="default", providers=["static-local"])],
+    )
+
+
+def _engine() -> FallbackEngine:
+    return FallbackEngine(_base_config())
+
+
+def test_register_new_provider_adds_config_adapter_and_profile() -> None:
+    engine = _engine()
+    summary = engine.register_provider(
+        _launcher_provider_config("llama.cpp", 8085)
+    )
+
+    names = [p.name for p in engine.config.providers]
+    assert "launcher-llamacpp-8085" in names
+    assert "launcher-llamacpp-8085" in engine._adapters
+    chain = engine.config.profile_by_name("launcher")
+    assert chain.providers == ["launcher-llamacpp-8085"]
+    assert summary["replaced"] is False
+    assert summary["persisted"] is False
+
+
+def test_reregister_same_name_replaces_instead_of_duplicating() -> None:
+    engine = _engine()
+    engine.register_provider(_launcher_provider_config("llama.cpp", 8085))
+    summary = engine.register_provider(
+        _launcher_provider_config("llama.cpp", 8085)
+    )
+
+    names = [p.name for p in engine.config.providers]
+    assert names.count("launcher-llamacpp-8085") == 1
+    chain = engine.config.profile_by_name("launcher")
+    assert chain.providers.count("launcher-llamacpp-8085") == 1
+    assert summary["replaced"] is True
+
+
+def test_most_recent_backend_moves_to_front_of_launcher_profile() -> None:
+    engine = _engine()
+    engine.register_provider(_launcher_provider_config("llama.cpp", 8085))
+    engine.register_provider(_launcher_provider_config("vllm", 8081))
+
+    chain = engine.config.profile_by_name("launcher")
+    assert chain.providers[0] == "launcher-vllm-8081"
+    assert chain.providers == ["launcher-vllm-8081", "launcher-llamacpp-8085"]
+
+
+def test_default_profile_is_never_touched() -> None:
+    engine = _engine()
+    engine.register_provider(_launcher_provider_config("llama.cpp", 8085))
+
+    assert engine.config.default_profile == "default"
+    default_chain = engine.config.profile_by_name("default")
+    assert default_chain.providers == ["static-local"]
+
+
+def test_provider_config_shape_enables_models_passthrough() -> None:
+    pconf = _launcher_provider_config("llama.cpp", 8085)
+    # Empty model == passthrough provider: /v1/models will surface the
+    # upstream's loaded model id, and outbound requests omit the name.
+    assert pconf.model == ""
+    assert pconf.kind == "openai_compat"
+    assert str(pconf.base_url) == "http://localhost:8085/v1"
+
+
+def test_static_providers_and_adapters_survive_sync() -> None:
+    engine = _engine()
+    engine.register_provider(_launcher_provider_config("llama.cpp", 8085))
+
+    assert "static-local" in engine._adapters
+    assert any(p.name == "static-local" for p in engine.config.providers)
+
+
+def test_custom_profile_name_is_respected() -> None:
+    engine = _engine()
+    summary = engine.register_provider(
+        _launcher_provider_config("mlx", 9000), profile_name="bench"
+    )
+    assert summary["profile"] == "bench"
+    assert engine.config.profile_by_name("bench").providers == [
+        "launcher-mlx-9000"
+    ]
+
+
+@pytest.mark.parametrize(
+    ("backend", "port", "expected"),
+    [
+        ("llama.cpp", 8085, "launcher-llamacpp-8085"),
+        ("vllm", 8081, "launcher-vllm-8081"),
+        ("mlx", 9000, "launcher-mlx-9000"),
+    ],
+)
+def test_provider_naming(backend: str, port: int, expected: str) -> None:
+    assert _launcher_provider_config(backend, port).name == expected

coderouter_cli-2.7.4/tests/test_models_passthrough.py

@@ -0,0 +1,144 @@
+"""Tests for /v1/models upstream passthrough (empty-model providers).
+
+A provider whose ``model`` field is empty (the launcher_gui llama-server
+setup) is a passthrough provider: the upstream decides which model is
+loaded. /v1/models should surface the upstream's real model id(s) for such
+providers so external benchmarks can tell loaded GGUFs apart, while keeping
+the historic provider-name entries for everything else — and falling back
+to the provider name whenever the upstream cannot be reached.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from coderouter.config.schemas import CodeRouterConfig, FallbackChain, ProviderConfig
+from coderouter.ingress import openai_routes
+from coderouter.ingress.app import create_app
+
+
+def _config(*providers: ProviderConfig) -> CodeRouterConfig:
+    return CodeRouterConfig(
+        allow_paid=False,
+        default_profile="default",
+        providers=list(providers),
+        profiles=[FallbackChain(name="default", providers=[providers[0].name])],
+    )
+
+
+def _client(
+    config: CodeRouterConfig, monkeypatch: pytest.MonkeyPatch
+) -> TestClient:
+    monkeypatch.setattr(
+        "coderouter.ingress.app.load_config", lambda path=None: config
+    )
+    app = create_app()
+    app.state.config = config
+    return TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def _clear_cache() -> None:
+    openai_routes._upstream_models_cache.clear()
+
+
+def _passthrough_provider(name: str = "llama-cpp-local") -> ProviderConfig:
+    return ProviderConfig(
+        name=name,
+        base_url="http://localhost:8080/v1",
+        model="",  # passthrough — llama-server decides the model
+    )
+
+
+def _named_provider(name: str = "ollama-qwen") -> ProviderConfig:
+    return ProviderConfig(
+        name=name,
+        base_url="http://localhost:11434/v1",
+        model="qwen2.5-coder:7b",
+    )
+
+
+def test_empty_model_provider_surfaces_upstream_id(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def fake_fetch(base_url: str) -> list[str]:
+        assert base_url == "http://localhost:8080/v1"
+        return ["qwen2.5-coder-7b-q4_k_m.gguf"]
+
+    monkeypatch.setattr(openai_routes, "_fetch_upstream_model_ids", fake_fetch)
+    client = _client(_config(_passthrough_provider()), monkeypatch)
+
+    body = client.get("/v1/models").json()
+    ids = [m["id"] for m in body["data"]]
+    assert ids == ["qwen2.5-coder-7b-q4_k_m.gguf"]
+    assert body["data"][0]["owned_by"] == "coderouter/llama-cpp-local"
+
+
+def test_named_model_provider_keeps_historic_shape(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def fail_fetch(base_url: str) -> list[str]:  # pragma: no cover
+        raise AssertionError("passthrough must not fire for named models")
+
+    monkeypatch.setattr(openai_routes, "_fetch_upstream_model_ids", fail_fetch)
+    client = _client(_config(_named_provider()), monkeypatch)
+
+    body = client.get("/v1/models").json()
+    assert [m["id"] for m in body["data"]] == ["ollama-qwen"]
+    assert body["data"][0]["owned_by"] == "coderouter"
+
+
+def test_upstream_failure_falls_back_to_provider_name(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def fake_fetch(base_url: str) -> list[str]:
+        raise ConnectionError("upstream down")
+
+    monkeypatch.setattr(openai_routes, "_fetch_upstream_model_ids", fake_fetch)
+    client = _client(_config(_passthrough_provider()), monkeypatch)
+
+    body = client.get("/v1/models").json()
+    assert [m["id"] for m in body["data"]] == ["llama-cpp-local"]
+    assert body["data"][0]["owned_by"] == "coderouter"
+
+
+def test_mixed_providers_mix_entries(monkeypatch: pytest.MonkeyPatch) -> None:
+    async def fake_fetch(base_url: str) -> list[str]:
+        return ["loaded-model.gguf"]
+
+    monkeypatch.setattr(openai_routes, "_fetch_upstream_model_ids", fake_fetch)
+    client = _client(
+        _config(_passthrough_provider(), _named_provider()), monkeypatch
+    )
+
+    body = client.get("/v1/models").json()
+    assert [m["id"] for m in body["data"]] == ["loaded-model.gguf", "ollama-qwen"]
+
+
+def test_upstream_ids_are_ttl_cached(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[str] = []
+
+    async def fake_fetch(base_url: str) -> list[str]:
+        calls.append(base_url)
+        return ["loaded-model.gguf"]
+
+    monkeypatch.setattr(openai_routes, "_fetch_upstream_model_ids", fake_fetch)
+    client = _client(_config(_passthrough_provider()), monkeypatch)
+
+    client.get("/v1/models")
+    client.get("/v1/models")
+    assert len(calls) == 1, "second probe within the TTL must hit the cache"
+
+
+def test_multiple_upstream_ids_all_listed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def fake_fetch(base_url: str) -> list[str]:
+        return ["model-a.gguf", "model-b.gguf"]
+
+    monkeypatch.setattr(openai_routes, "_fetch_upstream_model_ids", fake_fetch)
+    client = _client(_config(_passthrough_provider()), monkeypatch)
+
+    body = client.get("/v1/models").json()
+    assert [m["id"] for m in body["data"]] == ["model-a.gguf", "model-b.gguf"]