delegation_registry.py 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
  1. """Delegation provider registry.
  2. Populated by plugins via :meth:`PluginContext.register_delegation_provider`; ``delegate_task``
  3. asks :func:`get_active_provider` which strategy turns each task into a child run. Selection is
  4. ``delegation.backend`` in config.yaml, ``default`` when unset. The default strategy (today's
  5. behaviour: every child follows the ``delegation`` section, else the parent's route) is itself a
  6. plugin, the bundled ``plugins/delegation/default``, registered through the same seam as any other.
  7. ``agent/delegation_backends.py`` saves it (``/delegation``); a session routes on the backend its tools were built from. A configured backend that is
  8. not registered or reports unavailable fails closed: ``delegate_task`` returns a tool error naming the
  9. backend and the fix, and never quietly runs the children on another route. Its schema parameters are
  10. absent, since the schema is built from the same resolution.
  11. """
  12. from __future__ import annotations
  13. import logging
  14. import re
  15. from typing import Any, Mapping, Optional
  16. from agent.delegation_provider import DelegationProvider, DelegationRouteError
  17. from agent.provider_registry import ProviderRegistry, is_available_safe, lower_key
  18. logger = logging.getLogger(__name__)
  19. DEFAULT_BACKEND = "default"
  20. _registry: ProviderRegistry[DelegationProvider] = ProviderRegistry(
  21. label="Delegation", provider_cls=DelegationProvider, logger=logger, normalize=lower_key,
  22. )
  23. _registry.export(globals())
  24. _BUNDLED_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
  25. def configured_backend(config: Mapping[str, Any]) -> str:
  26. """``delegation.backend`` normalized; blank/non-string means ``default``."""
  27. raw = config.get("backend") if isinstance(config, Mapping) else None
  28. return lower_key(raw) if isinstance(raw, str) and raw.strip() else DEFAULT_BACKEND
  29. _first_use: dict[str, DelegationProvider] = {}
  30. class _BundledRegistrar:
  31. """The one ``ctx`` method a bundled strategy's ``register()`` calls on first use. It keeps the provider
  32. outside the plugin registry, whose entries only the plugin manager adds and removes."""
  33. def __init__(self, name: str) -> None:
  34. self.name = name
  35. def register_delegation_provider(self, provider: DelegationProvider) -> None:
  36. _first_use[self.name] = provider
  37. def _bundled_disabled(name: str) -> bool:
  38. from hermes_cli.plugins_discovery import _get_disabled_plugins
  39. return bool({name, f"delegation/{name}"} & _get_disabled_plugins())
  40. def _load_bundled(name: str) -> Optional[DelegationProvider]:
  41. """The bundled strategy ``plugins/delegation/<name>/`` on first use when the plugin sweep has not
  42. registered it (a runtime that never ran discovery, or pinned it with zero plugins): delegation is a
  43. core tool and must not depend on the sweep. ``plugins.disabled`` wins on every call, so a later
  44. disable takes effect without a restart."""
  45. from hermes_cli.plugins import get_bundled_plugins_dir
  46. from plugins import plugin_loader
  47. if not _BUNDLED_NAME_RE.match(name) or _bundled_disabled(name): # the name comes from config.yaml: never a path
  48. return None
  49. if name in _first_use:
  50. return _first_use[name]
  51. plugin_dir = get_bundled_plugins_dir() / "delegation" / name
  52. if not (plugin_dir / "plugin.yaml").is_file():
  53. return None
  54. module = plugin_loader.load_plugin_module(
  55. f"plugins.delegation.{name.replace('-', '_')}", plugin_dir, parents=("plugins", "plugins.delegation"),
  56. logger=logger)
  57. if module is None:
  58. return None
  59. module.register(_BundledRegistrar(name))
  60. return _first_use.get(name)
  61. def _available(provider: Optional[DelegationProvider]) -> bool:
  62. return provider is not None and is_available_safe(
  63. provider, logger, "delegation provider %s.is_available() raised %s")
  64. def _usable(name: str) -> Optional[DelegationProvider]:
  65. """The available provider for ``name``: the registered one, else a bundled strategy of that name
  66. (also when the registered one reports unavailable), else one plugin discovery sweep (a caller
  67. that never imported ``model_tools``)."""
  68. registered = _registry.get_provider(name)
  69. if _available(registered):
  70. return registered
  71. bundled = _load_bundled(name)
  72. if _available(bundled):
  73. return bundled
  74. if registered is None and bundled is None:
  75. from hermes_cli.plugins import discover_plugins
  76. discover_plugins()
  77. registered = _registry.get_provider(name)
  78. if _available(registered):
  79. return registered
  80. return None
  81. def backend_status(name: str) -> tuple[Optional[DelegationProvider], str]:
  82. """``(provider, "")`` when backend ``name`` can run here, else ``(provider or None, reason)``; the reason is
  83. the user-facing fix (it becomes the ``delegate_task`` tool error)."""
  84. provider = _usable(name)
  85. if provider is not None:
  86. return provider, ""
  87. registered = _registry.get_provider(name)
  88. if registered is None and name == DEFAULT_BACKEND:
  89. return None, ("No default delegation strategy is available: the bundled plugin delegation/default is "
  90. "disabled. Remove it from plugins.disabled in config.yaml.")
  91. if registered is None:
  92. return None, (
  93. f"Delegation backend '{name}' is not installed: no enabled plugin provides it. Install or enable the "
  94. f"plugin that does (`hermes plugins list`), or switch back to the default backend "
  95. f"(`hermes config set delegation.backend default`).")
  96. return registered, (
  97. f"Delegation backend '{name}' is unavailable here (its plugin reports it cannot run). Fix its setup, or "
  98. f"switch back to the default backend: `/delegation default` for this session, or "
  99. f"`hermes config set delegation.backend default`.")
  100. def get_active_provider(config: Mapping[str, Any]) -> DelegationProvider:
  101. """The provider ``config`` (the ``delegation`` section) selects; ``default`` when unset. Raises
  102. :class:`DelegationRouteError` naming the backend and the fix when it is not registered or unavailable."""
  103. provider, reason = backend_status(configured_backend(config))
  104. if reason or provider is None:
  105. raise DelegationRouteError(f"{reason} No subagent was started.")
  106. return provider