plugin_host.py 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627
  1. """Parent side of the plugin host: one process per profile that runs its third-party plugins.
  2. With ``plugins.isolation: host`` the loader hands a general Python plugin to :class:`PluginHost`
  3. instead of importing it. The host process imports it and runs ``register(ctx)``; every ``ctx`` call
  4. arrives here and is replayed on the plugin's real :class:`~hermes_cli.plugins.PluginContext`, with
  5. the plugin's callables and provider objects swapped for proxies that call back into the host. From
  6. then on the rest of Hermes sees ordinary registrations — the registry, hook dispatch, the ledger,
  7. unload and ``hermes plugins list`` do not know the plugin lives elsewhere, and neither does the
  8. plugin: its code is unchanged and never learns which process or tenant it serves.
  9. Requests the host makes while Hermes is waiting on it (a tool handler calling ``ctx.dispatch_tool``)
  10. run in the caller's context — same profile home, secret scope and session — via the wire's
  11. ``origin`` field; spontaneous ones (a ``spawn_task`` loop) run bound to this profile's home.
  12. When the host dies every proxy raises :class:`PluginHostUnavailable`: tool calls return an error,
  13. hooks fail like any raising callback, and Hermes itself keeps running. A fresh host is then started
  14. and its plugins reloaded (bounded restarts; a plugin that killed the host while loading stays out).
  15. """
  16. from __future__ import annotations
  17. import asyncio
  18. import contextvars
  19. import dataclasses
  20. import inspect
  21. import functools
  22. import importlib
  23. import itertools
  24. import logging
  25. import os
  26. import subprocess
  27. import sys
  28. import threading
  29. import time
  30. import weakref
  31. from pathlib import Path
  32. from typing import Any, Callable, Dict, Optional
  33. from hermes_cli.plugin_host_wire import (
  34. Channel, Opaque, PluginHostUnavailable, PluginHostUnsupported, declared_return, decode, encode, restore,
  35. signature_from,
  36. )
  37. logger = logging.getLogger("hermes_cli.plugins")
  38. _HOST_MODULE = "hermes_cli.plugin_host_child"
  39. _START_TIMEOUT_SECS = 30.0
  40. _SHUTDOWN_GRACE_SECS = 3.0
  41. # A host that dies is restarted (its plugins reloaded) at most this many times per window; a plugin
  42. # that kills the host while loading is not reloaded, so one bad plugin cannot crash-loop the rest.
  43. _RESTART_BUDGET = 3
  44. _RESTART_WINDOW_SECS = 600.0
  45. def _hosted_ambient_credentials(home: Path) -> dict[str, str]:
  46. """``env_vars`` of this home's hosted ``ambient_credentials`` providers (``GH_TOKEN``-style names the
  47. child-env scrub always strips), read the way that provider reads them in-process: ``get_secret``
  48. under the home's scope, so the launch home keeps its shell value and a routed home never gets it."""
  49. from agent.secret_scope import build_profile_secret_scope, get_secret, reset_secret_scope, set_secret_scope
  50. from hermes_cli.plugin_host_profiles import is_hosted_profile
  51. from providers import list_providers
  52. names = {name for p in list_providers() if p.ambient_credentials and is_hosted_profile(p) for name in p.env_vars}
  53. if not names:
  54. return {}
  55. token = set_secret_scope(build_profile_secret_scope(home), profile_home=str(home))
  56. try:
  57. return {name: value for name in sorted(names) if (value := get_secret(name))}
  58. finally:
  59. reset_secret_scope(token)
  60. class PluginHost:
  61. """One host process for one :class:`~hermes_cli.plugins.PluginManager` (one profile home)."""
  62. def __init__(self, manager: Any):
  63. self._manager = manager
  64. self._home = Path(manager.home_path)
  65. self._lock = threading.Lock()
  66. self._proc: Optional[subprocess.Popen] = None
  67. self._channel: Optional[Channel] = None
  68. self._contexts: dict[str, Any] = {}
  69. self._handles: dict[int, Any] = {}
  70. self._handle_ids = itertools.count(1)
  71. self._base_context = self._build_base_context()
  72. self._loading: Optional[str] = None
  73. self._stopping = False
  74. self._deaths: list = []
  75. # Bumped per host process: a proxy made for an earlier process must not address this one
  76. # (object ids restart at 1, so a stale id would silently land on a different object).
  77. self._generation = 0
  78. self._releases: list = []
  79. self.info: dict[str, Any] = {}
  80. # -- lifecycle ----------------------------------------------------------------------------------
  81. @property
  82. def pid(self) -> Optional[int]:
  83. return self._proc.pid if self._proc is not None else None
  84. @property
  85. def home(self) -> Path:
  86. return self._home
  87. @property
  88. def alive(self) -> bool:
  89. return (self._channel is not None and self._channel.closed_reason is None
  90. and self._proc is not None and self._proc.poll() is None)
  91. def _build_base_context(self) -> contextvars.Context:
  92. # A fresh context, not a copy of whichever caller created the host: requests with no
  93. # caller (a ``spawn_task`` loop) must not inherit that caller's session or approvals.
  94. context = contextvars.Context()
  95. def bind() -> None:
  96. from hermes_constants import set_hermes_home_override
  97. set_hermes_home_override(self._home)
  98. from agent.secret_scope import build_profile_secret_scope, is_multiplex_active, set_secret_scope
  99. if is_multiplex_active():
  100. set_secret_scope(build_profile_secret_scope(self._home), profile_home=str(self._home))
  101. context.run(bind)
  102. return context
  103. def _argv(self) -> list:
  104. from hermes_cli.plugin_isolation import host_launcher
  105. return [*host_launcher(), sys.executable, "-m", _HOST_MODULE]
  106. def _env(self) -> dict[str, str]:
  107. from tools.environments.local import served_profile_child_env
  108. env = self._base_context.run(served_profile_child_env, target_home=self._home, inherit_credentials=True)
  109. env.update(self._base_context.run(_hosted_ambient_credentials, self._home))
  110. repo_root = str(Path(__file__).resolve().parents[1])
  111. env["PYTHONPATH"] = os.pathsep.join(p for p in (repo_root, env.get("PYTHONPATH", "")) if p)
  112. env.setdefault("HERMES_PLUGIN_HOST_LOG_LEVEL", "WARNING")
  113. from hermes_cli.plugin_isolation import HOST_PROCESS_ENV
  114. env[HOST_PROCESS_ENV] = "1"
  115. return env
  116. def ensure_started(self) -> Channel:
  117. with self._lock:
  118. if self.alive:
  119. return self._channel # type: ignore[return-value]
  120. self._stopping = False
  121. argv = self._argv()
  122. proc = subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
  123. stderr=subprocess.PIPE, env=self._env(), cwd=str(self._home),
  124. bufsize=0)
  125. threading.Thread(target=_pump_stderr, args=(proc, self._home.name), daemon=True,
  126. name=f"plugin-host-{proc.pid}-stderr").start()
  127. self._generation += 1
  128. channel = Channel(proc.stdout, proc.stdin, self._handle, # type: ignore[arg-type]
  129. name=f"plugin-host[{proc.pid}]",
  130. on_close=functools.partial(self._on_channel_close, self._generation),
  131. context_for_origin=self._context_for_origin).start()
  132. self._proc, self._channel = proc, channel
  133. self._releases = []
  134. try:
  135. self.info = channel.call("hello", {}, timeout=_START_TIMEOUT_SECS)
  136. except Exception as exc:
  137. self.shutdown()
  138. raise PluginHostUnavailable(f"plugin host failed to start ({' '.join(argv)}): {exc}") from exc
  139. logger.info("Plugin host started for %s (pid %s)", self._home, proc.pid)
  140. return channel
  141. def _exit_reason(self) -> str:
  142. proc = self._proc
  143. code = proc.poll() if proc is not None else None
  144. if proc is not None and code is None:
  145. try:
  146. code = proc.wait(timeout=0.5) # the pipe closes a moment before the exit status lands
  147. except subprocess.TimeoutExpired:
  148. pass
  149. return (f"the plugin host for this profile exited (code {code}); Hermes restarts it and reloads "
  150. f"its plugins automatically" if code is not None else "the plugin host is not running")
  151. def _on_channel_close(self, generation: int, reason: str) -> None:
  152. if self._stopping or generation != self._generation:
  153. return # a deliberate shutdown, or a late close from a host already replaced
  154. culprit = self._loading
  155. keys = [k for k in self._contexts.copy() if k != culprit and k in self._manager._plugins]
  156. logger.warning("Plugin host for %s exited (%s)%s", self._home, self._exit_reason(),
  157. f" while loading plugin '{culprit}'" if culprit else "")
  158. now = time.monotonic()
  159. self._deaths = [t for t in self._deaths if now - t < _RESTART_WINDOW_SECS] + [now]
  160. if keys:
  161. threading.Thread(target=self._restart, args=(keys,), daemon=True,
  162. name="plugin-host-restart").start()
  163. def _restart_refused(self, what: str) -> bool:
  164. if len(self._deaths) <= _RESTART_BUDGET:
  165. return False
  166. logger.error("Plugin host for %s died %d times in %.0fs; not restarting it again (%s)",
  167. self._home, len(self._deaths), _RESTART_WINDOW_SECS, what)
  168. return True
  169. def _restart(self, keys: list) -> None:
  170. if self._restart_refused("plugins: " + ", ".join(keys)):
  171. return
  172. time.sleep(0.5 * len(self._deaths))
  173. manager = self._manager
  174. for key in keys:
  175. loaded = manager._plugins.get(key)
  176. if loaded is None or not loaded.enabled:
  177. continue
  178. manager.unload(key)
  179. manager._load_plugin(loaded.manifest)
  180. def shutdown(self) -> None:
  181. self._stopping = True
  182. with self._lock:
  183. proc, channel = self._proc, self._channel
  184. self._proc = self._channel = None
  185. if channel is not None and channel.closed_reason is None:
  186. try:
  187. channel.call("shutdown", {}, timeout=_SHUTDOWN_GRACE_SECS)
  188. except Exception:
  189. pass
  190. channel.close("shutdown")
  191. if proc is not None:
  192. try:
  193. proc.wait(timeout=_SHUTDOWN_GRACE_SECS)
  194. except subprocess.TimeoutExpired:
  195. proc.kill()
  196. proc.wait(timeout=_SHUTDOWN_GRACE_SECS)
  197. # -- loading ------------------------------------------------------------------------------------
  198. def load(self, manifest: Any, ctx: Any, *, module_name: Optional[str], entrypoint: bool) -> str:
  199. """Import ``manifest``'s plugin in the host and replay its registrations onto ``ctx``."""
  200. from hermes_cli.plugins import PluginContext, manifest_key
  201. channel = self.ensure_started()
  202. plugin_key = manifest_key(manifest)
  203. self._contexts[plugin_key] = ctx
  204. params = {
  205. "plugin_key": plugin_key, "plugin_id": ctx.plugin_id, "name": manifest.name,
  206. "path": manifest.path, "module_name": module_name, "entrypoint": entrypoint,
  207. "profile_name": self._base_context.copy().run(lambda: ctx.profile_name),
  208. "manifest": {k: getattr(manifest, k, None) for k in (
  209. "name", "version", "description", "author", "source", "path", "key", "kind",
  210. "data_namespace")},
  211. "ctx_methods": sorted(n for n in dir(PluginContext) if not n.startswith("_")),
  212. }
  213. self._loading = plugin_key
  214. try:
  215. result = channel.call("load", params)
  216. except BaseException:
  217. self._contexts.pop(plugin_key, None)
  218. raise
  219. finally:
  220. self._loading = None
  221. ctx.on_unload(functools.partial(self._unload, plugin_key))
  222. return str((result or {}).get("module") or module_name or "")
  223. def load_instance(self, plugin_dir: Path, *, module_name: str, base_ref: str, capture: str,
  224. ctx: Any = None, before_reload: Optional[Callable[[], None]] = None) -> Any:
  225. """Load a category plugin (memory provider, context engine, cron scheduler) in the host and
  226. return a proxy that is an instance of ``base_ref``. ``ctx`` receives its other registrations.
  227. The proxy outlives a host crash: its next use loads the plugin into the new host (after
  228. ``before_reload``, which drops the registrations the old load forwarded) and carries on."""
  229. load = functools.partial(self._load_instance_ref, Path(plugin_dir), module_name=module_name,
  230. base_ref=base_ref, capture=capture, ctx=ctx)
  231. ref = load()
  232. if ref is None:
  233. return None
  234. def reload() -> dict[str, Any]:
  235. if self._restart_refused(f"{capture} plugin {Path(plugin_dir).name}"):
  236. raise PluginHostUnavailable(self._exit_reason())
  237. if before_reload is not None:
  238. before_reload()
  239. fresh = load()
  240. if fresh is None:
  241. raise PluginHostUnavailable(f"plugin {Path(plugin_dir).name!r} no longer loads in the plugin host")
  242. return fresh
  243. return self._object_proxy(ref, _import_ref(base_ref), reload=reload)
  244. def _load_instance_ref(self, plugin_dir: Path, *, module_name: str, base_ref: str, capture: str,
  245. ctx: Any) -> Optional[dict[str, Any]]:
  246. channel = self.ensure_started()
  247. plugin_key = f"{capture}:{Path(plugin_dir).name}"
  248. if ctx is not None:
  249. self._contexts[plugin_key] = ctx
  250. from hermes_cli.plugins import PluginContext
  251. params = {
  252. "plugin_key": plugin_key, "plugin_id": getattr(ctx, "plugin_id", Path(plugin_dir).name),
  253. "name": Path(plugin_dir).name, "path": str(plugin_dir), "module_name": module_name,
  254. "base": base_ref, "capture": capture, "forward": ctx is not None,
  255. "manifest": {"name": Path(plugin_dir).name, "path": str(plugin_dir), "source": "user"},
  256. "ctx_methods": sorted(n for n in dir(PluginContext) if not n.startswith("_")),
  257. }
  258. self._loading = plugin_key
  259. try:
  260. ref = channel.call("load_instance", params)
  261. finally:
  262. self._loading = None
  263. if ref is not None:
  264. ref["generation"] = self._generation
  265. return ref
  266. def config_schema(self, path: Path) -> Any:
  267. """Run a user memory provider's ``config_schema.py`` here and return its ``CONFIG_SCHEMA``."""
  268. self.ensure_started()
  269. return self._call("config_schema", {"path": str(path)})
  270. def profile_call(self, plugin_dir: str, module_name: str, profile: str, attr: str,
  271. args: tuple, kwargs: dict) -> Any:
  272. """Run a model-provider profile's overridden method / callable field in the host."""
  273. self.ensure_started()
  274. return self._call("profile_call", {"path": plugin_dir, "module_name": module_name, "profile": profile,
  275. "attr": attr, "args": encode(list(args)), "kwargs": encode(kwargs)})
  276. def asgi_request(self, plugin_name: str, dashboard_dir: str, api_file: str, method: str, path: str,
  277. query: str, headers: list, body: bytes, *, timeout: Optional[float] = None,
  278. authenticated: bool = False) -> dict[str, Any]:
  279. """One dashboard ``/api/plugins/<name>/`` request, served by the plugin's router in the host;
  280. ``TimeoutError`` when no answer comes within ``timeout`` seconds (the host is left running)."""
  281. self.ensure_started()
  282. return self._call("asgi", {"plugin": plugin_name, "dashboard_dir": dashboard_dir, "api_file": api_file,
  283. "method": method, "path": path, "query": query,
  284. "authenticated": authenticated is True,
  285. "headers": [list(h) for h in headers], "body": encode(body)},
  286. timeout=timeout)
  287. def _unload(self, plugin_key: str) -> None:
  288. self._contexts.pop(plugin_key, None)
  289. channel = self._channel
  290. if channel is None or channel.closed_reason is not None:
  291. return
  292. errors = (channel.call("unload", {"plugin_key": plugin_key}) or {}).get("errors") or []
  293. for error in errors:
  294. logger.warning("Plugin '%s' on_unload callback failed in the plugin host: %s", plugin_key, error)
  295. # -- parent -> host -----------------------------------------------------------------------------
  296. def _call(self, method: str, params: dict[str, Any], *, generation: Optional[int] = None,
  297. timeout: Optional[float] = None, returns: Any = None) -> Any:
  298. """``returns`` is the type a core ABC declares for the result; the reply is rebuilt as it."""
  299. channel = self._channel
  300. try:
  301. if channel is None:
  302. raise PluginHostUnavailable("not started")
  303. if generation is not None and generation != self._generation:
  304. raise PluginHostUnavailable("this object belonged to a plugin host process that has exited")
  305. if self._releases:
  306. released, self._releases = self._releases, []
  307. channel.call("release", {"refs": released})
  308. resolve = functools.partial(self._resolve_result_ref, base=_host_object_base(returns))
  309. return restore(decode(channel.call(method, params, timeout=timeout), resolve), returns)
  310. except PluginHostUnavailable as exc:
  311. raise PluginHostUnavailable(self._exit_reason()) from exc
  312. def _release(self, generation: int, ref: int) -> None:
  313. """Finalizer of an object proxy (any thread, GC time): queue only; sent with the next call."""
  314. if generation == self._generation:
  315. self._releases.append(ref)
  316. def invoke(self, ref: int, args: tuple, kwargs: dict, *, generation: Optional[int] = None) -> Any:
  317. return self._call("invoke", {"ref": ref, "args": encode(list(args)), "kwargs": encode(kwargs)},
  318. generation=generation)
  319. def obj_invoke(self, slot: _ObjectSlot, method: str, args: tuple, kwargs: dict, returns: Any = None) -> Any:
  320. ref, generation = slot.live()
  321. return self._call("obj_invoke", {"ref": ref, "method": method, "args": encode(list(args)),
  322. "kwargs": encode(kwargs)}, generation=generation, returns=returns)
  323. def obj_getattr(self, slot: _ObjectSlot, name: str, returns: Any = None) -> Any:
  324. ref, generation = slot.live()
  325. value = self._call("obj_getattr", {"ref": ref, "name": name}, generation=generation, returns=returns)
  326. if isinstance(value, dict) and set(value) == {"__missing__"}:
  327. raise AttributeError(name)
  328. return value
  329. def obj_setattr(self, slot: _ObjectSlot, name: str, value: Any) -> None:
  330. ref, generation = slot.live()
  331. self._call("obj_setattr", {"ref": ref, "name": name, "value": encode(value)}, generation=generation)
  332. # -- host -> parent -----------------------------------------------------------------------------
  333. def _context_for_origin(self, origin: Optional[int]) -> contextvars.Context:
  334. channel = self._channel
  335. caller = channel.context_of(origin) if channel is not None else None
  336. return (caller or self._base_context).copy()
  337. def _handle(self, method: str, params: dict[str, Any], _origin: Optional[int]) -> Any:
  338. if method == "ctx":
  339. return self._serve_ctx(params)
  340. if method == "facade":
  341. return self._serve_facade(params)
  342. if method == "dispose":
  343. handle = self._handles.pop(int(params["handle"]), None)
  344. if handle is not None:
  345. handle.dispose()
  346. return None
  347. raise ValueError(f"unknown plugin host request {method!r}")
  348. def _plugin_ctx(self, params: dict[str, Any]) -> Any:
  349. ctx = self._contexts.get(str(params.get("plugin")))
  350. if ctx is None:
  351. raise LookupError(f"plugin {params.get('plugin')!r} is not loaded in this host")
  352. return ctx
  353. def _serve_ctx(self, params: dict[str, Any]) -> Any:
  354. from hermes_cli.plugin_isolation import (
  355. HOST_OBJECT_BASES, HOST_SKIPPED_CTX_METHODS, HOST_UNSUPPORTED_CTX_METHODS,
  356. )
  357. ctx = self._plugin_ctx(params)
  358. method = str(params.get("method") or "")
  359. if (method.startswith("_") or method in HOST_UNSUPPORTED_CTX_METHODS
  360. or method in HOST_SKIPPED_CTX_METHODS or method in {"on_unload", "spawn_task"}):
  361. raise PluginHostUnsupported(f"ctx.{method}() cannot be called across the plugin host")
  362. base = _import_ref(HOST_OBJECT_BASES[method]) if method in HOST_OBJECT_BASES else None
  363. resolve = functools.partial(self._resolve_ref, base=base)
  364. args = decode(params.get("args") or [], resolve)
  365. kwargs = decode(params.get("kwargs") or {}, resolve)
  366. result = getattr(ctx, method)(*args, **kwargs)
  367. return self._encode_for_host(result)
  368. def _serve_facade(self, params: dict[str, Any]) -> Any:
  369. from hermes_cli.plugin_isolation import HOST_REMOTE_FACADES
  370. ctx = self._plugin_ctx(params)
  371. facade, method = str(params.get("facade") or ""), str(params.get("method") or "")
  372. if facade not in HOST_REMOTE_FACADES or method.startswith("_"):
  373. raise PluginHostUnsupported(f"ctx.{facade}.{method} is not available in the plugin host")
  374. target = getattr(getattr(ctx, facade), method)
  375. if not callable(target):
  376. return self._encode_for_host(target)
  377. if params.get("probe"):
  378. return {"__method__": True, "async": inspect.iscoroutinefunction(target)}
  379. args = decode(params.get("args") or [], self._resolve_ref)
  380. kwargs = decode(params.get("kwargs") or {}, self._resolve_ref)
  381. result = target(*args, **kwargs)
  382. if asyncio.iscoroutine(result):
  383. result = _run_on_gateway_loop(result)
  384. return self._encode_for_host(result)
  385. def _encode_for_host(self, value: Any) -> Any:
  386. from hermes_cli.plugins_ledger import PluginRegistration
  387. def refs(obj: Any) -> Optional[dict]:
  388. if isinstance(obj, PluginRegistration):
  389. handle_id = next(self._handle_ids)
  390. self._handles[handle_id] = obj
  391. return {"__handle__": handle_id, "kind": obj.kind, "key": obj.key}
  392. return None
  393. return encode(value, refs)
  394. # -- proxies ------------------------------------------------------------------------------------
  395. def _resolve_ref(self, ref: dict[str, Any], base: Optional[type] = None) -> Any:
  396. if "__callable__" in ref:
  397. return self._callable_proxy(ref)
  398. if "__object__" in ref:
  399. if base is None:
  400. raise PluginHostUnsupported(f"a {ref.get('type', 'plugin')} object cannot be passed here "
  401. "across the plugin host")
  402. return self._object_proxy(ref, base)
  403. raise PluginHostUnsupported("registration handles are owned by the plugin host")
  404. def _resolve_result_ref(self, ref: dict[str, Any], base: Optional[type] = None) -> Any:
  405. """A provider object a hosted method returned (``ContextEngine.clone_for_agent``): a proxy when
  406. the contract declares that provider type, otherwise a placeholder (and the host drops it)."""
  407. if "__object__" in ref and base is None:
  408. self._release(self._generation, int(ref["__object__"]))
  409. return Opaque(str(ref.get("type") or "object"))
  410. return self._resolve_ref(ref, base)
  411. def _callable_proxy(self, ref: dict[str, Any]) -> Callable[..., Any]:
  412. ref_id, generation = int(ref["__callable__"]), self._generation
  413. async def async_proxy(*args: Any, **kwargs: Any) -> Any:
  414. return await asyncio.to_thread(self.invoke, ref_id, args, kwargs, generation=generation)
  415. def sync_proxy(*args: Any, **kwargs: Any) -> Any:
  416. return self.invoke(ref_id, args, kwargs, generation=generation)
  417. proxy: Any = async_proxy if ref.get("async") else sync_proxy
  418. signature = signature_from(ref.get("sig"))
  419. if signature is not None:
  420. proxy.__signature__ = signature # type: ignore[attr-defined]
  421. proxy.__name__ = str(ref.get("name") or "callback")
  422. proxy.__qualname__ = str(ref.get("qualname") or proxy.__name__)
  423. # Tool override policy and hook attribution key on the defining module.
  424. proxy.__module__ = str(ref.get("module") or __name__)
  425. proxy.__hermes_plugin_host_ref__ = ref_id # type: ignore[attr-defined]
  426. return proxy
  427. def _object_proxy(self, ref: dict[str, Any], base: type,
  428. reload: Optional[Callable[[], dict[str, Any]]] = None) -> Any:
  429. """An instance of ``base`` whose methods and public attributes live in the host. Attributes
  430. Hermes assigns go to the plugin's object when they can cross; live handles stay local."""
  431. host = self
  432. slot = _ObjectSlot(self, ref, reload)
  433. live = set(ref.get("live") or ())
  434. namespace: dict[str, Any] = {}
  435. for name, meta in (ref.get("methods") or {}).items():
  436. namespace[name] = _method_proxy(host, slot, name, meta, declared_return(base, name))
  437. def __getattribute__(self_: Any, name: str) -> Any:
  438. if name in live:
  439. return host.obj_getattr(slot, name, declared_return(base, name))
  440. return object.__getattribute__(self_, name)
  441. def __getattr__(self_: Any, name: str) -> Any:
  442. if name.startswith("_"):
  443. raise AttributeError(name)
  444. try:
  445. return host.obj_getattr(slot, name)
  446. except PluginHostUnavailable as exc: # ``hasattr``/``getattr(x, n, None)`` probes stay probes
  447. raise AttributeError(name) from exc
  448. def __setattr__(self_: Any, name: str, value: Any) -> None:
  449. if not name.startswith("_") and not _holds_live_handle(value):
  450. host.obj_setattr(slot, name, value)
  451. live.add(name)
  452. return
  453. live.discard(name)
  454. object.__setattr__(self_, name, value)
  455. namespace.update(__getattribute__=__getattribute__, __getattr__=__getattr__, __setattr__=__setattr__,
  456. __module__=__name__, __hermes_plugin_host_ref__=slot,
  457. __repr__=lambda self_: f"<plugin-host {ref.get('type')} #{slot.ref}>")
  458. cls = type(f"Hosted{ref.get('type') or base.__name__}", (base,), namespace)
  459. cls.__abstractmethods__ = frozenset()
  460. proxy = object.__new__(cls)
  461. slot.track(proxy)
  462. return proxy
  463. class _ObjectSlot:
  464. """Which host object (id + host generation) a proxy addresses; re-resolved after a host restart
  465. when the proxy knows how to load its plugin again."""
  466. def __init__(self, host: PluginHost, ref: dict[str, Any], reload: Optional[Callable[[], dict[str, Any]]]):
  467. self._host, self._reload = host, reload
  468. self.ref, self.generation = int(ref["__object__"]), int(ref.get("generation") or host._generation)
  469. self._finalizer: Optional[weakref.finalize] = None
  470. self._proxy: Optional[weakref.ref] = None
  471. def track(self, proxy: Any) -> None:
  472. self._proxy = weakref.ref(proxy)
  473. self._finalizer = weakref.finalize(proxy, self._host._release, self.generation, self.ref)
  474. def live(self) -> tuple:
  475. if (self.generation != self._host._generation or not self._host.alive) and self._reload is not None:
  476. fresh = self._reload()
  477. if self._finalizer is not None:
  478. self._finalizer.detach()
  479. self.ref, self.generation = int(fresh["__object__"]), int(fresh["generation"])
  480. proxy = self._proxy() if self._proxy is not None else None
  481. if proxy is not None:
  482. self.track(proxy)
  483. return self.ref, self.generation
  484. def _holds_live_handle(value: Any) -> bool:
  485. """True when ``value`` would reach the host only as an opaque placeholder (an agent, a client)."""
  486. found = False
  487. def refs(obj: Any) -> Optional[dict]:
  488. nonlocal found
  489. if callable(obj) or not (dataclasses.is_dataclass(obj) or hasattr(obj, "model_dump")):
  490. found = True
  491. return None
  492. encoded = encode(value, refs)
  493. return found or (isinstance(encoded, dict) and "__opaque__" in encoded)
  494. def is_hosted_object(obj: Any) -> bool:
  495. """``obj`` is a proxy for a plugin object whose code runs in the plugin host (``plugins.isolation:
  496. host``): its methods run there and anything they return that is not plain data arrives as an
  497. :class:`Opaque` placeholder."""
  498. return "__hermes_plugin_host_ref__" in vars(type(obj))
  499. def _run_on_gateway_loop(coro: Any) -> Any:
  500. """A facade coroutine (``platform_actions``) uses adapters bound to the gateway's event loop, so
  501. it runs there when a gateway is up; otherwise on a private loop. Always called off-loop (a
  502. channel thread), never from the loop itself."""
  503. try:
  504. from gateway.run import _gateway_runner_ref
  505. runner = _gateway_runner_ref()
  506. except Exception:
  507. runner = None
  508. loop = getattr(runner, "_gateway_loop", None)
  509. if loop is not None and loop.is_running() and not loop.is_closed():
  510. return asyncio.run_coroutine_threadsafe(coro, loop).result()
  511. return asyncio.run(coro)
  512. def _method_proxy(host: PluginHost, slot: _ObjectSlot, name: str, meta: dict[str, Any],
  513. returns: Any) -> Callable[..., Any]:
  514. async def async_method(self_: Any, *args: Any, **kwargs: Any) -> Any:
  515. return await asyncio.to_thread(host.obj_invoke, slot, name, args, kwargs, returns)
  516. def sync_method(self_: Any, *args: Any, **kwargs: Any) -> Any:
  517. return host.obj_invoke(slot, name, args, kwargs, returns)
  518. method: Any = async_method if meta.get("async") else sync_method
  519. method.__name__ = method.__qualname__ = name
  520. signature = signature_from(meta.get("sig"))
  521. if signature is not None: # callers introspect accepted kwargs; bound access drops ``self`` again
  522. self_param = inspect.Parameter("self", inspect.Parameter.POSITIONAL_OR_KEYWORD)
  523. method.__signature__ = signature.replace(parameters=[self_param, *signature.parameters.values()])
  524. return method
  525. def _host_object_base(hint: Any) -> Optional[type]:
  526. """``hint`` when it is a provider ABC a hosted object may stand in for (``HOST_OBJECT_BASES``)."""
  527. from hermes_cli.plugin_isolation import HOST_OBJECT_BASES
  528. if isinstance(hint, type) and f"{hint.__module__}:{hint.__qualname__}" in HOST_OBJECT_BASES.values():
  529. return hint
  530. return None
  531. def _import_ref(ref: str) -> type:
  532. module, attr = ref.split(":")
  533. return getattr(importlib.import_module(module), attr)
  534. def _pump_stderr(proc: subprocess.Popen, label: str) -> None:
  535. """Plugin output and host logs go to the Hermes log, tagged with the host's profile."""
  536. stream = proc.stderr
  537. if stream is None:
  538. return
  539. for raw in iter(stream.readline, b""):
  540. line = raw.decode("utf-8", "replace").rstrip()
  541. if line:
  542. logger.info("plugin host [%s]: %s", label, line)