The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(config): recognize runtime-read selection and plugin-declared keys in config get/set
Tekniume402afa78325
diff --git a/hermes_cli/config.py b/hermes_cli/config.pyindex 74af83c9f4a..ba0892ef03c 100644--- a/hermes_cli/config.py+++ b/hermes_cli/config.py@@ -2977,10 +2977,12 @@ def _validate_config_key(key: str) -> tuple[bool, Optional[str]]:segments = _split_key_path(key)top = segments[0]- # A leading underscore on the FIRST segment marks an intentionally non-schema internal key- # (test harnesses/tooling); only the first segment is exempt so ``agent._max_turns`` is caught.+ # A leading ``_`` on the FIRST segment only marks an internal key (``agent._max_turns`` is caught);+ # runtime-read keys DEFAULT_CONFIG leaves unseeded come from config_runtime_keys.+ from hermes_cli.config_runtime_keys import is_runtime_read_keyfrom hermes_cli.left_core_migration import LEFT_CORE_TERMINAL_KEYS- if top.startswith("_") or top in _PLATFORM_CONTAINER_KEYS or key in LEFT_CORE_TERMINAL_KEYS:+ if top.startswith("_") or top in _PLATFORM_CONTAINER_KEYS or key in LEFT_CORE_TERMINAL_KEYS \+ or is_runtime_read_key(".".join(segments)):return True, Noneknown = _known_top_level_keys()@@ -3470,11 +3472,9 @@ def get_config_value(key: str, *, as_json: bool = False, raw: bool = False):# Phantom-key notice (#112348): a nested path under a KNOWN section that the schema does not# define (``compression.compressor.enabled``) is echoed straight from the user's file and is- # usually read by nothing, so it must not look like a live setting. The check is a- # DEFAULT_CONFIG walk and some live keys are deliberately unseeded (``browser.cloud_provider``,- # ``stt.provider``, ``gateway.proxy_url``: a stored value counts as an explicit user pick), so- # the wording hedges exactly like the set-path notice. Custom top-level keys stay exempt (they- # are bridged into os.environ for skills) and ``_validate_config_key`` already accepts+ # usually read by nothing, so it must not look like a live setting. Unseeded live keys pass via+ # config_runtime_keys; the wording still hedges like the set-path notice. Custom top-level keys+ # stay exempt (bridged into os.environ for skills) and ``_validate_config_key`` already accepts# open-subkey sections. stderr keeps stdout/--json parseable; the exit code stays 0.if _split_key_path(key)[0] in _known_top_level_keys():is_known, suggestion = _validate_config_key(key)diff --git a/hermes_cli/config_runtime_keys.py b/hermes_cli/config_runtime_keys.pynew file mode 100644index 00000000000..73860698d8a--- /dev/null+++ b/hermes_cli/config_runtime_keys.py@@ -0,0 +1,68 @@+"""Config keys the runtime reads that the DEFAULT_CONFIG walk in ``_validate_config_key`` cannot see.++Two owners supply them:++* Core selection keys (``browser.cloud_provider``, ``<category>.use_gateway``, ``stt.provider``):+ :func:`tools.tool_backend_helpers.selection_config_keys`, the table ``read_selection`` reads.+* Plugins: a ``config_keys`` list in ``plugin.yaml`` (or a dashboard plugin's+ ``dashboard/manifest.json``) names the core-section paths the plugin's code reads, e.g.+ ``memory.retaindb``. A declared path covers itself and everything below it.++Without these, ``hermes config get/set`` called live keys "not a recognized config key".+"""++from __future__ import annotations++import json+import logging+from functools import lru_cache+from pathlib import Path++from utils import fast_safe_load++logger = logging.getLogger(__name__)++# Manifest locations relative to a plugins root: flat and category plugins, plus dashboard plugins.+_MANIFEST_GLOBS = ("*/plugin.yaml", "*/plugin.yml", "*/*/plugin.yaml", "*/*/plugin.yml", "*/dashboard/manifest.json")+++def _manifest_config_keys(path: Path) -> list[str]:+ try:+ text = path.read_text(encoding="utf-8-sig")+ data = json.loads(text) if path.suffix == ".json" else fast_safe_load(text)+ except Exception as exc: # OSError, JSON/YAML parse errors: one bad plugin must not break config get+ logger.debug("config_keys: skipping unreadable manifest %s: %s", path, exc)+ return []+ raw = data.get("config_keys") if isinstance(data, dict) else None+ if not isinstance(raw, list):+ return []+ return [item.strip() for item in raw if isinstance(item, str) and item.strip()]+++@lru_cache(maxsize=8)+def _declared_keys_under(roots: tuple[str, ...]) -> frozenset[str]:+ keys: set[str] = set()+ for root in map(Path, roots):+ if not root.is_dir():+ continue+ for pattern in _MANIFEST_GLOBS:+ for manifest in root.glob(pattern):+ keys.update(_manifest_config_keys(manifest))+ return frozenset(keys)+++def plugin_declared_config_keys() -> frozenset[str]:+ """``config_keys`` declared by bundled and the active profile's user-installed plugins."""+ from hermes_cli.plugins import get_bundled_plugins_dir+ from hermes_constants import get_hermes_home++ return _declared_keys_under((str(get_bundled_plugins_dir()), str(get_hermes_home() / "plugins")))+++def is_runtime_read_key(key: str) -> bool:+ """True when ``key`` (dotted) is a core selection key or sits at/under a plugin-declared path."""+ from tools.tool_backend_helpers import selection_config_keys++ if key in selection_config_keys():+ return True+ return any(key == declared or key.startswith(declared + ".") for declared in plugin_declared_config_keys())diff --git a/hermes_cli/plugins_manifest.py b/hermes_cli/plugins_manifest.pyindex 8153f476a41..6781c71b91f 100644--- a/hermes_cli/plugins_manifest.py+++ b/hermes_cli/plugins_manifest.py@@ -35,7 +35,7 @@ _KNOWN_MANIFEST_FIELDS: set[str] = {"pip_dependencies", "provides_browser_providers", "provides_web_providers","manifest_version", "api_version", "requires_plugins", "python_dependencies", "config_schema","license", "homepage", "tags", "capabilities", "emits", "listens", "hermes", "depends",- "requires_hermes", "python_runtime", "provides_locales", "requires_auth", "oauth",+ "requires_hermes", "python_runtime", "provides_locales", "requires_auth", "oauth", "config_keys",}# Highest manifest schema version this Hermes understands.diff --git a/plugins/computer_use/cua/plugin.yaml b/plugins/computer_use/cua/plugin.yamlindex abf0826ff5d..49c8f4c97cc 100644--- a/plugins/computer_use/cua/plugin.yaml+++ b/plugins/computer_use/cua/plugin.yaml@@ -4,3 +4,5 @@ description: >-or focus. Default when computer_use.backend is unset.version: 1.0.0author: Nous Research+config_keys:+ - computer_use.backend # read by the plugins/computer_use provider selectordiff --git a/plugins/kanban/dashboard/manifest.json b/plugins/kanban/dashboard/manifest.jsonindex 8be4b8c4517..9afb565d380 100644--- a/plugins/kanban/dashboard/manifest.json+++ b/plugins/kanban/dashboard/manifest.json@@ -10,5 +10,6 @@},"entry": "dist/index.js","css": "dist/style.css",- "api": "plugin_api.py"+ "api": "plugin_api.py",+ "config_keys": ["dashboard.kanban"]}diff --git a/plugins/memory/byterover/plugin.yaml b/plugins/memory/byterover/plugin.yamlindex bdfc1045f11..a813c34eb21 100644--- a/plugins/memory/byterover/plugin.yaml+++ b/plugins/memory/byterover/plugin.yaml@@ -5,3 +5,6 @@ external_dependencies:- name: brvinstall: "curl -fsSL https://byterover.dev/install.sh | sh"check: "brv --version"+config_keys:+ - memory.byterover+ - memory.provider_config # legacy block name early docs useddiff --git a/plugins/memory/retaindb/plugin.yaml b/plugins/memory/retaindb/plugin.yamlindex 0d0ff73c834..743581cd102 100644--- a/plugins/memory/retaindb/plugin.yaml+++ b/plugins/memory/retaindb/plugin.yaml@@ -3,3 +3,5 @@ version: 1.0.0description: "RetainDB — cloud memory API with hybrid search and 7 memory types."requires_env:- RETAINDB_API_KEY+config_keys:+ - memory.retaindb # base_url / project persisted by the dashboarddiff --git a/tests/hermes_cli/test_config_runtime_keys.py b/tests/hermes_cli/test_config_runtime_keys.pynew file mode 100644index 00000000000..8565974da23--- /dev/null+++ b/tests/hermes_cli/test_config_runtime_keys.py@@ -0,0 +1,69 @@+"""`hermes config get/set` must recognize keys the runtime reads but DEFAULT_CONFIG leaves unseeded:+core provider selections (``browser.cloud_provider``, ``<category>.use_gateway``) and keys a plugin+declares through ``config_keys`` in its manifest."""++import argparse+import json+import os+from unittest.mock import patch++import pytest++from hermes_cli.config import config_command, set_config_value++NOTICE = "not a recognized config key"++[email protected](autouse=True)+def hermes_home(tmp_path):+ (tmp_path / ".env").touch()+ with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):+ yield tmp_path+++def test_config_get_browser_selection_keys_print_value_without_notice(hermes_home, capsys):+ (hermes_home / "config.yaml").write_text(+ json.dumps({"browser": {"cloud_provider": "browser-use", "use_gateway": True}}))++ for key, expected in (("browser.cloud_provider", "browser-use"), ("browser.use_gateway", True)):+ config_command(argparse.Namespace(config_command="get", key=key, json=True))+ captured = capsys.readouterr()+ assert json.loads(captured.out) == expected+ assert NOTICE not in captured.err, key++[email protected]("key,value", [+ ("browser.cloud_provider", "browserbase"), # core: tools.tool_backend_helpers.read_selection+ ("web.use_gateway", "true"), # core: legacy managed-gateway flag, every category+ ("memory.retaindb.project", "p1"), # plugin manifest: plugins/memory/retaindb+ ("dashboard.kanban.default_tenant", "t1"), # dashboard manifest: plugins/kanban/dashboard+])+def test_config_set_runtime_read_key_is_silent(key, value, hermes_home, capsys):+ set_config_value(key, value)+ out = capsys.readouterr().out+ assert f"Set {key}" in out+ assert NOTICE not in out+++def test_config_set_browser_cloud_provider_is_what_the_runtime_selects(hermes_home, capsys):+ from tools.tool_backend_helpers import read_selection++ set_config_value("browser.cloud_provider", "browserbase")+ assert read_selection("browser") == "browserbase"+ set_config_value("browser.cloud_provider", "browser-use")+ assert read_selection("browser") == "browser-use"+ assert NOTICE not in capsys.readouterr().out+++def test_user_plugin_declares_its_config_keys_in_plugin_yaml(hermes_home, capsys):+ plugin = hermes_home / "plugins" / "widget-plugin"+ plugin.mkdir(parents=True)+ (plugin / "plugin.yaml").write_text(json.dumps({"name": "widget-plugin", "config_keys": ["display.widget"]}))++ set_config_value("display.widget.size", "3")+ assert NOTICE not in capsys.readouterr().out+ # A sibling the plugin did not declare, and a typo of a core selection key, still warn.+ set_config_value("display.widgetx", "3")+ assert NOTICE in capsys.readouterr().out+ set_config_value("browser.cloud_providr", "browserbase")+ assert NOTICE in capsys.readouterr().outdiff --git a/tools/tool_backend_helpers.py b/tools/tool_backend_helpers.pyindex 3da341453aa..bd82bafeead 100644--- a/tools/tool_backend_helpers.py+++ b/tools/tool_backend_helpers.py@@ -199,6 +199,19 @@ _EXTRA_SELECTION_KEYS = {"web": ("search_backend", "extract_backend")}# pre-v52 driver choice) is not the cloud provider — excluded._SELECTION_NAME_KEYS = {"browser": ("cloud_provider",), "web": ("backend",)}_DEFAULT_NAME_KEYS = ("provider", "backend", "cloud_provider")+# Categories whose stored selection read_selection() decides (the `hermes tools` / Tool Gateway rows).+SELECTION_SECTIONS = ("web", "image_gen", "video_gen", "tts", "stt", "browser")+++def selection_config_keys() -> frozenset[str]:+ """Dotted config keys read_selection()/selection_exists() honour. DEFAULT_CONFIG leaves them+ unseeded on purpose (a stored key is the user's explicit pick), so the config-key validator+ asks here instead of walking the defaults."""+ return frozenset(+ f"{section}.{key}"+ for section in SELECTION_SECTIONS+ for key in ("use_gateway", *_SELECTION_NAME_KEYS.get(section, _DEFAULT_NAME_KEYS),+ *_EXTRA_SELECTION_KEYS.get(section, ())))def _raw_section(section: str) -> dict[str, Any] | None:diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.mdindex 7f16af6e439..bf459b63083 100644--- a/website/docs/developer-guide/plugins/index.md+++ b/website/docs/developer-guide/plugins/index.md@@ -620,6 +620,7 @@ this Hermes understands still loads with a warning.| `python_dependencies` | list of str | Declared Python requirements (e.g. `"requests>=2.0,<3"`). Installation requests consent; enabling admits the candidate through PM with the existing core, extras, and enabled-plugin union. Successful preparation publishes the environment and configuration transactionally; failure preserves the previous selection and enabled set. Declining leaves the installed plugin disabled. Pin upper bounds. || `python_runtime` | str | `external` — the plugin manages its own interpreter/venv (sidecar pattern); Hermes installs nothing and leaves any `pyproject.toml` alone. || `config_schema` | mapping | JSON-schema-ish description of keys under `plugins.entries.<id>.settings`: `api_url: {type: str, default: "", description: "...", required: false}`. Validated at load; mismatches log actionable warnings naming the key and expected type — never load failures. Types: `str`, `int`, `float`, `bool`, `list`, `dict` (plus JSON-schema aliases) and `secret`. Also drives the settings form in the Desktop Plugins tab — see [Settings form in the Desktop](#settings-form-in-the-desktop). |+| `config_keys` | list | Dotted paths in Hermes' own config sections that your code reads (e.g. `memory.retaindb`, `dashboard.kanban`). Each path covers itself and everything below it, so `hermes config get/set` recognizes those keys instead of warning "not a recognized config key". Settings for your plugin alone belong in `config_schema`; use this only for a core section your plugin reads. Dashboard plugins can declare it in `dashboard/manifest.json`. || `license` | str | SPDX-style license id (e.g. `MIT`). || `homepage` | str | Project URL. || `tags` | list of str | Free-form discovery tags (e.g. `[gateway, telegram]`). |