toolset_validation.py 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173
  1. """Validation for the ``platform_toolsets`` config section."""
  2. import ast
  3. from functools import cache
  4. from typing import Callable, List, Optional
  5. from hermes_cli.platforms import PLATFORMS
  6. from hermes_cli.toolset_scope import toolset_allowed_for_platform
  7. _NO_TOOLS = "the agent will have no tools on this platform. Run `hermes tools` to reconfigure."
  8. def parse_platform_toolsets_value(value: object) -> Optional[list[str]]:
  9. """The toolset list a saved ``platform_toolsets.<platform>`` value encodes, or None.
  10. Older ``hermes config set`` builds stored a bare ``[...]`` argument as a plain string, so an
  11. explicit selection like ``'["browser", "terminal"]'`` parses as str, not list (#115866).
  12. Every reader and writer of the section goes through this one parser so the runtime,
  13. ``hermes doctor`` and ``hermes plugins enable`` agree on what the user configured. Any other
  14. shape (null, scalar, unparseable string) is None: the caller decides how to report it.
  15. """
  16. if isinstance(value, list):
  17. return value
  18. if isinstance(value, str) and value.strip().startswith("["):
  19. try:
  20. parsed = ast.literal_eval(value.strip())
  21. except (ValueError, SyntaxError):
  22. return None
  23. if isinstance(parsed, list):
  24. return [str(item) for item in parsed]
  25. return None
  26. def _platform_default_toolset(platform: object) -> str:
  27. info = PLATFORMS.get(platform)
  28. return info.default_toolset if info is not None else f"hermes-{platform}"
  29. @cache
  30. def _bundled_platform_names() -> frozenset:
  31. from hermes_cli.config import _platform_manifest_paths
  32. return frozenset(name for name, path, _kind, _st in _platform_manifest_paths(source="bundled") if path)
  33. def is_known_platform_bundle(platform: object, name: str) -> bool:
  34. """True when ``name`` is the ``hermes-<platform>`` bundle of a platform Hermes knows: builtin, shipped
  35. under ``plugins/platforms``, a platform that left core for a catalog plugin, or one a loaded plugin
  36. registered. Installs seeded from cli-config.yaml.example carry such rows for platforms nobody set up
  37. (teams, google_chat, homeassistant), inert until the plugin loads. A misspelt platform key naming its
  38. own bundle (``telegarm: [hermes-telegarm]``) is not known, so it is still reported."""
  39. if name != _platform_default_toolset(platform):
  40. return False
  41. key = str(platform)
  42. if key in PLATFORMS or key in _bundled_platform_names():
  43. return True
  44. from hermes_cli.left_core_migration import LEFT_CORE
  45. if any(feature.platform == key for feature in LEFT_CORE):
  46. return True
  47. from gateway.platform_registry import platform_registry
  48. return platform_registry.is_registered(key)
  49. def _platform_default_is_valid(
  50. platform: object, default_toolset: str, is_valid_toolset: Callable[[str], bool],
  51. is_allowed_for_platform: Callable[[str, str], bool]) -> bool:
  52. if is_valid_toolset(default_toolset) and is_allowed_for_platform(default_toolset, str(platform)):
  53. return True
  54. # Dynamic plugin platforms are resolved by toolsets.resolve_toolset() even though their synthesized
  55. # hermes-<platform> name is not in TOOLSETS.
  56. try:
  57. from gateway.platform_registry import platform_registry
  58. return platform_registry.is_registered(platform)
  59. except Exception:
  60. return False
  61. def saved_toolset_resolver(config: dict) -> Callable[[str], bool]:
  62. """``is_valid_toolset`` for a saved ``platform_toolsets`` list, mirroring what
  63. ``tools_config._get_platform_tools`` lets through: registered toolsets, any configured MCP server by
  64. its ``mcp-<server>`` toolset name or bare alias (neither is registered before MCP discovery; a
  65. disabled server is inactive, not a typo), ``hermes-<platform>`` plugin-platform bundles and the
  66. ``no_mcp`` sentinel. The manifest scan and the plugin lookup (which may run plugin discovery)
  67. happen only for a name the cheaper checks cannot place."""
  68. from functools import cache
  69. from toolsets import validate_toolset
  70. mcp_servers = config.get("mcp_servers")
  71. servers = {str(name) for name in mcp_servers} if isinstance(mcp_servers, dict) else set()
  72. known = servers | {f"mcp-{name}" for name in servers} | {"no_mcp"}
  73. @cache
  74. def platform_bundles() -> frozenset:
  75. from hermes_cli.config import _platform_plugin_manifests
  76. return frozenset(f"hermes-{name}" for name, _manifest in _platform_plugin_manifests())
  77. @cache
  78. def plugin_names() -> frozenset:
  79. from hermes_cli.plugins import get_plugin_toolset_keys_nowait, get_portable_mcp_server_names_nowait
  80. portable = get_portable_mcp_server_names_nowait()
  81. return frozenset(get_plugin_toolset_keys_nowait() | portable | {f"mcp-{name}" for name in portable})
  82. return lambda name: (validate_toolset(name) or name in known
  83. or name in platform_bundles() or name in plugin_names())
  84. def validate_platform_toolsets(
  85. platform_toolsets: object, is_valid_toolset: Callable[[str], bool],
  86. is_allowed_for_platform: Callable[[str, str], bool] = toolset_allowed_for_platform,
  87. ) -> list[str]:
  88. """Return human-readable warnings for a ``platform_toolsets`` mapping.
  89. Reports: a toolset name ``is_valid_toolset`` rejects (suggesting ``hermes-<platform>`` when that
  90. would have been valid); a non-empty mapping resolving to zero valid toolsets (agent would start with
  91. no tools); a platform with no valid toolsets, checked per-platform because the global net is
  92. suppressed once any platform is valid; and non-list platform values, which fall back to the platform
  93. default. ``is_valid_toolset`` is injected so this does no registry imports or I/O."""
  94. warnings: list[str] = []
  95. if not isinstance(platform_toolsets, dict) or not platform_toolsets:
  96. return warnings
  97. valid_count = 0
  98. for platform, raw in platform_toolsets.items():
  99. default = _platform_default_toolset(platform)
  100. default_valid = _platform_default_is_valid(platform, default, is_valid_toolset, is_allowed_for_platform)
  101. platform_valid_count = 0
  102. toolsets = parse_platform_toolsets_value(raw)
  103. if toolsets is None:
  104. if default_valid:
  105. valid_count += 1
  106. platform_valid_count += 1
  107. fallback_detail = f"falling back to '{default}'" if default_valid else f"falling back to unknown default '{default}'"
  108. if raw is None:
  109. value_detail = "a null toolset value"
  110. elif isinstance(raw, str):
  111. value_detail = f"invalid toolset value '{raw}'"
  112. else:
  113. value_detail = f"invalid {type(raw).__name__} toolset value"
  114. warnings.append(
  115. f"platform '{platform}' has {value_detail} — "
  116. f"{fallback_detail}. Run `hermes tools` to configure explicitly.")
  117. if platform_valid_count == 0:
  118. warnings.append(f"platform '{platform}' has no valid toolsets configured — {_NO_TOOLS}")
  119. continue
  120. for name in toolsets:
  121. if not isinstance(name, str) or not name:
  122. continue
  123. if not is_valid_toolset(name) and not is_known_platform_bundle(platform, name):
  124. hint = f" — did you mean '{default}'?" if default_valid else ""
  125. warnings.append(f"platform '{platform}' references unknown toolset '{name}'{hint}")
  126. elif is_allowed_for_platform(name, str(platform)):
  127. valid_count += 1
  128. platform_valid_count += 1
  129. else:
  130. warnings.append(
  131. f"platform '{platform}' references toolset '{name}' which is not available on this platform"
  132. )
  133. if platform_valid_count == 0:
  134. reason = "is configured with an empty toolset list" if not toolsets else "has no valid toolsets configured"
  135. warnings.append(f"platform '{platform}' {reason} — {_NO_TOOLS}")
  136. if valid_count == 0:
  137. warnings.append(
  138. "platform_toolsets resolves to zero valid toolsets — the agent will "
  139. "have no tools. Run `hermes tools` to reconfigure.")
  140. return warnings