The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(config): config_keys come from the loader's discovery, count only for active plugins, never widen a section
Tekniume1be6fcfe02e
diff --git a/hermes_cli/agent_plugins.py b/hermes_cli/agent_plugins.pyindex 64205785b04..6cece2b2621 100644--- a/hermes_cli/agent_plugins.py+++ b/hermes_cli/agent_plugins.py@@ -520,13 +520,19 @@ def load_agent_plugin(plugin_root: Path, data_root: Path) -> AgentPluginPackage:)-def manifest_config_schema(manifest: Any) -> Any:- """Raw ``extensions.com.nousresearch.hermes.config_schema`` of a parsed ``plugin.json`` (Agent- Plugins v1 forbids unknown top-level fields), else ``None``. Unvalidated: the settings form- filters it, the loader and ``plugins validate`` report what is malformed."""+def manifest_hermes_extension(manifest: Any) -> dict:+ """``extensions.com.nousresearch.hermes`` of a parsed ``plugin.json`` (Agent Plugins v1 forbids+ unknown top-level fields, so Hermes-specific fields such as ``config_keys`` live here), else ``{}``."""extensions = manifest.get("extensions") if isinstance(manifest, dict) else Nonehermes = extensions.get(_HERMES_EXTENSION) if isinstance(extensions, dict) else None- return hermes.get("config_schema") if isinstance(hermes, dict) else None+ return hermes if isinstance(hermes, dict) else {}+++def manifest_config_schema(manifest: Any) -> Any:+ """Raw ``extensions.com.nousresearch.hermes.config_schema`` of a parsed ``plugin.json``, else+ ``None``. Unvalidated: the settings form filters it, the loader and ``plugins validate`` report+ what is malformed."""+ return manifest_hermes_extension(manifest).get("config_schema")def read_agent_plugin_manifest(plugin_root: Path) -> tuple[dict, tuple[AgentPluginDiagnostic, ...]]:diff --git a/hermes_cli/config.py b/hermes_cli/config.pyindex ba0892ef03c..32122a7a97d 100644--- a/hermes_cli/config.py+++ b/hermes_cli/config.py@@ -2963,26 +2963,25 @@ def _suggest_closest_key(key: str, candidates: set[str], cutoff: float = 0.6) ->def _validate_config_key(key: str) -> tuple[bool, Optional[str]]:- """Validate a dotted config-key path against the known schema -> ``(is_known, suggestion)``.+ """Dotted config-key path -> ``(is_known, suggestion)``: the schema walk, then (only for a refused key)+ the runtime-read keys DEFAULT_CONFIG leaves unseeded (config_runtime_keys)."""+ known, suggestion = _validate_schema_key(key)+ if known or not key:+ return known, suggestion+ from hermes_cli.config_runtime_keys import is_runtime_read_key+ return (True, None) if is_runtime_read_key(".".join(_split_key_path(key))) else (False, suggestion)- Headline case from #34067: ``gateway.discord.gateway_restart_notification`` was silently written, even- though ``gateway`` only has 4 known sub-keys (``strict``, ``media_delivery_allow_dirs``,- ``trust_recent_files``, ``trust_recent_files_seconds``). The correct path is- ``discord.gateway_restart_notification`` (platform configs live at the top level, not under a- ``platforms`` namespace).- """++def _validate_schema_key(key: str) -> tuple[bool, Optional[str]]:+ """#34067: ``gateway.discord.gateway_restart_notification`` was silently written; the correct path is+ ``discord.gateway_restart_notification`` (platform configs live at the top level)."""if not key:return False, None-segments = _split_key_path(key)top = segments[0]-- # 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+ # A leading ``_`` on the FIRST segment only marks an internal key (``agent._max_turns`` is caught).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 \- or is_runtime_read_key(".".join(segments)):+ if top.startswith("_") or top in _PLATFORM_CONTAINER_KEYS or key in LEFT_CORE_TERMINAL_KEYS:return True, Noneknown = _known_top_level_keys()diff --git a/hermes_cli/config_runtime_keys.py b/hermes_cli/config_runtime_keys.pyindex 4581d0b24d0..d1e67bc9904 100644--- a/hermes_cli/config_runtime_keys.py+++ b/hermes_cli/config_runtime_keys.py@@ -1,73 +1,109 @@"""Config keys the runtime reads that the DEFAULT_CONFIG walk in ``_validate_config_key`` cannot see.-Two owners supply them:+``_validate_config_key`` asks here only AFTER the schema walk refused a key, so nothing here can+override a schema verdict; it only vouches for an exact path (and what is below it) a reader uses.+Three 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".+ :func:`tools.tool_backend_helpers.selection_config_keys`, built from ``read_selection``'s tables.+* Core-owned unseeded keys outside that table, each listed with its reader (:data:`CORE_RUNTIME_KEYS`).+* ACTIVE plugins: a ``config_keys`` list in ``plugin.yaml`` (or ``extensions.com.nousresearch.hermes``+ in a portable ``plugin.json``) names core-section paths the plugin's code reads, e.g.+ ``memory.retaindb``. Plugins are found and gated by the loader's own discovery+ (``plugins_discovery``), plus the memory provider ``memory.provider`` selects. A declared path is+ at least two segments deep, is ignored when DEFAULT_CONFIG already defines it, and covers itself+ and everything below it.++Nothing is cached: the lookup runs only for a key the schema refused, and a plugin installed or+enabled in a long-running process must count on the next ``config get/set``."""from __future__ import annotations-import jsonimport logging-from functools import lru_cache-from pathlib import Path--import hermes_yaml as yaml-from utils import fast_safe_load+from collections.abc import Iterable, Iteratorlogger = 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 (OSError, ValueError, yaml.YAMLError) as exc: # one bad manifest 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)+# Core-owned keys read at runtime but deliberately absent from DEFAULT_CONFIG -> their reader.+CORE_RUNTIME_KEYS: dict[str, str] = {+ "computer_use.backend": "plugins/computer_use/__init__.py configured_backend_name() (unset = cua)",+ "dashboard.kanban": "plugins/kanban/dashboard/plugin_api.py (bundled dashboard tab preferences)",+}-def plugin_declared_config_keys() -> frozenset[str]:- """``config_keys`` declared by bundled, the active profile's user-installed and (opt-in) project plugins."""- from hermes_cli import plugins as _plugins- from hermes_constants import get_hermes_home+def _covered(key: str, paths: Iterable[str]) -> bool:+ return any(key == path or key.startswith(path + ".") for path in paths)+++def _in_default_config(path: str) -> bool:+ from hermes_cli.config import DEFAULT_CONFIG++ node = DEFAULT_CONFIG+ for segment in path.split("."):+ if not isinstance(node, dict) or segment not in node:+ return False+ node = node[segment]+ return True+++def _selected_memory_provider_manifest():+ """Manifest of the memory provider ``memory.provider`` selects. Memory providers are ``exclusive``+ plugins: the general gate never enables them, the selection does."""+ from hermes_cli.config import cfg_get, load_config+ from hermes_cli.plugins_manifest import parse_manifest_file- roots = [str(_plugins.get_bundled_plugins_dir()), str(get_hermes_home() / "plugins")]- # Same opt-in gate and directory as plugins_discovery.collect_directory_manifests.- if _plugins._env_enabled("HERMES_ENABLE_PROJECT_PLUGINS"):- roots.append(str(Path.cwd() / ".hermes" / "plugins"))- return _declared_keys_under(tuple(roots))+ name = cfg_get(load_config(), "memory", "provider")+ if not isinstance(name, str) or not name.strip():+ return None+ from plugins.memory import find_provider_dir++ provider_dir = find_provider_dir(name.strip())+ if provider_dir is None:+ return None+ manifest_file = next((f for f in (provider_dir / "plugin.yaml", provider_dir / "plugin.yml") if f.exists()), None)+ return parse_manifest_file(manifest_file, provider_dir, "memory", "memory") if manifest_file else None+++def _active_manifests() -> Iterator:+ """Manifests of the plugins the loader would activate, by its own discovery, precedence and gate."""+ from hermes_cli.plugins_discovery import (+ _get_disabled_plugins, _get_enabled_plugins, collect_directory_manifests, discover_entrypoint_manifests,+ gate_manifest, resolve_manifest_winners,+ )+ from hermes_cli.plugins_manifest import manifest_key, requires_hermes_error++ manifests = collect_directory_manifests()+ # Same merge as PluginManager._discover_and_load_inner: a directory install keeps its identity.+ directory_keys = {manifest_key(m) for m in manifests}+ manifests += [m for m in discover_entrypoint_manifests() if manifest_key(m) not in directory_keys]+ disabled, enabled = _get_disabled_plugins(), _get_enabled_plugins()+ for manifest in resolve_manifest_winners(manifests).values():+ verdict = gate_manifest(manifest, disabled, enabled)+ if (verdict.action != "placeholder" or verdict.enabled) and requires_hermes_error(manifest) is None:+ yield manifest+ memory = _selected_memory_provider_manifest()+ if memory is not None:+ yield memory+++def plugin_declared_config_keys() -> frozenset[str]:+ """``config_keys`` declared by active plugins, minus paths DEFAULT_CONFIG already defines."""+ keys = set()+ for manifest in _active_manifests():+ for path in manifest.config_keys:+ if _in_default_config(path):+ logger.debug("config_keys: ignoring %s from plugin %s (a DEFAULT_CONFIG key)", path, manifest.name)+ else:+ keys.add(path)+ return frozenset(keys)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."""+ """True when ``key`` (dotted) is a core selection key, a core runtime key, or sits at/under a path+ an active plugin declares. Call only for a key the schema walk refused."""from tools.tool_backend_helpers import selection_config_keys- if key in selection_config_keys():+ if key in selection_config_keys() or _covered(key, CORE_RUNTIME_KEYS):return True- return any(key == declared or key.startswith(declared + ".") for declared in plugin_declared_config_keys())+ return _covered(key, plugin_declared_config_keys())diff --git a/hermes_cli/plugins_manifest.py b/hermes_cli/plugins_manifest.pyindex 6781c71b91f..22ecbc213b6 100644--- a/hermes_cli/plugins_manifest.py+++ b/hermes_cli/plugins_manifest.py@@ -107,6 +107,19 @@ def _manifest_list(data: Mapping, key: str, field_name: str, what: str, coerce:return out+def _config_key_path(item: object) -> Optional[str]:+ """A ``config_keys`` entry: a dotted path at least two segments deep (``memory.retaindb``), else None.+ A bare section (``agent``) would silence typo notices for the whole section."""+ parts = item.strip().split(".") if isinstance(item, str) else []+ return ".".join(parts) if len(parts) >= 2 and all(parts) else None+++def manifest_config_keys(data: Mapping, key: str) -> list[str]:+ """Validated ``config_keys`` of a manifest mapping (malformed entries warn and are skipped)."""+ return _manifest_list(data, key, "config_keys", "a list of dotted config paths", _config_key_path,+ "Plugin %s: config_keys entry %r must be a dotted path at least two levels deep; skipping")++def _dependency_entry(item: object) -> Optional[dict[str, Any]]:"""``{id, version_range}`` from a requires_plugins item (str shorthand ok); None when malformed."""if isinstance(item, str):@@ -175,6 +188,7 @@ def _parse_manifest_v2_fields(data: Mapping, key: str) -> dict[str, Any]:)schema = _config_schema_entries(key, _manifest_field_of_type(data, key, "config_schema", Mapping, "a mapping"))tags = [str(t) for t in (_manifest_field_of_type(data, key, "tags", list, "a list") or [])]+ config_keys = manifest_config_keys(data, key)# Forward compat: unknown fields warn (never fail); v1 manifests only at debug.unknown = sorted(set(data.keys()) - _KNOWN_MANIFEST_FIELDS)if unknown:@@ -185,7 +199,7 @@ def _parse_manifest_v2_fields(data: Mapping, key: str) -> dict[str, Any]:return {"manifest_version": mv, "api_version": api, "requires_plugins": deps, "python_dependencies": pydeps,"config_schema": schema, "license": str(data.get("license") or ""),- "homepage": str(data.get("homepage") or ""), "tags": tags,+ "homepage": str(data.get("homepage") or ""), "tags": tags, "config_keys": config_keys,}@@ -400,6 +414,9 @@ class PluginManifest:# ``{endonym, rtl}`` from the mapping form of a ``provides_locales`` entry.provides_locales: list[str] = field(default_factory=list)locale_metadata: dict[str, dict[str, Any]] = field(default_factory=dict)+ # Dotted paths in Hermes' own config sections the plugin reads (``memory.retaindb``), so+ # ``hermes config get/set`` recognizes them while the plugin is active (hermes_cli/config_runtime_keys.py).+ config_keys: list[str] = field(default_factory=list)def parse_provides_locales(raw: Any, key: str = "") -> tuple[list[str], dict[str, dict[str, Any]]]:@@ -495,7 +512,7 @@ def requires_hermes_error(manifest: PluginManifest | Mapping[str, Any]) -> Optiodef portable_plugin_manifest(child: Path, source: str, prefix: str) -> PluginManifest:"""Build the manifest for a portable Agent Plugin directory (``plugin.json``); diagnostics warn."""- from hermes_cli.agent_plugins import manifest_config_schema, read_agent_plugin_manifest+ from hermes_cli.agent_plugins import manifest_config_schema, manifest_hermes_extension, read_agent_plugin_manifestdata, diagnostics = read_agent_plugin_manifest(child)for diagnostic in diagnostics:logger.warning("Agent Plugin '%s': %s", child, diagnostic.message)@@ -505,6 +522,7 @@ def portable_plugin_manifest(child: Path, source: str, prefix: str) -> PluginManauthor=_display_author(data.get("author", "")), source=source, path=str(child), key=key,portable=True, data_namespace=_portable_data_namespace(key),config_schema=_config_schema_entries(key, manifest_config_schema(data)),+ config_keys=manifest_config_keys(manifest_hermes_extension(data), key),)diff --git a/plugins/computer_use/cua/plugin.yaml b/plugins/computer_use/cua/plugin.yamlindex 49c8f4c97cc..abf0826ff5d 100644--- a/plugins/computer_use/cua/plugin.yaml+++ b/plugins/computer_use/cua/plugin.yaml@@ -4,5 +4,3 @@ 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 9afb565d380..8be4b8c4517 100644--- a/plugins/kanban/dashboard/manifest.json+++ b/plugins/kanban/dashboard/manifest.json@@ -10,6 +10,5 @@},"entry": "dist/index.js","css": "dist/style.css",- "api": "plugin_api.py",- "config_keys": ["dashboard.kanban"]+ "api": "plugin_api.py"}diff --git a/tests/hermes_cli/test_config_runtime_keys.py b/tests/hermes_cli/test_config_runtime_keys.pyindex 7b94430a61d..79884504f23 100644--- a/tests/hermes_cli/test_config_runtime_keys.py+++ b/tests/hermes_cli/test_config_runtime_keys.py@@ -1,6 +1,7 @@"""`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."""+core provider selections (``browser.cloud_provider``, ``<category>.use_gateway``), core-owned keys with+a known reader (``computer_use.backend``), and keys an ACTIVE plugin declares through ``config_keys``.+Declarations never weaken the schema's typo notices."""import argparseimport json@@ -16,14 +17,36 @@ NOTICE = "not a recognized config key"@pytest.fixture(autouse=True)def hermes_home(tmp_path):- (tmp_path / ".env").touch()- with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):- yield tmp_path+ home = tmp_path / "hermes"+ home.mkdir()+ (home / ".env").touch()+ with patch.dict(os.environ, {"HERMES_HOME": str(home)}):+ os.environ.pop("HERMES_ENABLE_PROJECT_PLUGINS", None)+ yield home+++def _write_config(home, data):+ (home / "config.yaml").write_text(json.dumps(data))+++def _plugin(root, name, config_keys, init_source=None):+ plugin = root / name+ plugin.mkdir(parents=True)+ (plugin / "plugin.yaml").write_text(json.dumps({"name": name, "config_keys": config_keys}))+ if init_source is not None:+ (plugin / "__init__.py").write_text(init_source)+ return plugin+++def _set_notice(key, value, capsys):+ set_config_value(key, value)+ out = capsys.readouterr().out+ assert f"Set {key}" in out+ return NOTICE in outdef 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}}))+ _write_config(hermes_home, {"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))@@ -35,48 +58,87 @@ def test_config_get_browser_selection_keys_print_value_without_notice(hermes_hom@pytest.mark.parametrize("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+ ("dashboard.kanban.default_tenant", "t1"), # core: bundled kanban dashboard preferences])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+ assert not _set_notice(key, value, capsys)-def test_config_set_browser_cloud_provider_is_what_the_runtime_selects(hermes_home, capsys):- from tools.tool_backend_helpers import read_selection+def test_every_selection_category_key_set_is_what_read_selection_returns(hermes_home, capsys):+ from tools.tool_backend_helpers import read_selection, selection_config_keys- 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+ name_keys: dict[str, set] = {}+ for dotted in selection_config_keys():+ section, key = dotted.split(".")+ name_keys.setdefault(section, set()).add(key)+ # Every `hermes tools` / Tool Gateway category read_selection serves.+ assert {"web", "image_gen", "video_gen", "tts", "stt", "browser"} <= set(name_keys)+ for section, keys in name_keys.items():+ key = next(k for k in ("cloud_provider", "backend", "provider") if k in keys)+ _write_config(hermes_home, {})+ assert not _set_notice(f"{section}.{key}", f"vendor-{section}", capsys)+ assert read_selection(section) == f"vendor-{section}"-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"]}))+def test_computer_use_backend_set_is_what_the_selector_reads(hermes_home, capsys):+ from plugins.computer_use import configured_backend_name- set_config_value("display.widget.size", "3")- assert NOTICE not in capsys.readouterr().out+ assert not _set_notice("computer_use.backend", "widget-driver", capsys)+ assert configured_backend_name() == "widget-driver"+++def test_plugin_config_keys_count_only_while_the_plugin_is_enabled(hermes_home, capsys):+ _plugin(hermes_home / "plugins", "widget-plugin", ["display.widget"])++ assert _set_notice("display.widget.size", "3", capsys) # installed, not enabled+ _write_config(hermes_home, {"plugins": {"enabled": ["widget-plugin"]}})+ assert not _set_notice("display.widget.size", "4", capsys)# 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+ assert _set_notice("display.widgetx", "3", capsys)+ assert _set_notice("browser.cloud_providr", "browserbase", capsys)+ _write_config(hermes_home, {"plugins": {"enabled": ["widget-plugin"], "disabled": ["widget-plugin"]}})+ assert _set_notice("display.widget.size", "5", capsys) # disabled wins-def test_enabled_project_plugin_declares_its_config_keys(hermes_home, tmp_path, monkeypatch, capsys):- plugin = tmp_path / "proj" / ".hermes" / "plugins" / "widget-plugin"+def test_portable_plugin_declares_config_keys_in_its_hermes_extension(hermes_home, capsys):+ plugin = hermes_home / "plugins" / "portwidget"plugin.mkdir(parents=True)- (plugin / "plugin.yaml").write_text(json.dumps({"name": "widget-plugin", "config_keys": ["display.widget"]}))+ (plugin / "plugin.json").write_text(json.dumps({+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "portwidget",+ "version": "1.0.0", "extensions": {"com.nousresearch.hermes": {"config_keys": ["display.portwidget"]}},+ }))++ assert _set_notice("display.portwidget.size", "3", capsys)+ _write_config(hermes_home, {"plugins": {"enabled": ["portwidget"]}})+ assert not _set_notice("display.portwidget.size", "4", capsys)+++def test_plugin_cannot_silence_typos_in_a_whole_core_section(hermes_home, capsys):+ _plugin(hermes_home / "plugins", "hostile", ["agent", "agent.turn_liveness"])+ _write_config(hermes_home, {"plugins": {"enabled": ["hostile"]}})++ for typo, suggestion in (("agent.max_turnz", "agent.max_turns"),+ ("agent.turn_liveness.timeout", "agent.turn_liveness.timeout_s")):+ set_config_value(typo, "1")+ out = capsys.readouterr().out+ assert NOTICE in out, typo+ assert suggestion in out+++def test_selected_memory_provider_declares_its_config_keys(hermes_home, capsys):+ _plugin(hermes_home / "plugins", "widgetmem", ["memory.widgetmem"],+ init_source="from agent.memory_provider import MemoryProvider\n\nclass WidgetMem(MemoryProvider):\n pass\n")++ assert _set_notice("memory.widgetmem.project", "p1", capsys) # installed, not selected+ _write_config(hermes_home, {"memory": {"provider": "widgetmem"}})+ assert not _set_notice("memory.widgetmem.project", "p2", capsys)+++def test_enabled_project_plugin_declares_its_config_keys(hermes_home, tmp_path, monkeypatch, capsys):+ _plugin(tmp_path / "proj" / ".hermes" / "plugins", "widget-plugin", ["display.widget"])+ _write_config(hermes_home, {"plugins": {"enabled": ["widget-plugin"]}})monkeypatch.chdir(tmp_path / "proj")- set_config_value("display.widget.size", "3")- assert NOTICE in capsys.readouterr().out # project plugins are opt-in+ assert _set_notice("display.widget.size", "3", capsys) # project plugins are opt-inmonkeypatch.setenv("HERMES_ENABLE_PROJECT_PLUGINS", "1")- set_config_value("display.widget.size", "4")- assert NOTICE not in capsys.readouterr().out+ assert not _set_notice("display.widget.size", "4", capsys)diff --git a/tools/tool_backend_helpers.py b/tools/tool_backend_helpers.pyindex bd82bafeead..968b129d1af 100644--- a/tools/tool_backend_helpers.py+++ b/tools/tool_backend_helpers.py@@ -195,23 +195,24 @@ def prefers_gateway(config_section: str) -> bool:NOUS_MANAGED_PROVIDER = "nous"# Per-capability keys that also count as "this category has been configured"._EXTRA_SELECTION_KEYS = {"web": ("search_backend", "extract_backend")}-# Key(s) carrying the category's provider selection. A leftover ``browser.backend`` (the-# 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")+# Key(s) carrying each category's provider selection: one entry per `hermes tools` / Tool Gateway+# category read_selection() serves. A leftover ``browser.backend`` (the pre-v52 driver choice) is+# not the cloud provider — excluded.+_SELECTION_NAME_KEYS = {+ "browser": ("cloud_provider",), "web": ("backend",),+ **dict.fromkeys(("image_gen", "video_gen", "tts", "stt"), _DEFAULT_NAME_KEYS),+}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."""+ """Dotted config keys read_selection()/selection_exists() honour, from their own tables.+ 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, ())))+ for section, name_keys in _SELECTION_NAME_KEYS.items()+ for key in ("use_gateway", *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 bf459b63083..ffa5f10f8c0 100644--- a/website/docs/developer-guide/plugins/index.md+++ b/website/docs/developer-guide/plugins/index.md@@ -620,7 +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`. |+| `config_keys` | list | Dotted paths in Hermes' own config sections that your code reads (e.g. `memory.retaindb`). Each path covers itself and everything below it, so `hermes config get/set` recognizes those keys instead of warning "not a recognized config key", but only while the plugin is active (enabled, or the selected `memory.provider`). A path must be at least two segments deep, and paths Hermes already defines are ignored, so a declaration never hides a typo elsewhere in the section. Settings for your plugin alone belong in `config_schema`; use this only for a core section your plugin reads. Portable `plugin.json` packages put it under `extensions."com.nousresearch.hermes".config_keys`. || `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]`). |