Skip to content

The agent that grows with you

fix(config): address review on the config backend seam

kshitijk4poorbf9054470281
diff --git a/hermes_cli/config_backend.py b/hermes_cli/config_backend.py
index 7a4dfb72535..fe92b25b832 100644
--- a/hermes_cli/config_backend.py
+++ b/hermes_cli/config_backend.py
@@ -148,6 +148,22 @@ class FileBackend:
_FILE_BACKEND = FileBackend()
+def _dotenv_backend_override() -> Optional[str]:
+ """``HERMES_CONFIG_BACKEND`` as the launch home's ``.env`` then the managed ``.env`` set it
+ (both load with override), or None. Consulted only on the refusal path."""
+ try:
+ from agent.secret_scope import load_env_file
+ from hermes_cli import managed_scope
+ from hermes_constants import get_process_hermes_home
+ except ImportError: # a bare tree without the dotenv stack (pm runtime fixtures) has no .env layer
+ return None
+ value = load_env_file(get_process_hermes_home() / ".env").get(BACKEND_ENV)
+ managed_dir = managed_scope.get_managed_dir()
+ if managed_dir is not None:
+ value = load_env_file(managed_dir / ".env").get(BACKEND_ENV, value)
+ return value
+
+
def get_config_backend() -> ConfigBackend:
"""The backend selected by ``HERMES_CONFIG_BACKEND`` (default ``file``).
@@ -155,6 +171,10 @@ def get_config_backend() -> ConfigBackend:
select it (D11). Raises :class:`ConfigBackendUnavailable` for a backend this build lacks.
"""
kind = os.environ.get(BACKEND_ENV, "").strip().lower() or "file"
+ if kind != "file":
+ # A config read can run before load_hermes_dotenv() (hermes_cli.config reads at import time):
+ # refuse only a value the launch home's .env / managed .env do not override, as that load will.
+ kind = (_dotenv_backend_override() or kind).strip().lower() or "file"
if kind == "file":
return _FILE_BACKEND
if kind == "remote":
@@ -164,65 +184,72 @@ def get_config_backend() -> ConfigBackend:
raise ConfigBackendUnavailable(f"{BACKEND_ENV}={kind!r} is not a config backend (expected 'file').")
-def _route(config_path: PathLike) -> Tuple[Any, Path, bool]:
- """``(backend, home_or_path, is_user_layer)`` for a config path.
+class _ExplicitFile(FileBackend):
+ """A config file that is not a home's user layer (a test fixture, an import source): the file
+ backend's behaviour on that exact path, whichever backend is selected."""
+
+ def __init__(self, path: Path):
+ self._path = path
+
+ def config_path(self, home: Path) -> Path:
+ return self._path
+
+
+def _route(config_path: PathLike) -> Tuple[ConfigBackend, Path]:
+ """``(backend, home)`` serving a config path through the one ``ConfigBackend`` surface.
``<home>/config.yaml`` is that home's user layer and goes to the selected backend. Any other
- file name is an explicit file (a test fixture, an import source), not a user layer: it is read
- and written with the file backend's primitives regardless of the selected backend.
+ file name is an explicit file, served by the file backend on that path.
"""
path = Path(config_path)
if path.name == CONFIG_FILENAME:
- return get_config_backend(), path.parent, True
- return _FILE_BACKEND, path, False
+ return get_config_backend(), path.parent
+ return _ExplicitFile(path), path.parent
def read_config_doc(config_path: PathLike) -> Any:
"""Parsed root of a config file (None when empty); raises like ``open`` + ``fast_safe_load``."""
- backend, target, is_layer = _route(config_path)
- return backend.read_user_layer(target).doc if is_layer else backend.read_path(target)
+ backend, home = _route(config_path)
+ return backend.read_user_layer(home).doc
def read_config_doc_readonly(config_path: PathLike) -> Any:
"""Signature-cached :func:`read_config_doc`; the result is shared — never mutate it."""
- backend, target, is_layer = _route(config_path)
- return backend.read_user_doc_readonly(target) if is_layer else backend.read_path_readonly(target)
+ backend, home = _route(config_path)
+ return backend.read_user_doc_readonly(home)
def config_version(config_path: PathLike) -> Tuple[Any, ...]:
"""Cache signature of a config file; raises ``FileNotFoundError`` / ``OSError`` like ``stat``."""
- backend, target, is_layer = _route(config_path)
- return backend.version(target) if is_layer else backend.version_path(target)
+ backend, home = _route(config_path)
+ return backend.version(home)
def probe_config_readable(config_path: PathLike) -> None:
"""Raise ``OSError`` while a local config file cannot be opened; no parse. A non-file user
- layer has no local read to fail, so only explicit files and the file backend probe."""
- backend, target, is_layer = _route(config_path)
- if is_layer and not backend.supports_file_tooling():
- return
- path = backend.config_path(target) if is_layer else target
- with open(path, "rb") as f:
- f.read(1)
+ layer has no local read to fail."""
+ backend, home = _route(config_path)
+ if isinstance(backend, FileBackend):
+ path = backend.config_path(home)
+ with open(path, "rb") as f:
+ f.read(1)
def config_exists(config_path: PathLike) -> bool:
- backend, target, is_layer = _route(config_path)
- return backend.exists(target) if is_layer else target.exists()
+ backend, home = _route(config_path)
+ return backend.exists(home)
def write_config_document(config_path: PathLike, document: dict, *, extra_content_on_create: Optional[str] = None) -> None:
"""Replace a config file's document (comment-preserving merge for the file backend)."""
- backend, target, is_layer = _route(config_path)
- changes = Changes(document=document, extra_content_on_create=extra_content_on_create)
- backend.write_changes(target, changes) if is_layer else backend.write_path(target, changes)
+ backend, home = _route(config_path)
+ backend.write_changes(home, Changes(document=document, extra_content_on_create=extra_content_on_create))
def write_config_key(config_path: PathLike, key_path: str, value: Any) -> None:
"""Set one dotted key (``None`` removes it) — ``atomic_roundtrip_yaml_update`` semantics."""
- backend, target, is_layer = _route(config_path)
- changes = Changes(unset=(key_path,)) if value is None else Changes(set={key_path: value})
- backend.write_changes(target, changes) if is_layer else backend.write_path(target, changes)
+ backend, home = _route(config_path)
+ backend.write_changes(home, Changes(unset=(key_path,)) if value is None else Changes(set={key_path: value}))
def supports_file_tooling() -> bool:
diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py
index ea4ef50fe64..13c5f745f68 100644
--- a/hermes_cli/profiles.py
+++ b/hermes_cli/profiles.py
@@ -25,6 +25,7 @@ from hermes_constants import (
named_profile_has_identity, named_profile_is_deleted, named_profile_is_live,
)
from hermes_cli.config_backend import config_exists, config_version, require_file_tooling
+from hermes_cli.profiles_cache import _PROFILE_FILE_CACHE, _cached_profile_read, _config_version_or_none # noqa: F401 _PROFILE_FILE_CACHE: tests clear it here
logger = logging.getLogger(__name__)
@@ -706,43 +707,6 @@ def _load_yaml_dict(path: Path) -> Optional[dict]:
return data if isinstance(data, dict) else None
-# (path, kind) -> (file signature, the small derived value). `list_profiles` re-reads three YAML
-# files PER PROFILE, and it is the shared body of `GET /api/profiles` and `profiles.list`, which the
-# Bots roster polls every 5s per connection — so an installer-seeded config.yaml (the annotated
-# template, ~119KB) was re-parsed for every bot every five seconds to yield the same two strings.
-# Only DERIVED values are cached, never a document a caller could write back: the raw readers
-# (`read_user_config_raw`, `_load_yaml_dict`) keep their uncached contract. See #117378.
-_PROFILE_FILE_CACHE: dict[tuple, tuple] = {}
-_PROFILE_FILE_CACHE_MAX = 512
-
-
-def _profile_file_signature(path: Path) -> Optional[tuple]:
- """``(mtime_ns, size, inode)``, or None when the file is absent. The atomic writers rename a
- temp file into place, so a rewrite always lands a new inode even within one mtime tick."""
- try:
- stat = path.stat()
- except OSError:
- return None
- return (stat.st_mtime_ns, stat.st_size, stat.st_ino)
-
-
-def _cached_profile_read(path: Path, kind: str, compute):
- """``compute()``'s value, reused while *path* has not changed. A missing file is never cached:
- reading it costs nothing, and one created later must be picked up."""
- signature = _profile_file_signature(path)
- if signature is None:
- return compute()
- key = (str(path), kind)
- cached = _PROFILE_FILE_CACHE.get(key)
- if cached is not None and cached[0] == signature:
- return cached[1]
- value = compute()
- if len(_PROFILE_FILE_CACHE) >= _PROFILE_FILE_CACHE_MAX:
- _PROFILE_FILE_CACHE.clear()
- _PROFILE_FILE_CACHE[key] = (signature, value)
- return value
-
-
def _read_distribution_meta(profile_dir: Path) -> tuple:
"""``(name, version, source)`` from ``distribution.yaml``; ``(None, None, None)`` if absent."""
def _read() -> tuple:
@@ -773,7 +737,7 @@ def _read_config_model(profile_dir: Path) -> tuple:
pass
return None, None
- return _cached_profile_read(config_path, "config-model", _read)
+ return _cached_profile_read(config_path, "config-model", _read, _config_version_or_none)
def _seed_model_config(profile_dir: Path) -> None:
diff --git a/hermes_cli/profiles_cache.py b/hermes_cli/profiles_cache.py
new file mode 100644
index 00000000000..3a80963c0c6
--- /dev/null
+++ b/hermes_cli/profiles_cache.py
@@ -0,0 +1,52 @@
+"""The per-profile derived-value cache behind ``list_profiles`` (``hermes_cli.profiles``)."""
+
+from pathlib import Path
+from typing import Dict, Optional
+
+from hermes_cli.config_backend import config_version
+
+
+# (path, kind) -> (file signature, the small derived value). `list_profiles` re-reads three YAML
+# files PER PROFILE, and it is the shared body of `GET /api/profiles` and `profiles.list`, which the
+# Bots roster polls every 5s per connection — so an installer-seeded config.yaml (the annotated
+# template, ~119KB) was re-parsed for every bot every five seconds to yield the same two strings.
+# Only DERIVED values are cached, never a document a caller could write back: the raw readers
+# (`read_user_config_raw`, `_load_yaml_dict`) keep their uncached contract. See #117378.
+_PROFILE_FILE_CACHE: Dict[tuple, tuple] = {}
+_PROFILE_FILE_CACHE_MAX = 512
+
+
+def _profile_file_signature(path: Path) -> Optional[tuple]:
+ """``(mtime_ns, size, inode)``, or None when the file is absent. The atomic writers rename a
+ temp file into place, so a rewrite always lands a new inode even within one mtime tick."""
+ try:
+ stat = path.stat()
+ except OSError:
+ return None
+ return (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+
+
+def _config_version_or_none(path: Path) -> Optional[tuple]:
+ """The config backend's version of a profile's config.yaml (None when absent): the user layer
+ changes through the backend, not necessarily on local disk."""
+ try:
+ return config_version(path)
+ except OSError:
+ return None
+
+
+def _cached_profile_read(path: Path, kind: str, compute, signature_of=_profile_file_signature):
+ """``compute()``'s value, reused while ``signature_of(path)`` is unchanged. A missing file is never
+ cached: reading it costs nothing, and one created later must be picked up."""
+ signature = signature_of(path)
+ if signature is None:
+ return compute()
+ key = (str(path), kind)
+ cached = _PROFILE_FILE_CACHE.get(key)
+ if cached is not None and cached[0] == signature:
+ return cached[1]
+ value = compute()
+ if len(_PROFILE_FILE_CACHE) >= _PROFILE_FILE_CACHE_MAX:
+ _PROFILE_FILE_CACHE.clear()
+ _PROFILE_FILE_CACHE[key] = (signature, value)
+ return value
diff --git a/scripts/check b/scripts/check
index 783553041f6..8b0cba124ce 100755
--- a/scripts/check
+++ b/scripts/check
@@ -106,6 +106,7 @@ _GUARDS = {
"shebangs": ["scripts/check_bash_shebangs.py"],
"no-tmp": ["scripts/check_no_tmp_literals.py"],
"config-writers": ["scripts/check_config_yaml_writers.py"],
+ "config-readers": ["scripts/check_config_yaml_readers.py"],
"os-marker-fakes": ["scripts/ci/check_os_marker_fakes.py"],
"agents-md": ["scripts/ci/check_agents_md_size.py"],
"case-collisions": ["scripts/check-case-collisions.py"],
diff --git a/scripts/check_config_yaml_readers.py b/scripts/check_config_yaml_readers.py
index 24962fc24fa..79b34b7e404 100644
--- a/scripts/check_config_yaml_readers.py
+++ b/scripts/check_config_yaml_readers.py
@@ -67,6 +67,7 @@ FUNC_READS = {
"load_all", "compose", "compose_all",
# Byte reads and file copies of the user layer (pm snapshots/digests, shutil.copy*).
"read_bytes_or_none", "file_digest", "copy", "copy2", "copyfile"}
+PATH_KEYWORDS = {"file", "path", "filename", "stream", "src", "fp"}
BYPASS_WRITERS = {"atomic_roundtrip_yaml_update", "atomic_roundtrip_yaml_save", "atomic_write_text"}
YAML_HELPER_RE = re.compile(r"(load|read)_yaml|yaml_(load|read)")
@@ -167,7 +168,9 @@ class _Scanner:
if name is None:
return
receiver = node.func.value if isinstance(node.func, ast.Attribute) else None
- first = node.args[0] if node.args else None
+ # The path is the first positional argument, or a path-bearing keyword (`open(file=p)`).
+ first = node.args[0] if node.args else next(
+ (k.value for k in node.keywords if k.arg in PATH_KEYWORDS), None)
if name in BYPASS_WRITERS and first is not None and self.is_config_path(first, names):
self.flag(node, f"bypass write of a config path ({self.seg(first)})")
return
@@ -182,7 +185,10 @@ class _Scanner:
is_reader = name in FUNC_READS or YAML_HELPER_RE.search(name) is not None
if name == "load" and receiver is not None and "yaml" in self.seg(receiver).lower():
is_reader = True
- if is_reader and first is not None and (receiver is None or name != "open") and self.is_config_path(first, names):
+ # `p.open()` is a Path method (handled above); `io.open(p)` / `builtins.open(p)` are the builtin.
+ qualified_builtin = isinstance(receiver, ast.Name) and receiver.id in {"io", "builtins", "os"}
+ if (is_reader and first is not None and (receiver is None or name != "open" or qualified_builtin)
+ and self.is_config_path(first, names)):
self.flag(node, f"direct {name}() of a config path ({self.seg(first)[:60]})")
def scan(self) -> list[str]:
diff --git a/tests/hermes_cli/test_config_backend.py b/tests/hermes_cli/test_config_backend.py
index 74ca5fe41ec..080ed5044f3 100644
--- a/tests/hermes_cli/test_config_backend.py
+++ b/tests/hermes_cli/test_config_backend.py
@@ -34,6 +34,13 @@ class TestSelection:
with pytest.raises(cb.ConfigBackendUnavailable):
cb.read_config_doc(home / "config.yaml")
+ def test_launch_env_file_overrides_a_stale_shell_value_before_dotenv_loads(self, home, monkeypatch):
+ # A config read can precede load_hermes_dotenv(); the launch home's .env wins, as that load will.
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ monkeypatch.setenv(cb.BACKEND_ENV, "remote")
+ (home / ".env").write_text(f"{cb.BACKEND_ENV}=file\n", encoding="utf-8")
+ assert cb.get_config_backend().name == "file"
+
def test_explicit_non_config_file_ignores_backend(self, home, monkeypatch):
other = home / "import-source.yaml"
other.write_text("a: 1\n", encoding="utf-8")
@@ -247,6 +254,9 @@ class TestReaderGate:
"p = home / 'config.yaml'\n return Path.read_text(p)",
"p = home / 'config.yaml'\n shutil.copy2(p, home / 'bak')",
"return read_bytes_or_none(home / 'config.yaml')",
+ "p = home / 'config.yaml'\n return io.open(p)",
+ "p = home / 'config.yaml'\n return builtins.open(p)",
+ "p = home / 'config.yaml'\n return open(file=p)",
])
def test_every_binding_form_is_tracked(self, tmp_path, body):
# Tuple unpacking, attributes, loop targets, unbound Path methods, copies, byte reads.
diff --git a/tests/hermes_cli/test_profile_listing_cache.py b/tests/hermes_cli/test_profile_listing_cache.py
index 86560835295..e0c7a409cb5 100644
--- a/tests/hermes_cli/test_profile_listing_cache.py
+++ b/tests/hermes_cli/test_profile_listing_cache.py
@@ -84,3 +84,16 @@ def test_the_raw_config_reader_keeps_its_uncached_contract(profile_dir):
config_path.write_text("model:\n provider: xai\n default: grok-4.6\n", encoding="utf-8")
assert read_user_config_raw(config_path)["model"]["provider"] == "xai"
+
+
+def test_config_model_cache_is_keyed_on_the_backend_version_not_the_local_file(profile_dir, monkeypatch):
+ """The user layer changes through the config backend, which need not touch the local file."""
+ from hermes_cli import config_backend, profiles_cache
+
+ assert profiles._read_config_model(profile_dir) == ("gpt-4o", "openai")
+ version = [("v2",)]
+ monkeypatch.setattr(profiles_cache, "config_version", lambda path: version[0])
+ monkeypatch.setattr(config_backend.FileBackend, "read_user_layer", lambda self, home: config_backend.UserLayer(
+ doc={"model": {"provider": "anthropic", "default": "claude-opus-4.6"}}, version=version[0]))
+
+ assert profiles._read_config_model(profile_dir) == ("claude-opus-4.6", "anthropic")
diff --git a/tui_gateway/methods_config.py b/tui_gateway/methods_config.py
index ac34f7c6134..66d0aa2c174 100644
--- a/tui_gateway/methods_config.py
+++ b/tui_gateway/methods_config.py
@@ -243,12 +243,24 @@ def _cfg_get_thinking_mode(params):
return {"value": raw}
+def _version_token(version) -> float:
+ """A non-zero number that changes with ``version`` (0 = no config yet, as before)."""
+ if not version:
+ return 0
+ if isinstance(version[0], int):
+ return version[0] / 1_000_000_000
+ import zlib
+ return float(zlib.crc32(repr(version).encode("utf-8")) or 1)
+
+
def _cfg_get_mtime(params):
from hermes_cli.config_backend import config_exists, config_version
cfg_path = _hermes_home / "config.yaml"
try:
- # The client only compares for change; the file backend's version leads with st_mtime_ns.
- mtime = config_version(cfg_path)[0] / 1_000_000_000 if config_exists(cfg_path) else 0
+ # The client only compares successive values for change: a numeric token derived from the
+ # backend's opaque version (the file backend's leads with st_mtime_ns, kept as seconds).
+ version = config_version(cfg_path) if config_exists(cfg_path) else None
+ mtime = _version_token(version)
except Exception:
return {"mtime": 0}
# mcp_rev: hash of the MCP-relevant sections so the poller reloads MCP servers only when