"""Plugin-triggered gateway turns (``PluginContext.inject_message``): the process-wide injector this runner publishes, the thread-safe scheduler, and the dispatch through the adapter message path. Two targets: an existing session (``session_key``; route and session id pinned from the store) or a messaging chat (``origin``) whose session is created — or continued — through the normal session path in the calling plugin's OWN profile. The origin path never chooses a profile: the gateway's routing for that chat through that profile's adapter must already land in the plugin's profile, so a human follow-up in the same chat keys into the same session.""" from __future__ import annotations import asyncio import concurrent.futures import contextlib import logging import weakref from pathlib import Path from typing import Any, Mapping, Optional from gateway.config import Platform from gateway.platforms.event import MessageEvent, MessageType from gateway.session import SessionSource logger = logging.getLogger("gateway.run") class GatewayPluginInjectionMixin: def _install_plugin_message_injector(self) -> None: """Publish this live gateway's plugin message scheduler process-wide.""" from hermes_cli.plugins import publish_gateway_message_host publish_gateway_message_host(self, self._schedule_plugin_message_injection) def _clear_plugin_message_injector(self) -> None: """Remove this runner's scheduler without clobbering a newer owner.""" from hermes_cli.plugins import clear_published_gateway_message_host clear_published_gateway_message_host(self) def _schedule_plugin_message_injection( self, *, content: str, plugin_id: str, session_key: Optional[str] = None, origin: Optional[Mapping[str, Any]] = None, plugin_home: Optional[Path] = None, keyless: bool = False, calling_session_key: str = "", ) -> bool: """Schedule a plugin-triggered turn on the live gateway loop (thread-safe). With ``origin`` the profile, origin and adapter checks run here, synchronously, so the plugin gets ``False`` for a chat it may not start; authorization is rechecked at dispatch. ``keyless`` (neither given) picks the target here too (``gateway/plugin_keyless_inject.py``).""" from gateway.run import safe_schedule_threadsafe loop = getattr(self, "_gateway_loop", None) if not getattr(self, "_running", False) or loop is None or loop.is_closed(): return False if keyless: from gateway import plugin_keyless_inject resolved = plugin_keyless_inject.resolve(self, plugin_home=plugin_home, plugin_id=plugin_id, calling_session_key=calling_session_key) if resolved is None: return False target = f"session={resolved[1].route} (no key given)" coro = plugin_keyless_inject.admit(self, *resolved, content=content, plugin_id=plugin_id) elif origin is not None: source = self._plugin_origin_source(origin, plugin_home=plugin_home, plugin_id=plugin_id) if source is None or not self._plugin_origin_admissible(source, plugin_home=plugin_home, plugin_id=plugin_id): return False target = f"origin={source.platform.value}/{source.chat_id}" coro = self._dispatch_plugin_origin_injection(source=source, content=content, plugin_id=plugin_id) else: if not self._plugin_session_key_admissible(session_key, plugin_home=plugin_home, plugin_id=plugin_id): return False target = f"session={session_key}" coro = self._dispatch_plugin_message_injection( session_key=session_key, content=content, plugin_id=plugin_id, plugin_home=plugin_home, ) try: current_loop = asyncio.get_running_loop() except RuntimeError: current_loop = None if current_loop is loop: try: future = loop.create_task(coro) except Exception: coro.close() logger.warning("Plugin message injection scheduling failed", exc_info=True) return False self._background_tasks.add(future) future.add_done_callback(self._background_tasks.discard) else: future = safe_schedule_threadsafe( coro, loop, logger=logger, log_message="Plugin message injection scheduling failed", log_level=logging.WARNING, ) if future is None: return False def _log_result(completed) -> None: try: if completed.result(): return except (asyncio.CancelledError, concurrent.futures.CancelledError): return except Exception: # dispatch boundary: the plugin already got True; log, never raise logger.warning("Plugin message injection failed: plugin=%s %s", plugin_id, target, exc_info=True) return logger.warning("Plugin message injection was not routed: plugin=%s %s", plugin_id, target) future.add_done_callback(_log_result) return True def _plugin_injection_accepting(self) -> bool: return getattr(self, "_running", False) and not getattr(self, "_draining", False) def _plugin_injection_scope(self, source: SessionSource, home: Optional[Path] = None): """Multiplex: enter the source's profile runtime scope (or *home*'s, when the owner is known) around ``handle_message`` so the background task it spawns — the turn AND the reply send after the handler returns — inherits that profile's home and secrets (this coroutine runs from the default loop context, not from the profile adapter's own intake task).""" if getattr(getattr(self, "config", None), "multiplex_profiles", False) is not True: return contextlib.nullcontext() from gateway.run import _async_profile_runtime_scope return _async_profile_runtime_scope(home or self._resolve_profile_home_for_source(source)) def _plugin_injection_authorized(self, source: SessionSource, *, plugin_id: str, target: str) -> bool: """Current gateway authorization for the route the injected turn will run as. Host-side plugin code is trusted to ask, never to widen access: a stored or supplied route must pass today's allowlists / pairing / allow-all, and adapter-time grants (Discord roles) do not count.""" try: authorized = self._is_user_authorized_for_source(source, allow_adapter_delegation=False) except Exception: logger.warning("Plugin message injection authorization check failed: plugin=%s %s", plugin_id, target, exc_info=True) return False if not authorized: logger.warning("Plugin message injection denied by current gateway authorization: plugin=%s %s", plugin_id, target) return authorized def _plugin_session_key_admissible(self, session_key: str, *, plugin_home: Optional[Path], plugin_id: str) -> bool: """Synchronous refusal of a keyed injection into another profile's session (local or messaging), so the plugin gets ``False``; an unknown key is decided at dispatch, as before. Dispatch rechecks.""" entry = self.session_store.lookup_by_session_key(session_key) if entry is None or entry.origin is None: return True from gateway.session_identity import replace_source source = replace_source(self._restored_source(entry)) if source.platform == Platform.LOCAL: return self._plugin_local_session(source, session_key, plugin_home=plugin_home, plugin_id=plugin_id) is not None return self._plugin_messaging_session_owned(session_key, plugin_home=plugin_home, plugin_id=plugin_id) def _plugin_messaging_session_owned(self, session_key: str, *, plugin_home: Optional[Path], plugin_id: str) -> bool: """A messaging session belongs to the profile its key names (``agent::...``) under multiplexing, and to the one served profile of a standalone gateway; it must be the plugin's own, as on the origin path. A caller with no plugin home is left to dispatch, as before.""" if plugin_home is None: return True profile = self._served_profile_for_home(plugin_home) owner = profile if profile is not None and getattr(getattr(self, "config", None), "multiplex_profiles", False) is True: from hermes_state_keys import profile_from_session_key owner = profile_from_session_key(session_key) if profile is not None and owner == profile: return True logger.warning("Plugin message injection refused: plugin=%s session=%s belongs to profile %s, not the " "plugin's profile %s", plugin_id, session_key, owner, profile) return False def _plugin_local_session(self, source: SessionSource, session_key: str, *, plugin_home: Optional[Path], plugin_id: str): """A local session's own source passes no chat allowlist, so the plugin's profile boundary is the only check: the session authority registered for the plugin's immutable home must hold the live session under this key. Its ``LiveSession``, or ``None`` (logged). Never resolved through the source's profile, whose fallback is the ambient scope (a default-profile local source carries none, so under beta's scope it would read as beta's).""" from gateway.session_authorities import authority_for_home authority = authority_for_home(self, plugin_home) if plugin_home is not None else None live = authority.sessions.get(source.chat_id) if authority is not None else None if live is not None and live.route == session_key: return live logger.warning("Plugin message injection refused: plugin=%s session=%s is not a live local session of the " "plugin's profile home %s", plugin_id, session_key, plugin_home) return None async def _dispatch_plugin_message_injection( self, *, session_key: str, content: str, plugin_id: str, plugin_home: Optional[Path] = None, ) -> bool: """Route a plugin-triggered turn through the session's live adapter.""" if not self._plugin_injection_accepting(): return False entry = await self.async_session_store.lookup_by_session_key(session_key) if entry is None or entry.origin is None or not self._plugin_injection_accepting(): return False from gateway.session_identity import replace_source source = replace_source(self._restored_source(entry)) if source.platform == Platform.LOCAL: return await self._dispatch_plugin_local_injection(source, entry, content=content, plugin_id=plugin_id, plugin_home=plugin_home) if not self._plugin_messaging_session_owned(session_key, plugin_home=plugin_home, plugin_id=plugin_id): return False if not self._plugin_injection_authorized(source, plugin_id=plugin_id, target=f"session={session_key}"): return False adapter = self._delivery_adapter_for(source) if adapter is None: return False async with self._plugin_injection_scope(source): admitted = await self._admit_plugin_injection( adapter, source, session_key=session_key, session_id=entry.session_id, content=content, plugin_id=plugin_id) if admitted is not None: return admitted await adapter.handle_message(MessageEvent( text=content, message_type=MessageType.TEXT, source=source, internal=True, allow_gateway_control=False, metadata={ "hermes_plugin_id": plugin_id, "hermes_plugin_injection": True, "gateway_session_key": session_key, "gateway_session_id": entry.session_id, "gateway_session_strict": True, }, )) logger.info( "Plugin message injection dispatched: plugin=%s session=%s session_id=%s", plugin_id, session_key, entry.session_id, ) return True async def _dispatch_plugin_local_injection(self, source: SessionSource, entry, *, content: str, plugin_id: str, plugin_home: Optional[Path]) -> bool: """A local (CLI/TUI/Desktop) session has no messaging adapter or chat allowlist: the plugin turn is committed to its FIFO on the live session's own source and adapter, as a bot delivery is, only when the plugin's own profile's authority holds the session (checked before entering that scope). Main queued key-less CLI injections into the REPL; this is where they land now.""" live = self._plugin_local_session(source, entry.session_key, plugin_home=plugin_home, plugin_id=plugin_id) if live is None: return False async with self._plugin_injection_scope(source, plugin_home): return bool(await self._admit_plugin_injection( self._adapter_for_source(live.source), live.source, session_key=entry.session_key, session_id=entry.session_id, content=content, plugin_id=plugin_id)) def _served_profile_for_home(self, home: Optional[Path]) -> Optional[str]: """Name of the profile this gateway serves at *home* (a plugin manager's immutable home), or ``None`` when this gateway does not serve it.""" if home is None: return None from hermes_constants import get_routing_process_hermes_home, hermes_home_key key = hermes_home_key(home) if getattr(getattr(self, "config", None), "multiplex_profiles", False): from gateway.run import _multiplex_profile_homes try: served = _multiplex_profile_homes(self.config) except Exception: logger.warning("Plugin message injection: served-profile set unavailable", exc_info=True) return None return next((name for name, served_home in served if hermes_home_key(served_home) == key), None) if hermes_home_key(get_routing_process_hermes_home()) != key: return None return getattr(self, "_primary_profile_name", None) or self._active_profile_name() def _plugin_origin_source( self, origin: Mapping[str, Any], *, plugin_home: Optional[Path], plugin_id: str, ) -> Optional[SessionSource]: """The canonicalized source for a plugin-supplied *origin*, or ``None`` (logged) when the plugin may not start a turn there: its profile is not served, the origin is malformed or names another profile, that profile has no live adapter for the platform, or the gateway's own routing for the chat lands in a different profile.""" def _refuse(reason: str, *args: Any) -> None: logger.warning("Plugin message injection refused: plugin=%s " + reason, plugin_id, *args) profile = self._served_profile_for_home(plugin_home) if profile is None: return _refuse("its profile home %s is not served by this gateway", plugin_home) fields = dict(origin) requested = fields.pop("profile", None) if requested and requested != profile: return _refuse("origin names profile %r; plugins may only start sessions in their own profile (%s)", requested, profile) try: source = SessionSource.from_dict(fields) except (KeyError, TypeError, ValueError) as exc: return _refuse("invalid origin (%s)", exc) where = f"{source.platform.value}/{source.chat_id}" adapter = self._adapters_for_profile(profile).get(source.platform) if adapter is None: return _refuse("no connected %s adapter for profile %s", source.platform.value, profile) # Same provenance build_source() stamps on a live inbound event from this adapter, so the # identity (receiving bot, runtime profile, authorization home) resolves exactly as it would # for a human message in this chat. source._transport_adapter_ref = weakref.ref(adapter) identity = self._canonicalize(source) if identity is None: return _refuse("origin %s does not resolve to a served profile", where) if identity.runtime_profile != profile: return _refuse("origin %s routes to profile %s, not the plugin's profile %s", where, identity.runtime_profile, profile) return source def _plugin_origin_admissible(self, source: SessionSource, *, plugin_home: Optional[Path], plugin_id: str) -> bool: """Under the session authority a plugin turn borrows the connector provenance of a human message already committed in that chat, and the gateway never mints it for a chat the platform did not deliver: refuse such an origin here, so the plugin gets ``False`` instead of a ``True`` for a turn the dispatch then drops. Dispatch rechecks.""" from gateway.session_authorities import authority_for_home from gateway.session_automation import committed_route_envelope authority = authority_for_home(self, plugin_home) if plugin_home is not None else None if authority is None: return True # no authority: the adapter's normal session path creates the session entry = self.session_store.lookup_by_session_key(self._session_key_for_source(source)) if entry is not None and committed_route_envelope(authority, entry) is not None: return True logger.warning("Plugin message injection refused: plugin=%s origin=%s/%s has no human message admitted " "yet; a plugin can continue a chat, not open one", plugin_id, source.platform.value, source.chat_id) return False async def _dispatch_plugin_origin_injection( self, *, source: SessionSource, content: str, plugin_id: str ) -> bool: """Start (or continue) the session at a plugin-supplied origin through the adapter's normal message path: ``get_or_create_session`` creates it, the reply goes back to that chat.""" target = f"origin={source.platform.value}/{source.chat_id}" if not self._plugin_injection_accepting(): return False adapter = self._delivery_adapter_for(source) if adapter is None: logger.warning("Plugin message injection: adapter for %s went away before dispatch", target) return False if not self._plugin_injection_authorized(source, plugin_id=plugin_id, target=target): return False session_key = self._session_key_for_source(source) async with self._plugin_injection_scope(source): from gateway.session_authorities import active_authority if active_authority(self) is not None: # The FIFO admits a producer turn only into a session that already holds a # committed human turn (its connector provenance is borrowed, never minted), so # an origin with no session yet is refused rather than run outside the FIFO. entry = await self.async_session_store.lookup_by_session_key(session_key) if entry is None: logger.warning("Plugin message injection refused: plugin=%s %s has no session under " "the session authority yet", plugin_id, target) return False return await self._admit_plugin_injection( adapter, source, session_key=session_key, session_id=entry.session_id, content=content, plugin_id=plugin_id) await adapter.handle_message(MessageEvent( text=content, message_type=MessageType.TEXT, source=source, internal=True, allow_gateway_control=False, # Non-strict: the key is pinned against topic recovery, the session may not exist yet. metadata={ "hermes_plugin_id": plugin_id, "hermes_plugin_injection": True, "gateway_session_key": session_key, }, )) logger.info("Plugin message injection dispatched: plugin=%s %s session=%s", plugin_id, target, session_key) return True async def _admit_plugin_injection( self, adapter, source: SessionSource, *, session_key: str, session_id: str, content: str, plugin_id: str, ) -> Optional[bool]: """Under a session authority, commit the plugin turn into the session's durable FIFO as a trusted producer admission (the heartbeat / completion seam) instead of running it on the in-process lane beside an admitted turn. ``None`` means no authority serves this scope and the caller keeps the standalone adapter path; a refused admission is ``False``, logged.""" from gateway.session_authorities import active_authority authority = active_authority(self) if authority is None: return None import json import uuid from hermes_state_runtime import RuntimeStoreError identity = json.dumps(["plugin", plugin_id, session_key, uuid.uuid4().hex], separators=(",", ":")) event = MessageEvent( text=content, message_type=MessageType.TEXT, source=source, internal=True, allow_gateway_control=False, message_id=identity, metadata={"gateway_session_key": session_key, "gateway_session_id": session_id}, ) try: await authority.admit_automation(adapter, event, identity) except RuntimeStoreError as exc: logger.warning("Plugin message injection refused by the session authority: plugin=%s session=%s (%s)", plugin_id, session_key, exc.reason) return False logger.info("Plugin message injection admitted: plugin=%s session=%s session_id=%s", plugin_id, session_key, session_id) return True