Skip to content

The agent that grows with you

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.py
index 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 None
hermes = 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.py
index 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, None
known = _known_top_level_keys()
diff --git a/hermes_cli/config_runtime_keys.py b/hermes_cli/config_runtime_keys.py
index 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 json
import 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, Iterator
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 (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.py
index 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]) -> Optio
def 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_manifest
data, 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) -> PluginMan
author=_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.yaml
index 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.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 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.py
index 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 argparse
import 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 out
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}}))
+ _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-in
monkeypatch.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.py
index 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.md
index 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]`). |