plugin_isolation.py 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143
  1. """Where third-party Python plugin code is allowed to run (``plugins.isolation``).
  2. ``in_process`` (default) imports every plugin into the Hermes process, as always. ``host`` keeps
  3. third-party plugin code OUT of it: general plugins load in one plugin-host process per profile
  4. (:mod:`hermes_cli.plugin_host`) and talk to Hermes only through ``ctx``; every other path that would
  5. import a user-supplied module in-process (category providers, model-provider profiles, dashboard
  6. plugin APIs) refuses with a stated reason. Bundled plugins ship with Hermes and stay in-process.
  7. That second half is the property a pooled deployment needs: one Hermes process serving many
  8. profiles must never share an interpreter with a profile's plugin code. The same boundary gives a
  9. single-user install crash isolation (a plugin that segfaults or hangs takes down its host, not the
  10. gateway), which is why it is a plain config value and not a cloud-only switch.
  11. The ctx surface tables below are the single source of truth for both the runtime boundary
  12. (:mod:`hermes_cli.plugin_host_child` refuses these methods) and the static audit
  13. (:mod:`hermes_cli.plugin_isolation_audit`), so "the audit says pool-safe" and "it loads in the host"
  14. cannot drift apart.
  15. """
  16. from __future__ import annotations
  17. import logging
  18. import os
  19. from typing import Any, Dict, FrozenSet, List, Mapping, Optional
  20. logger = logging.getLogger("hermes_cli.plugins")
  21. ISOLATION_IN_PROCESS = "in_process"
  22. ISOLATION_HOST = "host"
  23. _ISOLATION_MODES = frozenset({ISOLATION_IN_PROCESS, ISOLATION_HOST})
  24. # ctx methods that hand a plugin (or receive from it) live objects no process boundary can carry:
  25. # raw platform SDK clients, argparse parsers, adapter classes bound to the gateway's event loop, the
  26. # launch-scope dashboard auth registry. A plugin calling one of these runs only in-process.
  27. HOST_UNSUPPORTED_CTX_METHODS: dict[str, str] = {
  28. "register_login_backend": "browser-vault fills hold a server-local context manager",
  29. "register_browser_page_backend": "browser-vault fill scripts carry credentials that stay in the Hermes process",
  30. "register_platform": "platform adapters run on the gateway's event loop with native SDK clients",
  31. "register_platform_handler": "the handler factory receives the platform's native SDK client",
  32. "register_telegram_handler": "the handler factory receives the native Telegram Application",
  33. "register_slack_action_handler": "the callback receives native slack_bolt ack/body objects",
  34. "register_dashboard_auth_provider": "dashboard auth is owned by the launch process, not a profile",
  35. "register_approval_transport": "approval transports hold the live approval request/response channel",
  36. "post_message": "the returned handle is bound to the gateway's event loop and live adapter",
  37. "apost_message": "the returned handle is bound to the gateway's event loop and live adapter",
  38. }
  39. # Registered in-process only; skipped (with a warning, the plugin still loads) inside the host
  40. # because the surface they extend does not exist in a server process.
  41. HOST_SKIPPED_CTX_METHODS: dict[str, str] = {
  42. "register_cli_command": "`hermes <command>` subcommands are wired into the local CLI parser",
  43. }
  44. # Live ctx facades the host reaches by method call; each call returns plain data.
  45. HOST_REMOTE_FACADES: frozenset[str] = frozenset({
  46. "state", "llm", "platform_actions", "subagent_lifecycle", "delegation_backends",
  47. })
  48. # Object-taking ctx methods and the ABC the parent checks. The host sends the object's method table
  49. # and the parent builds a subclass of that ABC whose methods run in the host.
  50. HOST_OBJECT_BASES: dict[str, str] = {
  51. "register_image_gen_provider": "agent.image_gen_provider:ImageGenProvider",
  52. "register_video_gen_provider": "agent.video_gen_provider:VideoGenProvider",
  53. "register_web_search_provider": "agent.web_search_provider:WebSearchProvider",
  54. "register_browser_provider": "agent.browser_provider:BrowserProvider",
  55. "register_terminal_environment_provider": "agent.terminal_env_provider:TerminalEnvironmentProvider",
  56. "register_secret_source": "agent.secret_sources.base:SecretSource",
  57. "register_tts_provider": "agent.tts_provider:TTSProvider",
  58. "register_transcription_provider": "agent.transcription_provider:TranscriptionProvider",
  59. "register_delegation_provider": "agent.delegation_provider:DelegationProvider",
  60. "register_context_engine": "agent.context_engine:ContextEngine",
  61. "register_context_reference": "agent.context_references:ContextReferenceProvider",
  62. "register_memory_provider": "agent.memory_provider:MemoryProvider",
  63. }
  64. # Hooks whose payload carries live handles (the gateway runner, the session store). In the host the
  65. # callback receives placeholders for those fields, so a plugin that uses them needs in-process.
  66. HOST_DEGRADED_HOOKS: dict[str, str] = {
  67. "pre_gateway_dispatch": "receives the live gateway runner and session store",
  68. }
  69. def _plugins_config(config: Optional[Mapping[str, Any]] = None) -> Mapping[str, Any]:
  70. if config is None:
  71. from hermes_cli.config import load_config_readonly
  72. config = load_config_readonly() or {}
  73. section = config.get("plugins") if isinstance(config, Mapping) else None
  74. return section if isinstance(section, Mapping) else {}
  75. # Set in the plugin host's environment: inside the host, plugin code is already out of Hermes, so
  76. # every loader there imports directly (a host must never spawn a host of its own).
  77. HOST_PROCESS_ENV = "HERMES_PLUGIN_HOST_PROCESS"
  78. def isolation_mode(config: Optional[Mapping[str, Any]] = None) -> str:
  79. """``plugins.isolation`` for the active profile; an unknown value warns and means in-process."""
  80. if os.environ.get(HOST_PROCESS_ENV) == "1":
  81. return ISOLATION_IN_PROCESS
  82. raw = _plugins_config(config).get("isolation", ISOLATION_IN_PROCESS)
  83. mode = str(raw or ISOLATION_IN_PROCESS).strip().lower().replace("-", "_")
  84. if mode not in _ISOLATION_MODES:
  85. logger.warning("plugins.isolation=%r is not one of %s; loading plugins in-process",
  86. raw, ", ".join(sorted(_ISOLATION_MODES)))
  87. return ISOLATION_IN_PROCESS
  88. return mode
  89. def host_launcher(config: Optional[Mapping[str, Any]] = None) -> list[str]:
  90. """``plugins.host.launcher``: argv prefix the host process runs under (a sandbox runner)."""
  91. host = _plugins_config(config).get("host")
  92. launcher = host.get("launcher") if isinstance(host, Mapping) else None
  93. if not launcher:
  94. return []
  95. if isinstance(launcher, str):
  96. import shlex
  97. return shlex.split(launcher)
  98. return [str(part) for part in launcher]
  99. def in_process_import_refusal(what: str, *, source: str = "user",
  100. config: Optional[Mapping[str, Any]] = None) -> Optional[str]:
  101. """Reason an in-process import of third-party code must not happen, or ``None`` when allowed.
  102. Every loader that imports a user-supplied module into the Hermes process asks this first;
  103. bundled code always passes.
  104. """
  105. if source == "bundled" or isolation_mode(config) != ISOLATION_HOST:
  106. return None
  107. return (f"{what} runs only in-process, and plugins.isolation is 'host' (third-party plugin code "
  108. f"never runs inside the Hermes process); set plugins.isolation: in_process to load it")
  109. def user_plugin_host() -> Any:
  110. """The active profile's plugin host when ``plugins.isolation`` is ``host``, else ``None``.
  111. Category loaders (memory providers, context engines, cron schedulers) ask this before importing
  112. a user plugin directory, so the same plugins keep working with their code in the host.
  113. """
  114. if isolation_mode() != ISOLATION_HOST:
  115. return None
  116. from hermes_cli.plugins import get_plugin_manager
  117. return get_plugin_manager()._plugin_host()