Skip to content

The agent that grows with you

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.py
index b01aba4a27b..f17e153c17d 100644
--- a/hermes_cli/plugin_host_child.py
+++ b/hermes_cli/plugin_host_child.py
@@ -25,7 +25,6 @@ import os
import sys
import threading
import types
-from collections import abc
from pathlib import Path
from 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()):
continue
if 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))
continue
calls[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__.py
index 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__.py
index 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__.py
index 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_agent
from providers import register_provider
from 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) -> KimiProf
return 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__.py
index 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 should
diff --git a/plugins/model-providers/router/__init__.py b/plugins/model-providers/router/__init__.py
index 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__.py
index 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, ProviderProfile
xai = 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.py
index 8a423b6be62..840ae8ffa39 100644
--- a/providers/base.py
+++ b/providers/base.py
@@ -13,7 +13,6 @@ from __future__ import annotations
import logging
from dataclasses import dataclass, field
-from collections.abc import Mapping
from typing import TYPE_CHECKING, Any, Callable
if 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 self
def __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 send
diff --git a/tests/hermes_cli/test_version_info_startup_git.py b/tests/hermes_cli/test_version_info_startup_git.py
index 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"] == ua
assert 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.md
index 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",)`) |