The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(providers): lazy provider headers stay a real dict for plugin overrides
Tekniumd509ab10d7f1
diff --git a/hermes_cli/plugin_host_child.py b/hermes_cli/plugin_host_child.pyindex b01aba4a27b..f17e153c17d 100644--- a/hermes_cli/plugin_host_child.py+++ b/hermes_cli/plugin_host_child.py@@ -25,7 +25,6 @@ import osimport sysimport threadingimport types-from collections import abcfrom pathlib import Pathfrom typing import Any, Callable, Dict, List, Optional@@ -545,15 +544,6 @@ def capture_profiles(path: str, module_name: str) -> list[Any]:return captured-def _profile_value(value: Any) -> Any:- """A profile field as data: a non-dict Mapping (bundled ``LazyHeaders``, which an override copying a- bundled profile inherits) resolves here, in the credential-free extraction, rather than crossing as an- Opaque placeholder the parent's client builders silently drop."""- if isinstance(value, abc.Mapping) and not isinstance(value, dict):- return dict(value)- return value--def describe_profile(profile: Any) -> dict[str, Any]:"""Profile data (instance fields) plus the methods and callable fields that must run here."""from providers.base import ProviderProfile@@ -565,7 +555,7 @@ def describe_profile(profile: Any) -> dict[str, Any]:if callable(value):calls[name] = {"async": is_async_callable(value), "sig": describe_signature(value), "field": True}else:- fields[name] = encode(_profile_value(value))+ fields[name] = encode(value)for name in dir(type(profile)):if name.startswith("_") or name in fields or name in calls:continue@@ -573,7 +563,7 @@ def describe_profile(profile: Any) -> dict[str, Any]:if attr is getattr(ProviderProfile, name, object()):continueif isinstance(inspect.getattr_static(profile, name), property) or not callable(attr):- fields[name] = encode(_profile_value(getattr(profile, name)))+ fields[name] = encode(getattr(profile, name))continuecalls[name] = {"async": is_async_callable(attr), "sig": describe_signature(getattr(profile, name)),"field": False}diff --git a/plugins/model-providers/fireworks/__init__.py b/plugins/model-providers/fireworks/__init__.pyindex 0d82177112c..69fd9a670dc 100644--- a/plugins/model-providers/fireworks/__init__.py+++ b/plugins/model-providers/fireworks/__init__.py@@ -33,10 +33,10 @@ fireworks = FireworksProfile(base_url="https://api.fireworks.ai/inference/v1", auth_type="api_key",# Attribution headers (canonical Hermes set); via default_headers so they# survive switch_model and credential rotation.- default_headers=LazyHeaders(lambda: {+ default_headers=LazyHeaders({"HTTP-Referer": "https://hermes-agent.nousresearch.com","X-Title": "Hermes Agent",- "User-Agent": hermes_user_agent("HermesAgent"),+ "User-Agent": lambda: hermes_user_agent("HermesAgent"),}),default_aux_model="accounts/fireworks/models/glm-5p2",# Picker safety net when the live catalog fetch fails.diff --git a/plugins/model-providers/gmi/__init__.py b/plugins/model-providers/gmi/__init__.pyindex e47bb638d07..d564920fdc0 100644--- a/plugins/model-providers/gmi/__init__.py+++ b/plugins/model-providers/gmi/__init__.py@@ -10,7 +10,7 @@ gmi = ProviderProfile(signup_url="https://www.gmicloud.ai/", env_vars=("GMI_API_KEY", "GMI_BASE_URL"),base_url="https://api.gmi-serving.com/v1", auth_type="api_key",# Attribution so GMI can identify Hermes Agent traffic.- default_headers=LazyHeaders(lambda: {"User-Agent": hermes_user_agent("HermesAgent")}),+ default_headers=LazyHeaders({"User-Agent": lambda: hermes_user_agent("HermesAgent")}),default_aux_model="google/gemini-3.1-flash-lite-preview",fallback_models=("zai-org/GLM-5.1-FP8", "deepseek-ai/DeepSeek-V3.2", "moonshotai/Kimi-K2.5",diff --git a/plugins/model-providers/kimi-coding/__init__.py b/plugins/model-providers/kimi-coding/__init__.pyindex d09a991aaab..54aa9f1f43d 100644--- a/plugins/model-providers/kimi-coding/__init__.py+++ b/plugins/model-providers/kimi-coding/__init__.py@@ -9,16 +9,15 @@ from hermes_cli.version_info import hermes_user_agentfrom providers import register_providerfrom providers.base import OMIT_TEMPERATURE, LazyHeaders, ProviderProfile-def _headers() -> dict[str, str]:- return {- "HTTP-Referer": "https://hermes-agent.nousresearch.com",- "X-Title": "Hermes Agent",- "User-Agent": hermes_user_agent("HermesAgent"),- # Exclude brotli: httpx's brotlicffi backend has a streaming decode bug on- # Moonshot's content-encoding: br SSE responses (#28043, #48428, #59556).- # gzip sidesteps it while still compressing the transfer.- "Accept-Encoding": "gzip",- }+_HEADERS = {+ "HTTP-Referer": "https://hermes-agent.nousresearch.com",+ "X-Title": "Hermes Agent",+ "User-Agent": lambda: hermes_user_agent("HermesAgent"),+ # Exclude brotli: httpx's brotlicffi backend has a streaming decode bug on+ # Moonshot's content-encoding: br SSE responses (#28043, #48428, #59556).+ # gzip sidesteps it while still compressing the transfer.+ "Accept-Encoding": "gzip",+}def _is_confirmed_kimi_coding_url(base_url: str) -> bool:@@ -70,7 +69,7 @@ def _kimi(name: str, aliases: tuple, env_vars: tuple, base_url: str) -> KimiProfreturn KimiProfile(name=name, aliases=aliases, env_vars=env_vars, base_url=base_url,fixed_temperature=OMIT_TEMPERATURE, default_max_tokens=32000,- default_headers=LazyHeaders(_headers), default_aux_model="kimi-k2-turbo-preview",+ default_headers=LazyHeaders(_HEADERS), default_aux_model="kimi-k2-turbo-preview",)diff --git a/plugins/model-providers/opencode-zen/__init__.py b/plugins/model-providers/opencode-zen/__init__.pyindex ee31d4287df..39f192420fd 100644--- a/plugins/model-providers/opencode-zen/__init__.py+++ b/plugins/model-providers/opencode-zen/__init__.py@@ -14,12 +14,11 @@ from datetime import UTC# Attribution headers (same values as OpenRouter / Vercel / Fireworks); via# default_headers so they survive model switches and credential rotation.-def _attribution_headers() -> dict[str, str]:- return {- "HTTP-Referer": "https://hermes-agent.nousresearch.com",- "X-Title": "Hermes Agent",- "User-Agent": hermes_user_agent("HermesAgent"),- }+_ATTRIBUTION_HEADERS = {+ "HTTP-Referer": "https://hermes-agent.nousresearch.com",+ "X-Title": "Hermes Agent",+ "User-Agent": lambda: hermes_user_agent("HermesAgent"),+}def _flat_model_name(model: str | None) -> str:@@ -119,13 +118,13 @@ class OpenCodeZenProfile(ProviderProfile):opencode_zen = OpenCodeZenProfile(name="opencode-zen", aliases=("opencode", "opencode_zen", "zen"), env_vars=("OPENCODE_ZEN_API_KEY",),- base_url="https://opencode.ai/zen/v1", default_headers=LazyHeaders(_attribution_headers),+ base_url="https://opencode.ai/zen/v1", default_headers=LazyHeaders(_ATTRIBUTION_HEADERS),default_aux_model="gemini-3-flash",)opencode_go = OpenCodeGoProfile(name="opencode-go", aliases=("opencode_go", "go", "opencode-go-sub"), env_vars=("OPENCODE_GO_API_KEY",),- base_url="https://opencode.ai/zen/go/v1", default_headers=LazyHeaders(_attribution_headers),+ base_url="https://opencode.ai/zen/go/v1", default_headers=LazyHeaders(_ATTRIBUTION_HEADERS),default_aux_model="glm-5",# The Go relay's upstream validates tool content as a strict string: list-type tool# content (native vision embeds) 422s with ``messages.N.tool.content.str Input shoulddiff --git a/plugins/model-providers/router/__init__.py b/plugins/model-providers/router/__init__.pyindex 58cb201671b..3aa04b73a4f 100644--- a/plugins/model-providers/router/__init__.py+++ b/plugins/model-providers/router/__init__.py@@ -294,7 +294,7 @@ router = RouterProfile(env_vars=("RAMP_ROUTER_API_KEY", "ROUTER_API_KEY", "RAMP_ROUTER_BASE_URL"), base_url=_base_url(),auth_type="api_key",# Router attributes coding-agent clients by UA prefix; its WAF rejects default UAs.- default_headers=LazyHeaders(lambda: {"User-Agent": hermes_user_agent("Hermes-Agent")}),+ default_headers=LazyHeaders({"User-Agent": lambda: hermes_user_agent("Hermes-Agent")}),supports_vision=True, default_aux_model="gpt-5.4-mini",fallback_models=(), # account-scoped IDs; the picker uses fetch_models())diff --git a/plugins/model-providers/xai/__init__.py b/plugins/model-providers/xai/__init__.pyindex e1bc6adaaac..2bd79c40488 100644--- a/plugins/model-providers/xai/__init__.py+++ b/plugins/model-providers/xai/__init__.py@@ -7,7 +7,7 @@ from providers.base import LazyHeaders, ProviderProfilexai = ProviderProfile(name="xai", aliases=("grok", "x-ai", "x.ai"), api_mode="codex_responses", env_vars=("XAI_API_KEY",),base_url="https://api.x.ai/v1", auth_type="api_key",- default_headers=LazyHeaders(lambda: {"User-Agent": hermes_user_agent("Hermes-Agent")}),+ default_headers=LazyHeaders({"User-Agent": lambda: hermes_user_agent("Hermes-Agent")}),)register_provider(xai)diff --git a/providers/base.py b/providers/base.pyindex 8a423b6be62..840ae8ffa39 100644--- a/providers/base.py+++ b/providers/base.py@@ -13,7 +13,6 @@ from __future__ import annotationsimport loggingfrom dataclasses import dataclass, field-from collections.abc import Mappingfrom typing import TYPE_CHECKING, Any, Callableif TYPE_CHECKING:@@ -39,31 +38,97 @@ def _profile_user_agent() -> str:return "hermes-cli"-class LazyHeaders(Mapping[str, str]):- """``default_headers`` built on first read instead of at import.+class LazyHeaders(dict[str, str]):+ """``default_headers`` whose callable values (a User-Agent carrying the release) run on first read.- A User-Agent carrying the Hermes release resolves it from git in a source checkout, and every- CLI start imports all provider plugins (``hermes_cli.config`` lists their env vars), so headers- built at import made every command pay git subprocesses for a request it may never send.+ A source checkout resolves the release from git, and every CLI start imports all provider plugins+ (``hermes_cli.config`` lists their env vars), so headers built at import made every command pay git+ subprocesses for a request it may never send. Keys are stored up front, so ``in``/``len`` stay lazy,+ and the class stays a real ``dict``: plugins copy, merge, mutate and serialize ``default_headers``.++ Every method that reads or writes a value resolves first; ``__iter__`` is overridden so CPython's+ ``dict(x)``/``{**x}``/``f(**x)`` merge leaves its raw-storage fast path for ``keys()`` ++ ``__getitem__``, and ``json.dumps`` takes ``items()`` because the stored keys make the dict+ non-empty. Copies (``.copy()``, ``|``, ``copy``/``pickle``) are plain resolved dicts."""- def __init__(self, build: Callable[[], Mapping[str, str]]) -> None:- self._build = build- self._headers: dict[str, str] | None = None+ __slots__ = ("_pending",)++ def __init__(self, *args: Any, **kwargs: Any) -> None:+ super().__init__(*args, **kwargs)+ self._pending = any(callable(value) for value in dict.values(self))- def _resolved(self) -> dict[str, str]:- if self._headers is None:- self._headers = dict(self._build())- return self._headers+ def _resolved(self) -> LazyHeaders:+ if self._pending:+ for key, value in list(dict.items(self)):+ if callable(value):+ dict.__setitem__(self, key, value())+ self._pending = False+ return selfdef __getitem__(self, key: str) -> str:- return self._resolved()[key]+ return dict.__getitem__(self._resolved(), key)def __iter__(self):- return iter(self._resolved())+ return dict.__iter__(self._resolved())++ def __reversed__(self):+ return dict.__reversed__(self._resolved())++ def __repr__(self) -> str:+ return dict.__repr__(self._resolved())++ def __eq__(self, other: object) -> bool:+ return dict.__eq__(self._resolved(), other._resolved() if isinstance(other, LazyHeaders) else other)++ def __ne__(self, other: object) -> bool:+ equal = self.__eq__(other)+ return equal if equal is NotImplemented else not equal++ def __or__(self, other: Any) -> Any:+ return dict.__or__(self._resolved(), other)++ def __ror__(self, other: Any) -> Any:+ return dict.__or__(other, self._resolved()) if isinstance(other, dict) else NotImplemented++ def __ior__(self, other: Any) -> LazyHeaders:+ return dict.__ior__(self._resolved(), other)++ def __reduce__(self) -> tuple:+ return (dict, (dict.copy(self._resolved()),))++ def get(self, key: str, default: Any = None) -> Any:+ return dict.get(self._resolved(), key, default)++ def keys(self):+ return dict.keys(self._resolved())++ def values(self):+ return dict.values(self._resolved())++ def items(self):+ return dict.items(self._resolved())++ def copy(self) -> dict[str, str]:+ return dict.copy(self._resolved())++ def __setitem__(self, key: str, value: str) -> None:+ dict.__setitem__(self._resolved(), key, value)++ def __delitem__(self, key: str) -> None:+ dict.__delitem__(self._resolved(), key)++ def pop(self, *args: Any) -> Any:+ return dict.pop(self._resolved(), *args)++ def popitem(self) -> tuple[str, str]:+ return dict.popitem(self._resolved())++ def setdefault(self, key: str, default: Any = None) -> Any:+ return dict.setdefault(self._resolved(), key, default)- def __len__(self) -> int:- return len(self._resolved())+ def update(self, *args: Any, **kwargs: Any) -> None:+ dict.update(self._resolved(), *args, **kwargs)@dataclass@@ -163,7 +228,7 @@ class ProviderProfile:hostname: str = ""# ── Client-level quirks (set once at client construction) ─- default_headers: Mapping[str, str] = field(default_factory=dict)+ default_headers: dict[str, str] = field(default_factory=dict)# ── Request-level quirks ─────────────────────────────────# Temperature: None = use caller's default, OMIT_TEMPERATURE = don't senddiff --git a/tests/hermes_cli/test_version_info_startup_git.py b/tests/hermes_cli/test_version_info_startup_git.pyindex 547f8cae69d..b46e7e9e819 100644--- a/tests/hermes_cli/test_version_info_startup_git.py+++ b/tests/hermes_cli/test_version_info_startup_git.py@@ -61,35 +61,52 @@ def _run_logging_git(tmp_path: Path, code: str) -> tuple[dict, list[str]]:@pytest.mark.platforms("linux", "macos")-def test_provider_headers_run_no_git_until_read_and_cross_the_plugin_host(tmp_path):- # A user override copying a bundled profile inherits its lazy headers; under- # ``plugins.isolation: host`` they reach the parent only through the profile extraction.- override = tmp_path / "gmi-eu"- override.mkdir()- (override / "__init__.py").write_text(- "import dataclasses\n"- "from providers import get_provider_profile, register_provider\n"- "register_provider(dataclasses.replace(get_provider_profile('gmi'), name='gmi-eu', aliases=()))\n",- encoding="utf-8",- )[email protected]("isolation", ["in_process", "host"])+def test_provider_headers_run_no_git_until_read_and_stay_a_dict_for_overrides(tmp_path, isolation):+ # User overrides of a bundled profile, found by real discovery once installed: one inherits its+ # lazy headers as-is, one builds its own with the dict operations the documented+ # ``default_headers: dict[str, str]`` invites. Under ``plugins.isolation: host`` both run in the+ # plugin host and reach the parent only through the profile extraction.+ home = tmp_path / "home"+ home.mkdir()+ (home / "config.yaml").write_text(f"plugins:\n isolation: {isolation}\n", encoding="utf-8")+ overrides = {+ "gmi-eu": "register_provider(dataclasses.replace(base, name='gmi-eu', aliases=()))\n",+ "gmi-acct": (+ "headers = base.default_headers.copy()\n"+ "headers['X-Account'] = 'eu'\n"+ "headers = {'X-Tier': 'pro'} | (base.default_headers | headers)\n"+ "register_provider(dataclasses.replace(base, name='gmi-acct', aliases=(), default_headers=headers))\n"+ ),+ }code = (- "import json, os, hermes_cli.config, providers\n"+ "import json, os, pathlib, hermes_cli.config, providers\n""providers.list_providers()\n""log = os.environ['PATH'].split(os.pathsep)[0] + '/../git.log'\n""before = open(log, encoding='utf-8-sig').read().splitlines() if os.path.exists(log) else []\n""ua = dict(providers.get_provider_profile('fireworks').default_headers)['User-Agent']\n"+ f"for name, body in {overrides!r}.items():\n"+ " plugin = pathlib.Path(os.environ['HERMES_HOME'], 'plugins', 'model-providers', name)\n"+ " plugin.mkdir(parents=True)\n"+ " (plugin / '__init__.py').write_text('import dataclasses\\n'\n"+ " 'from providers import get_provider_profile, register_provider\\n'\n"+ " \"base = get_provider_profile('gmi')\\n\" + body)\n"+ "providers._home_layer(force_stamp_check=True)\n""from hermes_cli.version_info import get_version_info\n"- "from hermes_cli.plugin_host_profiles import load_hosted_profiles\n"- f"hosted, = load_hosted_profiles({str(override)!r}, '_hermes_user_provider_gmi_eu')\n"+ "found = {n: providers.get_provider_profile(n) for n in ('gmi-eu', 'gmi-acct')}\n""print(json.dumps({'before': before, 'ua': ua, 'base': get_version_info().base_version,\n"- " 'hosted': dict(hosted.default_headers)}))\n"+ " 'found': {n: p and dict(p.default_headers) for n, p in found.items()}}))\n")result, calls = _run_logging_git(tmp_path, code)assert result["before"] == [], "importing config + every provider plugin spawned git"- assert result["ua"] == f"HermesAgent/{result['base']}"+ ua = f"HermesAgent/{result['base']}"+ assert result["ua"] == uaassert calls, "reading the header resolves the release on demand"- assert result["hosted"] == {"User-Agent": f"HermesAgent/{result['base']}"}+ assert result["found"] == {+ "gmi-eu": {"User-Agent": ua},+ "gmi-acct": {"X-Tier": "pro", "User-Agent": ua, "X-Account": "eu"},+ }@pytest.mark.platforms("linux", "macos")diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.mdindex 9442cc979bc..0edd2982f36 100644--- a/website/docs/developer-guide/model-provider-plugin.md+++ b/website/docs/developer-guide/model-provider-plugin.md@@ -111,7 +111,7 @@ Full definition in `providers/base.py`. The most useful ones:| `fallback_models` | `tuple[str, ...]` | Curated list shown when live catalog fetch fails — in the `/model` picker AND the first-time `hermes setup` / `hermes model` API-key flow, which resolve the catalog the same way (`fetch_models()` merged curated-first with `fallback_models`; `fallback_models` alone when the fetch returns `None` or raises) || `supports_vision` | bool | Declares the provider's API accepts image content inside **tool-result** messages (a provider-wide wire capability). Per-model user-image routing comes from `model_capabilities` / models.dev, not from this flag || `model_capabilities` | `dict[str, dict[str, Any]]` | Per-model capability declarations in the `model_overrides` schema — see [Declaring model capabilities](#declaring-model-capabilities) |-| `default_headers` | `dict[str, str]` | Sent on every request (e.g. Copilot's `Editor-Version`); also forwarded by the default `fetch_models()` catalog request |+| `default_headers` | `dict[str, str]` | Sent on every request (e.g. Copilot's `Editor-Version`); also forwarded by the default `fetch_models()` catalog request. A value that is costly to compute at import (a User-Agent carrying the release) can be deferred with `providers.base.LazyHeaders({"User-Agent": lambda: hermes_user_agent("MyAgent")})`, a `dict` whose callable values run on first read (`hermes_user_agent` is in `hermes_cli.version_info`) || `fixed_temperature` | Any | `None` = use caller's value; `OMIT_TEMPERATURE` sentinel = don't send temperature at all (Kimi) || `default_max_tokens` | `int \| None` | Provider-level max_tokens cap (Nvidia: 16384) || `unsupported_response_formats` | `tuple` | `response_format` types the API rejects outright; auxiliary requests omit them instead of paying a guaranteed 400 (DeepSeek: `("json_schema",)`) |