Skip to content

The agent that grows with you

fix(models): an unreachable model catalog no longer stalls every picker build

Tekniumb3ce7f72d062
diff --git a/hermes_cli/model_catalog.py b/hermes_cli/model_catalog.py
index a23e3afc203..53338aae6a1 100644
--- a/hermes_cli/model_catalog.py
+++ b/hermes_cli/model_catalog.py
@@ -2,7 +2,7 @@
``get_catalog()`` returns the parsed manifest: in-process cache (TTL) → disk cache at
``~/.hermes/cache/model_catalog.json`` → master URL fetch; any fetch failure keeps the stale copy
-(or ``{}``). ``get_curated_openrouter_models()`` / ``get_curated_nous_models()`` are thin accessors
+(or ``{}``, and the URL is not retried for ``FETCH_RETRY_DELAY_SECONDS``). ``get_curated_openrouter_models()`` / ``get_curated_nous_models()`` are thin accessors
whose callers fall back to the in-repo lists on ``None``.
"""
@@ -34,6 +34,10 @@ DEFAULT_TTL_MINUTES = 20
# Legacy key, honoured only when the user set it explicitly; ``ttl_minutes`` is the shipped default.
DEFAULT_TTL_HOURS = DEFAULT_TTL_MINUTES / 60.0
DEFAULT_FETCH_TIMEOUT = 8.0
+# After a failed fetch with no cached manifest to serve, the same URL is not retried in this process
+# for this long: an offline user would otherwise wait out the timeout (primary + fallback URL, ~16 s)
+# on every picker build. Same window as the models.dev registry's failure backoff.
+FETCH_RETRY_DELAY_SECONDS = 300.0
SUPPORTED_SCHEMA_VERSION = 1
_HERMES_USER_AGENT = f"hermes-cli/{get_version_info().base_version}"
@@ -44,6 +48,19 @@ _HERMES_USER_AGENT = f"hermes-cli/{get_version_info().base_version}"
_catalog_cache: dict[str, Any] | None = None
_catalog_cache_source_mtime: float = 0.0
_catalog_cache_source_path: str = ""
+# ``monotonic()`` deadline before which a failed fetch key is not retried (see FETCH_RETRY_DELAY_SECONDS).
+_fetch_retry_after: dict[str, float] = {}
+
+
+def _backing_off(key: str) -> bool:
+ return time.monotonic() < _fetch_retry_after.get(key, 0.0)
+
+
+def _note_fetch_result(key: str, ok: bool) -> None:
+ if ok:
+ _fetch_retry_after.pop(key, None)
+ else:
+ _fetch_retry_after[key] = time.monotonic() + FETCH_RETRY_DELAY_SECONDS
def _load_catalog_config() -> dict[str, Any]:
@@ -232,7 +249,12 @@ def get_catalog(*, force_refresh: bool = False) -> dict[str, Any]:
_spawn_catalog_swr_refresh(cfg["url"])
return _remember(disk_data, disk_mtime)
+ # Keyed per cache file (profile) and URL, like the in-process copy above.
+ backoff_key = f"{_cache_path()}|{cfg['url']}"
+ if not force_refresh and disk_data is None and _backing_off(backoff_key):
+ return {}
fetched = _fetch_manifest_with_fallback(cfg["url"], DEFAULT_FETCH_TIMEOUT)
+ _note_fetch_result(backoff_key, fetched is not None)
if fetched is not None:
_write_disk_cache(fetched)
new_disk_data, new_mtime = _read_disk_cache()
@@ -277,8 +299,14 @@ def _fetch_provider_override(provider: str) -> dict[str, Any] | None:
override_url = provider_cfg.get("url")
if not isinstance(override_url, str) or not override_url.strip():
return None
- # Overrides are usually third-party self-hosted: skip the disk cache, re-request every call.
- return _fetch_manifest(override_url.strip(), DEFAULT_FETCH_TIMEOUT)
+ # Overrides are usually third-party self-hosted: skip the disk cache, re-request every call
+ # (except during a failure backoff; the caller then falls back to the main manifest).
+ override_url = override_url.strip()
+ if _backing_off(override_url):
+ return None
+ data = _fetch_manifest(override_url, DEFAULT_FETCH_TIMEOUT)
+ _note_fetch_result(override_url, data is not None)
+ return data
def _block_of(manifest: dict[str, Any] | None, provider: str) -> dict[str, Any] | None:
@@ -344,8 +372,9 @@ def seed_cache_from_checkout(project_root: Path | str) -> bool:
def reset_cache() -> None:
- """Clear the in-process cache. Used by tests and ``hermes model --refresh``."""
+ """Clear the in-process cache and fetch-failure backoff. Used by tests and ``hermes model --refresh``."""
global _catalog_cache, _catalog_cache_source_mtime, _catalog_cache_source_path
+ _fetch_retry_after.clear()
_catalog_cache = None
_catalog_cache_source_mtime = 0.0
_catalog_cache_source_path = ""
diff --git a/tests/hermes_cli/test_model_catalog.py b/tests/hermes_cli/test_model_catalog.py
index 88695dca13f..5bc8c37a5c0 100644
--- a/tests/hermes_cli/test_model_catalog.py
+++ b/tests/hermes_cli/test_model_catalog.py
@@ -129,6 +129,52 @@ class TestFetchFailure:
# Stale cache is better than nothing.
assert result == manifest
+ def test_offline_cold_cache_does_not_refetch_on_every_call(self, isolated_home, monkeypatch):
+ """Offline with no cached manifest: one failed fetch, then later calls answer at once
+ until the retry window ends; an explicit refresh still tries the network."""
+ from hermes_cli import model_catalog
+ calls: list[str] = []
+
+ def offline(url, timeout):
+ calls.append(url) # returns None: the fetch failed
+
+ with patch.object(model_catalog, "_fetch_manifest", side_effect=offline):
+ assert model_catalog.get_catalog() == {}
+ per_attempt = len(calls)
+ assert per_attempt >= 1
+ assert model_catalog.get_catalog() == {}
+ assert model_catalog.get_catalog() == {}
+ assert len(calls) == per_attempt, "retried the unreachable catalog inside the window"
+ assert model_catalog.get_catalog(force_refresh=True) == {}
+ assert len(calls) == 2 * per_attempt
+
+ # Window over (zero-length): the next call fetches again and serves the manifest.
+ monkeypatch.setattr(model_catalog, "FETCH_RETRY_DELAY_SECONDS", 0.0)
+ with patch.object(model_catalog, "_fetch_manifest", side_effect=offline):
+ assert model_catalog.get_catalog(force_refresh=True) == {}
+ with patch.object(model_catalog, "_fetch_manifest", return_value=_valid_manifest()):
+ assert model_catalog.get_catalog() == _valid_manifest()
+
+ def test_unreachable_provider_override_is_not_refetched_on_every_call(self, isolated_home):
+ from hermes_cli import model_catalog
+ calls: list[str] = []
+
+ def fetch(url, timeout):
+ calls.append(url)
+ return None if "override" in url else _valid_manifest()
+
+ cfg = {"enabled": True, "url": "http://master", "ttl_hours": 24.0,
+ "providers": {"openrouter": {"url": "http://override"}}}
+ with patch.object(model_catalog, "_load_catalog_config", return_value=cfg), \
+ patch.object(model_catalog, "_fetch_manifest", side_effect=fetch):
+ first = model_catalog.get_curated_openrouter_models()
+ second = model_catalog.get_curated_openrouter_models()
+
+ # Both calls fall back to the main manifest; the dead override is asked once.
+ assert first == second == [(m["id"], m["description"]) for m in
+ _valid_manifest()["providers"]["openrouter"]["models"]]
+ assert calls.count("http://override") == 1
+
class TestFallbackChain:
"""``_fetch_manifest_with_fallback`` walks ``DEFAULT_CATALOG_FALLBACK_URLS``