run_inbound_hooks.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. """Plugin and user extension points on the inbound pipeline (moved out of ``gateway/run_inbound.py``).
  2. ``pre_gateway_dispatch`` (before auth), ``post_gateway_admission`` (once per admitted inbound
  3. message, #129958), ``pre_command`` / ``command:<name>`` hooks, user ``quick_commands`` and
  4. plugin-registered slash commands. Bound onto ``GatewayRunner`` through ``GatewayInboundMixin``.
  5. """
  6. from __future__ import annotations
  7. import asyncio
  8. import contextlib
  9. import dataclasses
  10. import functools
  11. import inspect
  12. import logging
  13. import os
  14. import signal
  15. import sys
  16. from typing import Optional, Tuple
  17. from agent.i18n import t
  18. from gateway.platforms.event import MessageEvent
  19. from gateway.session import SessionSource, build_session_context
  20. # Log-record parity with the origin module.
  21. logger = logging.getLogger("gateway.run")
  22. # Seconds a ``type: exec`` quick command may run before its whole process tree is killed.
  23. _EXEC_QUICK_COMMAND_TIMEOUT = 30
  24. async def _stop_exec_tree(proc) -> None:
  25. """Kill an exec quick command's shell and everything it started, then reap the shell (bounded).
  26. Killing only the shell leaves ``sleep 120 & wait``'s sleep running. ``kill_process_tree`` reaches
  27. descendants (``taskkill /T`` on Windows); on POSIX the group the shell led also catches members
  28. that already outlived it."""
  29. if proc.returncode is None:
  30. from agent.deadline import kill_process_tree
  31. await asyncio.to_thread(kill_process_tree, proc.pid)
  32. if sys.platform != "win32":
  33. with contextlib.suppress(ProcessLookupError, PermissionError):
  34. os.killpg(proc.pid, signal.SIGKILL) # windows-footgun: ok — POSIX-only branch; start_new_session made pid the pgid
  35. with contextlib.suppress(TimeoutError):
  36. await asyncio.wait_for(proc.wait(), timeout=5)
  37. class GatewayInboundHooksMixin:
  38. """Hook, quick-command and plugin-command dispatch for ``GatewayInboundMixin``."""
  39. async def _hm_post_admission_consume(
  40. self, event: MessageEvent, source: SessionSource, session_key: str
  41. ) -> tuple[bool, Optional[str]]:
  42. """``post_gateway_admission`` exactly once per inbound message: ``(consumed, reply)``.
  43. Never while an admitted row EXECUTES (first run or restart replay): the authority path
  44. already offered the message at ingress, before its commit, so a consumed message is never
  45. admitted and an admitted one is never offered twice."""
  46. from gateway.session_ingress import executing_admission
  47. if executing_admission.get():
  48. return False, None
  49. from gateway.run_inbound_consumer import run_post_admission_hook
  50. return await run_post_admission_hook(self, event, source, session_key)
  51. async def _hm_pre_gateway_dispatch_hook(
  52. self, event: MessageEvent, source: SessionSource
  53. ) -> Optional[MessageEvent]:
  54. """Run the ``pre_gateway_dispatch`` plugin hook; None = drop, else the (maybe rewritten) event.
  55. Results: ``{"action": "skip"}`` → drop; ``{"action": "rewrite", "text"}`` → replace ``event.text``;
  56. ``allow``/None → normal dispatch. On the messaging path it runs BEFORE auth so plugins can handle
  57. unauthorized senders; on the producer path (webhook/relay, ``admit_producer``) it runs AFTER the
  58. delivery's authorization, which preparing its payload performs, so it never sees a refused sender.
  59. Once per inbound message, at ingress (here, or ``admit_producer`` for webhook/relay), never
  60. while an admitted row EXECUTES: a messaging turn already passed it before its commit, and a
  61. local CLI/TUI/Desktop turn never fired it on main, so a skip must not drop committed input."""
  62. from gateway.session_ingress import executing_admission
  63. if executing_admission.get():
  64. return event
  65. try:
  66. from hermes_cli.lifecycle import ainvoke_hook as _ainvoke_hook
  67. _hook_results = await _ainvoke_hook(
  68. "pre_gateway_dispatch", event=event, gateway=self,
  69. # getattr: bare-runner tests build GatewayRunner via object.__new__ without __init__.
  70. session_store=getattr(self, "session_store", None),
  71. )
  72. except Exception as _hook_exc: # health: allow BLE001 -- moved unchanged from run_inbound.py (main has the same handler): a plugin hook must never stop dispatch
  73. logger.warning("pre_gateway_dispatch invocation failed: %s", _hook_exc)
  74. _hook_results = []
  75. for _result in _hook_results:
  76. if not isinstance(_result, dict):
  77. continue
  78. _action = _result.get("action")
  79. if _action == "skip":
  80. logger.info(
  81. "pre_gateway_dispatch skip: reason=%s platform=%s chat=%s",
  82. _result.get("reason"), source.platform.value if source.platform else "unknown",
  83. source.chat_id or "unknown",
  84. )
  85. return None
  86. if _action == "rewrite":
  87. _new_text = _result.get("text")
  88. if isinstance(_new_text, str):
  89. from gateway.session_ingress_context import carry_callback
  90. rewritten = dataclasses.replace(event, text=_new_text)
  91. carry_callback(event, rewritten)
  92. event = rewritten
  93. break
  94. if _action == "allow":
  95. break
  96. return event
  97. def _hm_quick_commands(self) -> dict:
  98. """User-defined ``quick_commands`` mapping from config (empty dict when unset/malformed)."""
  99. cfg = self.config
  100. qc = (cfg.get("quick_commands") if isinstance(cfg, dict) else getattr(cfg, "quick_commands", None)) or {}
  101. return qc if isinstance(qc, dict) else {}
  102. @staticmethod
  103. def _hm_expand_alias_quick_command(event: MessageEvent, qcmd: dict) -> Optional[str]:
  104. """Rewrite ``event.text`` to an alias quick command's target; returns the new command name."""
  105. target = (qcmd.get("target") or "").strip()
  106. if not target:
  107. return None
  108. target = target if target.startswith("/") else f"/{target}"
  109. event.text = f"{target} {event.get_command_args().strip()}".strip()
  110. target_command = target.lstrip("/")
  111. return target_command.split()[0] if target_command else target_command
  112. async def _hm_command_hooks(
  113. self, event: MessageEvent, source: SessionSource, _quick_key: str, command: str, canonical: str
  114. ) -> tuple[bool, Optional[str], Optional[str]]:
  115. """Fire ``pre_command`` (observer) and ``command:<canonical>`` (interceptor) hooks →
  116. ``(handled, result, new_command)`` (``new_command`` set when a handler rewrote the command).
  117. The running-agent path deliberately does NOT fire these — a slow or hostile plugin must not
  118. interfere with the operator's escape hatches for a live agent."""
  119. raw_args = event.get_command_args().strip()
  120. platform = source.platform.value if source.platform else ""
  121. try:
  122. from hermes_cli.plugins import fire_pre_command_hook
  123. fire_pre_command_hook(
  124. surface="gateway", command=str(canonical), alias_used=str(command),
  125. args_raw=raw_args, session_key=_quick_key, platform=platform,
  126. )
  127. except Exception as _pre_cmd_err:
  128. logger.debug("pre_command hook dispatch failed (non-fatal): %s", _pre_cmd_err, exc_info=True)
  129. # Handlers may return ``{"decision": "deny" | "handled" | "rewrite", ...}`` to intercept
  130. # dispatch; handlers returning nothing behave as plain observers.
  131. hook_ctx = {
  132. "platform": platform, "user_id": source.user_id, "command": canonical,
  133. "raw_command": command, "args": raw_args, "raw_args": raw_args,
  134. }
  135. try:
  136. hook_results = await self.hooks.emit_collect(f"command:{canonical}", hook_ctx)
  137. except Exception as _hook_err:
  138. logger.debug("command:%s hook dispatch failed (non-fatal): %s", canonical, _hook_err, exc_info=True)
  139. hook_results = []
  140. for hook_result in hook_results:
  141. if not isinstance(hook_result, dict):
  142. continue
  143. decision = str(hook_result.get("decision", "")).strip().lower()
  144. message = hook_result.get("message")
  145. message = message if isinstance(message, str) and message else None
  146. if decision == "deny":
  147. return True, message or t("gateway.hooks.command_blocked", command=command), None
  148. if decision == "handled":
  149. return True, message, None
  150. if decision == "rewrite":
  151. new_command = str(hook_result.get("command_name", "")).strip().lstrip("/")
  152. if new_command:
  153. event.text = f"/{new_command} {str(hook_result.get('raw_args', '')).strip()}".strip()
  154. return False, None, event.get_command()
  155. return False, None, None
  156. async def _hm_run_exec_quick_command(self, command: str, exec_cmd: str, cwd: Optional[str] = None) -> str:
  157. """Run a ``type: exec`` quick command as a host shell of the gateway process: sanitized env
  158. (the gateway process has every API key in os.environ), redacted output, its process tree
  159. killed after 30 s or when the awaiting task is cancelled (gateway shutdown).
  160. ``cwd`` is a local session's folder; None keeps the gateway's own (messaging)."""
  161. proc = None
  162. try:
  163. from tools.environments.local import build_subprocess_env
  164. proc = await asyncio.create_subprocess_shell(
  165. exec_cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
  166. env=build_subprocess_env(), cwd=cwd,
  167. # Its own process group, so cleanup can reach what the shell started (POSIX;
  168. # Windows ignores it and _stop_exec_tree walks the tree with taskkill /T).
  169. start_new_session=True, # detached-spawn: ok — awaited; the timeout/cancel path kills its group
  170. )
  171. stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=_EXEC_QUICK_COMMAND_TIMEOUT)
  172. output = (stdout or stderr).decode().strip()
  173. if output:
  174. from agent.redact import redact_sensitive_text
  175. output = redact_sensitive_text(output)
  176. return output or t("gateway.quick_command.no_output")
  177. except (TimeoutError, asyncio.CancelledError) as stopped:
  178. # One cleanup for both: a cancelled await must not leave the command running either.
  179. if proc is not None:
  180. await asyncio.shield(_stop_exec_tree(proc))
  181. if isinstance(stopped, asyncio.CancelledError):
  182. raise
  183. return t("gateway.quick_command.timed_out")
  184. except Exception as e: # health: allow BLE001 -- moved unchanged from run_inbound.py (main has the same handler): an operator quick command's failure is its reply
  185. return t("gateway.quick_command.error", error=e)
  186. async def _hm_dispatch_quick_and_plugin_commands(
  187. self, event: MessageEvent, source: SessionSource, command: Optional[str]
  188. ) -> tuple[bool, Optional[str], Optional[str]]:
  189. """Drain gate, user-defined quick commands (exec/alias) and plugin slash commands →
  190. ``(handled, result, command)``; an alias quick command rewrites ``command``."""
  191. if self._draining and getattr(event, "_admitted_before_drain", False) is not True:
  192. return True, t("gateway.busy.drain_rejected_new_work", action=self._status_action_gerund()), command
  193. # User-defined quick commands (bypass agent loop, no LLM call)
  194. qcmd = self._hm_quick_commands().get(command) if command else None
  195. if qcmd is not None:
  196. # Quick commands are slash capabilities too — and type:exec ones run a shell command in
  197. # the gateway process. They are never in the registry, so the early gate never fires for
  198. # them; apply the same admin/user policy to the raw typed name here.
  199. # The early gate above only fires for registry-known commands, so quick commands (never in the
  200. # registry) would otherwise reach this dispatch sink unchecked. (#44727)
  201. _denied = self._check_slash_access(source, command)
  202. if _denied is not None:
  203. return True, _denied, command
  204. qtype = qcmd.get("type")
  205. if qtype == "exec":
  206. exec_cmd = qcmd.get("command", "")
  207. if not exec_cmd:
  208. return True, t("gateway.quick_command.no_command", command=command), command
  209. return True, await self._hm_run_exec_quick_command(command, exec_cmd), command
  210. if qtype != "alias":
  211. return True, t("gateway.quick_command.unsupported_type", command=command), command
  212. new_command = self._hm_expand_alias_quick_command(event, qcmd)
  213. if new_command is None:
  214. return True, t("gateway.quick_command.no_target", command=command), command
  215. command = new_command # Fall through to normal command dispatch below
  216. if not command:
  217. return False, None, command
  218. return await self._hm_dispatch_plugin_command(event, source, command)
  219. async def _hm_dispatch_plugin_command(
  220. self, event: MessageEvent, source: SessionSource, command: str
  221. ) -> tuple[bool, Optional[str], Optional[str]]:
  222. """Plugin-registered slash command *command* → ``(handled, result, command)``. No quick
  223. commands: a local session resolves those in its own profile before calling this."""
  224. # Underscores normalize to hyphens so Telegram's underscored autocomplete form matches
  225. # plugin commands registered with hyphens.
  226. if command:
  227. try:
  228. from hermes_cli.plugins import get_plugin_command_handler
  229. plugin_handler = get_plugin_command_handler(command.replace("_", "-"))
  230. if plugin_handler:
  231. return True, await self._hm_run_plugin_handler(plugin_handler, event, source), command
  232. except Exception as e:
  233. logger.warning("Plugin command dispatch failed: %s", e, exc_info=True)
  234. return False, None, command
  235. async def _hm_run_plugin_handler(
  236. self, plugin_handler, event: MessageEvent, source: SessionSource, session_entry=None, args=None
  237. ) -> Optional[str]:
  238. """Run a resolved plugin command handler for *source* → its reply text or None; raises what
  239. the handler raises (``gateway/session_commands.py`` resolves the exact registered name).
  240. *args* is the argument as typed (a local session's command); otherwise the message's
  241. command arguments, with the messaging dash repair of ``get_command_args``."""
  242. # The agent-turn path binds HERMES_SESSION_* via _set_session_env; this dispatch
  243. # sits before it, so a handler reading get_session_env() would see an empty or a
  244. # foreign (cron agent's os.environ) session (#108698). A local session's command
  245. # passes its live *session_entry* (key and id, as its turns bind them); a messaging
  246. # message has none yet, so session_key is derived from source. Sync handlers run on the
  247. # gateway pool (contextvars carried), never the loop thread: blocking I/O there starves
  248. # the liveness watchdog and the process exits 75 mid-handler (#105279).
  249. if session_entry is None and getattr(self, "session_store", None) is not None:
  250. # The chat's current session, if it has one (lookup only: a command never creates one), so
  251. # HERMES_SESSION_ID / session_id name what a later /new reports as old_session_id (#123245).
  252. session_entry = await self.async_session_store.lookup_by_session_key(
  253. self._session_key_for_source(source))
  254. _plugin_context = build_session_context(source, self.config, session_entry)
  255. if session_entry is None:
  256. _plugin_context.session_key = self._session_key_for_source(source)
  257. user_args = event.get_command_args().strip() if args is None else args
  258. from hermes_cli.plugin_command_dispatch import invoke_plugin_command
  259. from gateway.plugin_messages import bind_live_source
  260. from gateway.plugin_command_choice import chat_choices
  261. call = functools.partial(
  262. invoke_plugin_command, plugin_handler, user_args, source=source,
  263. session_id=_plugin_context.session_id or "", session_key=_plugin_context.session_key or "",
  264. platform=source.platform.value)
  265. # ctx.post_message from the handler reaches this chat even before its session is stored;
  266. # ctx.ask_choice asks it with the clarify prompt.
  267. with (self._session_env_scope(_plugin_context), bind_live_source(source),
  268. chat_choices(self, source, self._session_key_for_source(source))):
  269. if inspect.iscoroutinefunction(plugin_handler):
  270. result = await call()
  271. else:
  272. result = await self._run_in_executor_with_context(call)
  273. if inspect.isawaitable(result):
  274. result = await result
  275. return str(result) if result else None