The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(config): address review on the config backend seam
kshitijk4poorbf9054470281
diff --git a/hermes_cli/config_backend.py b/hermes_cli/config_backend.pyindex 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_BACKENDif 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.parentdef 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).docdef 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.pyindex 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 herelogger = 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:passreturn 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.pynew file mode 100644index 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 valuediff --git a/scripts/check b/scripts/checkindex 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.pyindex 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:returnreceiver = 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 Noneif 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.pyindex 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.pyindex 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.pyindex 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_versioncfg_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