run_plugin_injection.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392
  1. """Plugin-triggered gateway turns (``PluginContext.inject_message``): the process-wide injector this
  2. runner publishes, the thread-safe scheduler, and the dispatch through the adapter message path.
  3. Two targets: an existing session (``session_key``; route and session id pinned from the store) or a
  4. messaging chat (``origin``) whose session is created — or continued — through the normal session path
  5. in the calling plugin's OWN profile. The origin path never chooses a profile: the gateway's routing
  6. for that chat through that profile's adapter must already land in the plugin's profile, so a human
  7. follow-up in the same chat keys into the same session."""
  8. from __future__ import annotations
  9. import asyncio
  10. import concurrent.futures
  11. import contextlib
  12. import logging
  13. import weakref
  14. from pathlib import Path
  15. from typing import Any, Mapping, Optional
  16. from gateway.config import Platform
  17. from gateway.platforms.event import MessageEvent, MessageType
  18. from gateway.session import SessionSource
  19. logger = logging.getLogger("gateway.run")
  20. class GatewayPluginInjectionMixin:
  21. def _install_plugin_message_injector(self) -> None:
  22. """Publish this live gateway's plugin message scheduler process-wide."""
  23. from hermes_cli.plugins import publish_gateway_message_host
  24. publish_gateway_message_host(self, self._schedule_plugin_message_injection)
  25. def _clear_plugin_message_injector(self) -> None:
  26. """Remove this runner's scheduler without clobbering a newer owner."""
  27. from hermes_cli.plugins import clear_published_gateway_message_host
  28. clear_published_gateway_message_host(self)
  29. def _schedule_plugin_message_injection(
  30. self, *, content: str, plugin_id: str, session_key: Optional[str] = None,
  31. origin: Optional[Mapping[str, Any]] = None, plugin_home: Optional[Path] = None,
  32. keyless: bool = False, calling_session_key: str = "",
  33. ) -> bool:
  34. """Schedule a plugin-triggered turn on the live gateway loop (thread-safe).
  35. With ``origin`` the profile, origin and adapter checks run here, synchronously, so the plugin
  36. gets ``False`` for a chat it may not start; authorization is rechecked at dispatch. ``keyless``
  37. (neither given) picks the target here too (``gateway/plugin_keyless_inject.py``)."""
  38. from gateway.run import safe_schedule_threadsafe
  39. loop = getattr(self, "_gateway_loop", None)
  40. if not getattr(self, "_running", False) or loop is None or loop.is_closed():
  41. return False
  42. if keyless:
  43. from gateway import plugin_keyless_inject
  44. resolved = plugin_keyless_inject.resolve(self, plugin_home=plugin_home, plugin_id=plugin_id,
  45. calling_session_key=calling_session_key)
  46. if resolved is None:
  47. return False
  48. target = f"session={resolved[1].route} (no key given)"
  49. coro = plugin_keyless_inject.admit(self, *resolved, content=content, plugin_id=plugin_id)
  50. elif origin is not None:
  51. source = self._plugin_origin_source(origin, plugin_home=plugin_home, plugin_id=plugin_id)
  52. if source is None or not self._plugin_origin_admissible(source, plugin_home=plugin_home,
  53. plugin_id=plugin_id):
  54. return False
  55. target = f"origin={source.platform.value}/{source.chat_id}"
  56. coro = self._dispatch_plugin_origin_injection(source=source, content=content, plugin_id=plugin_id)
  57. else:
  58. if not self._plugin_session_key_admissible(session_key, plugin_home=plugin_home, plugin_id=plugin_id):
  59. return False
  60. target = f"session={session_key}"
  61. coro = self._dispatch_plugin_message_injection(
  62. session_key=session_key, content=content, plugin_id=plugin_id, plugin_home=plugin_home,
  63. )
  64. try:
  65. current_loop = asyncio.get_running_loop()
  66. except RuntimeError:
  67. current_loop = None
  68. if current_loop is loop:
  69. try:
  70. future = loop.create_task(coro)
  71. except Exception:
  72. coro.close()
  73. logger.warning("Plugin message injection scheduling failed", exc_info=True)
  74. return False
  75. self._background_tasks.add(future)
  76. future.add_done_callback(self._background_tasks.discard)
  77. else:
  78. future = safe_schedule_threadsafe(
  79. coro, loop, logger=logger, log_message="Plugin message injection scheduling failed",
  80. log_level=logging.WARNING,
  81. )
  82. if future is None:
  83. return False
  84. def _log_result(completed) -> None:
  85. try:
  86. if completed.result():
  87. return
  88. except (asyncio.CancelledError, concurrent.futures.CancelledError):
  89. return
  90. except Exception: # dispatch boundary: the plugin already got True; log, never raise
  91. logger.warning("Plugin message injection failed: plugin=%s %s", plugin_id, target, exc_info=True)
  92. return
  93. logger.warning("Plugin message injection was not routed: plugin=%s %s", plugin_id, target)
  94. future.add_done_callback(_log_result)
  95. return True
  96. def _plugin_injection_accepting(self) -> bool:
  97. return getattr(self, "_running", False) and not getattr(self, "_draining", False)
  98. def _plugin_injection_scope(self, source: SessionSource, home: Optional[Path] = None):
  99. """Multiplex: enter the source's profile runtime scope (or *home*'s, when the owner is known)
  100. around ``handle_message`` so the background task it spawns — the turn AND the reply send after
  101. the handler returns — inherits that profile's home and secrets (this coroutine runs from the
  102. default loop context, not from the profile adapter's own intake task)."""
  103. if getattr(getattr(self, "config", None), "multiplex_profiles", False) is not True:
  104. return contextlib.nullcontext()
  105. from gateway.run import _async_profile_runtime_scope
  106. return _async_profile_runtime_scope(home or self._resolve_profile_home_for_source(source))
  107. def _plugin_injection_authorized(self, source: SessionSource, *, plugin_id: str, target: str) -> bool:
  108. """Current gateway authorization for the route the injected turn will run as. Host-side
  109. plugin code is trusted to ask, never to widen access: a stored or supplied route must pass
  110. today's allowlists / pairing / allow-all, and adapter-time grants (Discord roles) do not count."""
  111. try:
  112. authorized = self._is_user_authorized_for_source(source, allow_adapter_delegation=False)
  113. except Exception:
  114. logger.warning("Plugin message injection authorization check failed: plugin=%s %s",
  115. plugin_id, target, exc_info=True)
  116. return False
  117. if not authorized:
  118. logger.warning("Plugin message injection denied by current gateway authorization: plugin=%s %s",
  119. plugin_id, target)
  120. return authorized
  121. def _plugin_session_key_admissible(self, session_key: str, *, plugin_home: Optional[Path], plugin_id: str) -> bool:
  122. """Synchronous refusal of a keyed injection into another profile's session (local or
  123. messaging), so the plugin gets ``False``; an unknown key is decided at dispatch, as before.
  124. Dispatch rechecks."""
  125. entry = self.session_store.lookup_by_session_key(session_key)
  126. if entry is None or entry.origin is None:
  127. return True
  128. from gateway.session_identity import replace_source
  129. source = replace_source(self._restored_source(entry))
  130. if source.platform == Platform.LOCAL:
  131. return self._plugin_local_session(source, session_key, plugin_home=plugin_home,
  132. plugin_id=plugin_id) is not None
  133. return self._plugin_messaging_session_owned(session_key, plugin_home=plugin_home, plugin_id=plugin_id)
  134. def _plugin_messaging_session_owned(self, session_key: str, *, plugin_home: Optional[Path],
  135. plugin_id: str) -> bool:
  136. """A messaging session belongs to the profile its key names (``agent:<profile>:...``) under
  137. multiplexing, and to the one served profile of a standalone gateway; it must be the plugin's
  138. own, as on the origin path. A caller with no plugin home is left to dispatch, as before."""
  139. if plugin_home is None:
  140. return True
  141. profile = self._served_profile_for_home(plugin_home)
  142. owner = profile
  143. if profile is not None and getattr(getattr(self, "config", None), "multiplex_profiles", False) is True:
  144. from hermes_state_keys import profile_from_session_key
  145. owner = profile_from_session_key(session_key)
  146. if profile is not None and owner == profile:
  147. return True
  148. logger.warning("Plugin message injection refused: plugin=%s session=%s belongs to profile %s, not the "
  149. "plugin's profile %s", plugin_id, session_key, owner, profile)
  150. return False
  151. def _plugin_local_session(self, source: SessionSource, session_key: str, *, plugin_home: Optional[Path],
  152. plugin_id: str):
  153. """A local session's own source passes no chat allowlist, so the plugin's profile boundary is
  154. the only check: the session authority registered for the plugin's immutable home must hold
  155. the live session under this key. Its ``LiveSession``, or ``None`` (logged). Never resolved
  156. through the source's profile, whose fallback is the ambient scope (a default-profile local
  157. source carries none, so under beta's scope it would read as beta's)."""
  158. from gateway.session_authorities import authority_for_home
  159. authority = authority_for_home(self, plugin_home) if plugin_home is not None else None
  160. live = authority.sessions.get(source.chat_id) if authority is not None else None
  161. if live is not None and live.route == session_key:
  162. return live
  163. logger.warning("Plugin message injection refused: plugin=%s session=%s is not a live local session of the "
  164. "plugin's profile home %s", plugin_id, session_key, plugin_home)
  165. return None
  166. async def _dispatch_plugin_message_injection(
  167. self, *, session_key: str, content: str, plugin_id: str, plugin_home: Optional[Path] = None,
  168. ) -> bool:
  169. """Route a plugin-triggered turn through the session's live adapter."""
  170. if not self._plugin_injection_accepting():
  171. return False
  172. entry = await self.async_session_store.lookup_by_session_key(session_key)
  173. if entry is None or entry.origin is None or not self._plugin_injection_accepting():
  174. return False
  175. from gateway.session_identity import replace_source
  176. source = replace_source(self._restored_source(entry))
  177. if source.platform == Platform.LOCAL:
  178. return await self._dispatch_plugin_local_injection(source, entry, content=content, plugin_id=plugin_id,
  179. plugin_home=plugin_home)
  180. if not self._plugin_messaging_session_owned(session_key, plugin_home=plugin_home, plugin_id=plugin_id):
  181. return False
  182. if not self._plugin_injection_authorized(source, plugin_id=plugin_id, target=f"session={session_key}"):
  183. return False
  184. adapter = self._delivery_adapter_for(source)
  185. if adapter is None:
  186. return False
  187. async with self._plugin_injection_scope(source):
  188. admitted = await self._admit_plugin_injection(
  189. adapter, source, session_key=session_key, session_id=entry.session_id,
  190. content=content, plugin_id=plugin_id)
  191. if admitted is not None:
  192. return admitted
  193. await adapter.handle_message(MessageEvent(
  194. text=content, message_type=MessageType.TEXT, source=source, internal=True,
  195. allow_gateway_control=False,
  196. metadata={
  197. "hermes_plugin_id": plugin_id, "hermes_plugin_injection": True,
  198. "gateway_session_key": session_key, "gateway_session_id": entry.session_id,
  199. "gateway_session_strict": True,
  200. },
  201. ))
  202. logger.info(
  203. "Plugin message injection dispatched: plugin=%s session=%s session_id=%s",
  204. plugin_id, session_key, entry.session_id,
  205. )
  206. return True
  207. async def _dispatch_plugin_local_injection(self, source: SessionSource, entry, *, content: str,
  208. plugin_id: str, plugin_home: Optional[Path]) -> bool:
  209. """A local (CLI/TUI/Desktop) session has no messaging adapter or chat allowlist: the plugin
  210. turn is committed to its FIFO on the live session's own source and adapter, as a bot delivery
  211. is, only when the plugin's own profile's authority holds the session (checked before entering
  212. that scope). Main queued key-less CLI injections into the REPL; this is where they land now."""
  213. live = self._plugin_local_session(source, entry.session_key, plugin_home=plugin_home, plugin_id=plugin_id)
  214. if live is None:
  215. return False
  216. async with self._plugin_injection_scope(source, plugin_home):
  217. return bool(await self._admit_plugin_injection(
  218. self._adapter_for_source(live.source), live.source, session_key=entry.session_key,
  219. session_id=entry.session_id, content=content, plugin_id=plugin_id))
  220. def _served_profile_for_home(self, home: Optional[Path]) -> Optional[str]:
  221. """Name of the profile this gateway serves at *home* (a plugin manager's immutable home), or
  222. ``None`` when this gateway does not serve it."""
  223. if home is None:
  224. return None
  225. from hermes_constants import get_routing_process_hermes_home, hermes_home_key
  226. key = hermes_home_key(home)
  227. if getattr(getattr(self, "config", None), "multiplex_profiles", False):
  228. from gateway.run import _multiplex_profile_homes
  229. try:
  230. served = _multiplex_profile_homes(self.config)
  231. except Exception:
  232. logger.warning("Plugin message injection: served-profile set unavailable", exc_info=True)
  233. return None
  234. return next((name for name, served_home in served if hermes_home_key(served_home) == key), None)
  235. if hermes_home_key(get_routing_process_hermes_home()) != key:
  236. return None
  237. return getattr(self, "_primary_profile_name", None) or self._active_profile_name()
  238. def _plugin_origin_source(
  239. self, origin: Mapping[str, Any], *, plugin_home: Optional[Path], plugin_id: str,
  240. ) -> Optional[SessionSource]:
  241. """The canonicalized source for a plugin-supplied *origin*, or ``None`` (logged) when the
  242. plugin may not start a turn there: its profile is not served, the origin is malformed or
  243. names another profile, that profile has no live adapter for the platform, or the gateway's
  244. own routing for the chat lands in a different profile."""
  245. def _refuse(reason: str, *args: Any) -> None:
  246. logger.warning("Plugin message injection refused: plugin=%s " + reason, plugin_id, *args)
  247. profile = self._served_profile_for_home(plugin_home)
  248. if profile is None:
  249. return _refuse("its profile home %s is not served by this gateway", plugin_home)
  250. fields = dict(origin)
  251. requested = fields.pop("profile", None)
  252. if requested and requested != profile:
  253. return _refuse("origin names profile %r; plugins may only start sessions in their own profile (%s)",
  254. requested, profile)
  255. try:
  256. source = SessionSource.from_dict(fields)
  257. except (KeyError, TypeError, ValueError) as exc:
  258. return _refuse("invalid origin (%s)", exc)
  259. where = f"{source.platform.value}/{source.chat_id}"
  260. adapter = self._adapters_for_profile(profile).get(source.platform)
  261. if adapter is None:
  262. return _refuse("no connected %s adapter for profile %s", source.platform.value, profile)
  263. # Same provenance build_source() stamps on a live inbound event from this adapter, so the
  264. # identity (receiving bot, runtime profile, authorization home) resolves exactly as it would
  265. # for a human message in this chat.
  266. source._transport_adapter_ref = weakref.ref(adapter)
  267. identity = self._canonicalize(source)
  268. if identity is None:
  269. return _refuse("origin %s does not resolve to a served profile", where)
  270. if identity.runtime_profile != profile:
  271. return _refuse("origin %s routes to profile %s, not the plugin's profile %s",
  272. where, identity.runtime_profile, profile)
  273. return source
  274. def _plugin_origin_admissible(self, source: SessionSource, *, plugin_home: Optional[Path], plugin_id: str) -> bool:
  275. """Under the session authority a plugin turn borrows the connector provenance of a human
  276. message already committed in that chat, and the gateway never mints it for a chat the
  277. platform did not deliver: refuse such an origin here, so the plugin gets ``False`` instead of
  278. a ``True`` for a turn the dispatch then drops. Dispatch rechecks."""
  279. from gateway.session_authorities import authority_for_home
  280. from gateway.session_automation import committed_route_envelope
  281. authority = authority_for_home(self, plugin_home) if plugin_home is not None else None
  282. if authority is None:
  283. return True # no authority: the adapter's normal session path creates the session
  284. entry = self.session_store.lookup_by_session_key(self._session_key_for_source(source))
  285. if entry is not None and committed_route_envelope(authority, entry) is not None:
  286. return True
  287. logger.warning("Plugin message injection refused: plugin=%s origin=%s/%s has no human message admitted "
  288. "yet; a plugin can continue a chat, not open one", plugin_id, source.platform.value,
  289. source.chat_id)
  290. return False
  291. async def _dispatch_plugin_origin_injection(
  292. self, *, source: SessionSource, content: str, plugin_id: str
  293. ) -> bool:
  294. """Start (or continue) the session at a plugin-supplied origin through the adapter's normal
  295. message path: ``get_or_create_session`` creates it, the reply goes back to that chat."""
  296. target = f"origin={source.platform.value}/{source.chat_id}"
  297. if not self._plugin_injection_accepting():
  298. return False
  299. adapter = self._delivery_adapter_for(source)
  300. if adapter is None:
  301. logger.warning("Plugin message injection: adapter for %s went away before dispatch", target)
  302. return False
  303. if not self._plugin_injection_authorized(source, plugin_id=plugin_id, target=target):
  304. return False
  305. session_key = self._session_key_for_source(source)
  306. async with self._plugin_injection_scope(source):
  307. from gateway.session_authorities import active_authority
  308. if active_authority(self) is not None:
  309. # The FIFO admits a producer turn only into a session that already holds a
  310. # committed human turn (its connector provenance is borrowed, never minted), so
  311. # an origin with no session yet is refused rather than run outside the FIFO.
  312. entry = await self.async_session_store.lookup_by_session_key(session_key)
  313. if entry is None:
  314. logger.warning("Plugin message injection refused: plugin=%s %s has no session under "
  315. "the session authority yet", plugin_id, target)
  316. return False
  317. return await self._admit_plugin_injection(
  318. adapter, source, session_key=session_key, session_id=entry.session_id,
  319. content=content, plugin_id=plugin_id)
  320. await adapter.handle_message(MessageEvent(
  321. text=content, message_type=MessageType.TEXT, source=source, internal=True,
  322. allow_gateway_control=False,
  323. # Non-strict: the key is pinned against topic recovery, the session may not exist yet.
  324. metadata={
  325. "hermes_plugin_id": plugin_id, "hermes_plugin_injection": True,
  326. "gateway_session_key": session_key,
  327. },
  328. ))
  329. logger.info("Plugin message injection dispatched: plugin=%s %s session=%s", plugin_id, target, session_key)
  330. return True
  331. async def _admit_plugin_injection(
  332. self, adapter, source: SessionSource, *, session_key: str, session_id: str, content: str,
  333. plugin_id: str,
  334. ) -> Optional[bool]:
  335. """Under a session authority, commit the plugin turn into the session's durable FIFO as a
  336. trusted producer admission (the heartbeat / completion seam) instead of running it on the
  337. in-process lane beside an admitted turn. ``None`` means no authority serves this scope and
  338. the caller keeps the standalone adapter path; a refused admission is ``False``, logged."""
  339. from gateway.session_authorities import active_authority
  340. authority = active_authority(self)
  341. if authority is None:
  342. return None
  343. import json
  344. import uuid
  345. from hermes_state_runtime import RuntimeStoreError
  346. identity = json.dumps(["plugin", plugin_id, session_key, uuid.uuid4().hex], separators=(",", ":"))
  347. event = MessageEvent(
  348. text=content, message_type=MessageType.TEXT, source=source, internal=True,
  349. allow_gateway_control=False, message_id=identity,
  350. metadata={"gateway_session_key": session_key, "gateway_session_id": session_id},
  351. )
  352. try:
  353. await authority.admit_automation(adapter, event, identity)
  354. except RuntimeStoreError as exc:
  355. logger.warning("Plugin message injection refused by the session authority: plugin=%s session=%s (%s)",
  356. plugin_id, session_key, exc.reason)
  357. return False
  358. logger.info("Plugin message injection admitted: plugin=%s session=%s session_id=%s",
  359. plugin_id, session_key, session_id)
  360. return True