Skip to content

The agent that grows with you

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.py
index 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_key
from 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, None
known = _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.py
new file mode 100644
index 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.py
index 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.yaml
index 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.0
author: Nous Research
+config_keys:
+ - computer_use.backend # read by the plugins/computer_use provider selector
diff --git a/plugins/kanban/dashboard/manifest.json b/plugins/kanban/dashboard/manifest.json
index 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.yaml
index bdfc1045f11..a813c34eb21 100644
--- a/plugins/memory/byterover/plugin.yaml
+++ b/plugins/memory/byterover/plugin.yaml
@@ -5,3 +5,6 @@ external_dependencies:
- name: brv
install: "curl -fsSL https://byterover.dev/install.sh | sh"
check: "brv --version"
+config_keys:
+ - memory.byterover
+ - memory.provider_config # legacy block name early docs used
diff --git a/plugins/memory/retaindb/plugin.yaml b/plugins/memory/retaindb/plugin.yaml
index 0d0ff73c834..743581cd102 100644
--- a/plugins/memory/retaindb/plugin.yaml
+++ b/plugins/memory/retaindb/plugin.yaml
@@ -3,3 +3,5 @@ version: 1.0.0
description: "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 dashboard
diff --git a/tests/hermes_cli/test_config_runtime_keys.py b/tests/hermes_cli/test_config_runtime_keys.py
new file mode 100644
index 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().out
diff --git a/tools/tool_backend_helpers.py b/tools/tool_backend_helpers.py
index 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.md
index 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]`). |