plugins_registrars.py 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  1. """The ``register_<category>_provider`` table behind :class:`hermes_cli.plugins.PluginContext`.
  2. Every ``register_<category>_provider`` shares one body (:meth:`PluginContext._register_scoped_provider`):
  3. type-check, register in the scope-keyed process-global registry, lease the slot so unload restores
  4. the displaced entry. ``hermes_cli.plugins`` generates one ctx method per row. Rows: (method, kind,
  5. registry module, base-class module:attr, label, docstring, options). ``normalize``: ``strip``
  6. (default), ``lower`` (strip+lowercase) or ``None`` (raw name). ``admit``: ``module:function`` taking
  7. the plugin's manifest and returning why it may not register this kind ("" = it may), judged under the
  8. manager's home before the registry is touched. ``identity``: a registry function judging the provider's
  9. name without running its code, before the shared body reads ``provider.name`` (``ValueError`` = refused,
  10. logged with ``reject_message``). Object-taking rows also need a
  11. ``plugin_isolation.HOST_OBJECT_BASES`` entry so the provider works under ``plugins.isolation: host``.
  12. """
  13. from __future__ import annotations
  14. import importlib
  15. import logging
  16. from typing import Any, Callable, Optional
  17. from hermes_cli.plugins_loader import _plugin_home_scope, _serialized_replacement
  18. logger = logging.getLogger(__name__)
  19. _SCOPED_PROVIDER_REGISTRARS: tuple[tuple[str, str, str, str, str, str, dict[str, Any]], ...] = (
  20. ("register_login_backend", "login_backend", "agent.vault_backend_registry",
  21. "agent.vault_backends.base:LoginBackend", "login backend",
  22. "Register a trusted in-process browser-vault LoginBackend; explicit vault.<name>.enabled "
  23. "is required. Registration is profile-scoped and removed on plugin unload. "
  24. "Backend instances must read active-profile configuration lazily. Accepted only from bundled "
  25. "plugins and catalog installs at tier verified or official.",
  26. {"normalize": None, "reject_message": "Plugin '%s' login backend rejected: %s",
  27. "admit": "hermes_cli.plugins_cmd_catalog:login_backend_provenance_error", "identity": "static_name"}),
  28. ("register_browser_page_backend", "browser_page_backend", "agent.browser_page_registry",
  29. "agent.browser_page_backend:BrowserPageBackend", "browser page backend",
  30. "Register an :class:`agent.browser_page_backend.BrowserPageBackend` so ``browser_vault`` inspects and "
  31. "fills the pages of a browser with no CDP endpoint (Camofox). Profile-scoped, removed on plugin "
  32. "unload; accepted only from bundled plugins and catalog installs at tier verified or official.",
  33. {"reject_message": "Plugin '%s' browser page backend rejected: %s",
  34. "admit": "hermes_cli.plugins_cmd_catalog:browser_page_backend_provenance_error"}),
  35. ("register_image_gen_provider", "image_gen_provider", "agent.image_gen_registry",
  36. "agent.image_gen_provider:ImageGenProvider", "image_gen provider",
  37. "Register an :class:`agent.image_gen_provider.ImageGenProvider`; "
  38. "``provider.name`` is matched by ``image_gen.provider``.", {"article": "an"}),
  39. ("register_video_gen_provider", "video_gen_provider", "agent.video_gen_registry",
  40. "agent.video_gen_provider:VideoGenProvider", "video_gen provider",
  41. "Register an :class:`agent.video_gen_provider.VideoGenProvider`; "
  42. "``provider.name`` is matched by ``video_gen.provider``.", {}),
  43. ("register_web_search_provider", "web_search_provider", "agent.web_search_registry",
  44. "agent.web_search_provider:WebSearchProvider", "web provider",
  45. "Register an :class:`agent.web_search_provider.WebSearchProvider`; "
  46. "``provider.name`` is matched by ``web.search_backend`` / ``web.extract_backend`` / ``web.backend``.",
  47. {}),
  48. ("register_browser_provider", "browser_provider", "agent.browser_registry",
  49. "agent.browser_provider:BrowserProvider", "browser provider",
  50. "Register an :class:`agent.browser_provider.BrowserProvider`; "
  51. "``provider.name`` is matched by ``browser.cloud_provider`` (consulted by "
  52. "``tools.browser_session_cloud.get_cloud_provider``).", {}),
  53. ("register_terminal_environment_provider", "terminal_environment_provider",
  54. "agent.terminal_env_registry", "agent.terminal_env_provider:TerminalEnvironmentProvider",
  55. "terminal environment provider",
  56. "Register a :class:`agent.terminal_env_provider.TerminalEnvironmentProvider`; ``provider.name`` "
  57. "is matched by ``terminal.backend`` when no built-in backend has that name. Built-in names (local, "
  58. "docker, modal, daytona, vercel_sandbox, ssh) are rejected — plugins never shadow "
  59. "in-tree backends.",
  60. {"normalize": "lower", "reject_message": "Plugin '%s' terminal environment provider rejected: %s"}),
  61. ("register_secret_source", "secret_source", "agent.secret_sources.registry",
  62. "agent.secret_sources.base:SecretSource", "secret source",
  63. "Register a :class:`agent.secret_sources.base.SecretSource`, run by ``load_hermes_dotenv()`` "
  64. "(after ``~/.hermes/.env``, before credentials are read) when ``secrets.<name>`` is enabled. The "
  65. "orchestrator owns ordering/precedence/provenance; the source only fetches. Since dotenv usually "
  66. "loads before discovery, the manager re-pulls enabled plugin sources afterwards.",
  67. {"normalize": None, "register": "register_source", "param": "source"}),
  68. ("register_tts_provider", "tts_provider", "agent.tts_registry",
  69. "agent.tts_provider:TTSProvider", "TTS provider",
  70. "Register an :class:`agent.tts_provider.TTSProvider`; ``provider.name`` is matched by "
  71. "``tts.provider`` unless it is a built-in name (rejected with a warning) or a "
  72. "``tts.providers.<name>: type: command`` entry shares it (command-providers win).",
  73. {"normalize": "lower"}),
  74. ("register_transcription_provider", "transcription_provider", "agent.transcription_registry",
  75. "agent.transcription_provider:TranscriptionProvider", "transcription provider",
  76. "Register an :class:`agent.transcription_provider.TranscriptionProvider`; ``provider.name`` is "
  77. "matched by ``stt.provider`` unless it is a built-in name (rejected) or a ``stt.providers.<name>: "
  78. "type: command`` entry shares it (command-providers win).", {"normalize": "lower"}),
  79. ("register_delegation_provider", "delegation_provider", "agent.delegation_registry",
  80. "agent.delegation_provider:DelegationProvider", "delegation provider",
  81. "Register an :class:`agent.delegation_provider.DelegationProvider`; ``provider.name`` is matched by "
  82. "``delegation.backend``. It decides each ``delegate_task`` task's route (model/provider or a Hermes "
  83. "profile) and may add per-task schema parameters; core keeps the subagent lifecycle.",
  84. {"normalize": "lower"}),
  85. )
  86. _NAME_NORMALIZERS: dict[Optional[str], Optional[Callable[[str], str]]] = {
  87. "strip": lambda n: n.strip(), "lower": lambda n: n.strip().lower(), None: None,
  88. }
  89. def _resolve(ref: str) -> Any:
  90. module, attr = ref.split(":")
  91. return getattr(importlib.import_module(module), attr)
  92. def make_scoped_provider_registrar(method_name, kind, registry_mod, base_ref, label, doc, options):
  93. """Build one ``register_<category>_provider`` method from a ``_SCOPED_PROVIDER_REGISTRARS`` row."""
  94. normalize_fn = _NAME_NORMALIZERS[options.get("normalize", "strip")]
  95. register_name = options.get("register")
  96. admit, identity = options.get("admit"), options.get("identity")
  97. def register(self, provider):
  98. if admit:
  99. with _plugin_home_scope(self._manager.home_path):
  100. refusal = _resolve(admit)(self.manifest)
  101. if refusal:
  102. logger.warning(options["reject_message"], self.manifest.name, refusal)
  103. return None
  104. registry = importlib.import_module(registry_mod)
  105. if identity:
  106. try:
  107. getattr(registry, identity)(provider)
  108. except ValueError as exc:
  109. logger.warning(options["reject_message"], self.manifest.name, exc)
  110. return None
  111. return self._register_scoped_provider(
  112. provider, kind=kind, base_class=_resolve(base_ref),
  113. registry=registry, label=label, article=options.get("article", "a"), normalize=normalize_fn,
  114. register=getattr(registry, register_name) if register_name else None,
  115. reject_message=options.get("reject_message"),
  116. )
  117. def register_source(self, source): # secret sources: ``source``
  118. return register(self, source)
  119. method = register_source if options.get("param") == "source" else register
  120. method.__name__, method.__qualname__, method.__doc__ = method_name, f"PluginContext.{method_name}", doc
  121. return _serialized_replacement(method)