hermes-agent/gateway/run_inbound_hooks.py

"""Plugin and user extension points on the inbound pipeline (moved out of ``gateway/run_inbound.py``).

``pre_gateway_dispatch`` (before auth), ``post_gateway_admission`` (once per admitted inbound
message, #129958), ``pre_command`` / ``command:<name>`` hooks, user ``quick_commands`` and
plugin-registered slash commands. Bound onto ``GatewayRunner`` through ``GatewayInboundMixin``.
"""

from __future__ import annotations

import asyncio
import contextlib
import dataclasses
import functools
import inspect
import logging
import os
import signal
import sys
from typing import Optional, Tuple

from agent.i18n import t
from gateway.platforms.event import MessageEvent
from gateway.session import SessionSource, build_session_context

# Log-record parity with the origin module.
logger = logging.getLogger("gateway.run")

# Seconds a ``type: exec`` quick command may run before its whole process tree is killed.
_EXEC_QUICK_COMMAND_TIMEOUT = 30


async def _stop_exec_tree(proc) -> None:
    """Kill an exec quick command's shell and everything it started, then reap the shell (bounded).

    Killing only the shell leaves ``sleep 120 & wait``'s sleep running. ``kill_process_tree`` reaches
    descendants (``taskkill /T`` on Windows); on POSIX the group the shell led also catches members
    that already outlived it."""
    if proc.returncode is None:
        from agent.deadline import kill_process_tree
        await asyncio.to_thread(kill_process_tree, proc.pid)
    if sys.platform != "win32":
        with contextlib.suppress(ProcessLookupError, PermissionError):
            os.killpg(proc.pid, signal.SIGKILL)  # windows-footgun: ok — POSIX-only branch; start_new_session made pid the pgid
    with contextlib.suppress(TimeoutError):
        await asyncio.wait_for(proc.wait(), timeout=5)


class GatewayInboundHooksMixin:
    """Hook, quick-command and plugin-command dispatch for ``GatewayInboundMixin``."""

    async def _hm_post_admission_consume(
        self, event: MessageEvent, source: SessionSource, session_key: str
    ) -> tuple[bool, Optional[str]]:
        """``post_gateway_admission`` exactly once per inbound message: ``(consumed, reply)``.

        Never while an admitted row EXECUTES (first run or restart replay): the authority path
        already offered the message at ingress, before its commit, so a consumed message is never
        admitted and an admitted one is never offered twice."""
        from gateway.session_ingress import executing_admission
        if executing_admission.get():
            return False, None
        from gateway.run_inbound_consumer import run_post_admission_hook
        return await run_post_admission_hook(self, event, source, session_key)

    async def _hm_pre_gateway_dispatch_hook(
        self, event: MessageEvent, source: SessionSource
    ) -> Optional[MessageEvent]:
        """Run the ``pre_gateway_dispatch`` plugin hook; None = drop, else the (maybe rewritten) event.
        Results: ``{"action": "skip"}`` → drop; ``{"action": "rewrite", "text"}`` → replace ``event.text``;
        ``allow``/None → normal dispatch. On the messaging path it runs BEFORE auth so plugins can handle
        unauthorized senders; on the producer path (webhook/relay, ``admit_producer``) it runs AFTER the
        delivery's authorization, which preparing its payload performs, so it never sees a refused sender.

        Once per inbound message, at ingress (here, or ``admit_producer`` for webhook/relay), never
        while an admitted row EXECUTES: a messaging turn already passed it before its commit, and a
        local CLI/TUI/Desktop turn never fired it on main, so a skip must not drop committed input."""
        from gateway.session_ingress import executing_admission
        if executing_admission.get():
            return event
        try:
            from hermes_cli.lifecycle import ainvoke_hook as _ainvoke_hook
            _hook_results = await _ainvoke_hook(
                "pre_gateway_dispatch", event=event, gateway=self,
                # getattr: bare-runner tests build GatewayRunner via object.__new__ without __init__.
                session_store=getattr(self, "session_store", None),
            )
        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
            logger.warning("pre_gateway_dispatch invocation failed: %s", _hook_exc)
            _hook_results = []

        for _result in _hook_results:
            if not isinstance(_result, dict):
                continue
            _action = _result.get("action")
            if _action == "skip":
                logger.info(
                    "pre_gateway_dispatch skip: reason=%s platform=%s chat=%s",
                    _result.get("reason"), source.platform.value if source.platform else "unknown",
                    source.chat_id or "unknown",
                )
                return None
            if _action == "rewrite":
                _new_text = _result.get("text")
                if isinstance(_new_text, str):
                    from gateway.session_ingress_context import carry_callback
                    rewritten = dataclasses.replace(event, text=_new_text)
                    carry_callback(event, rewritten)
                    event = rewritten
                break
            if _action == "allow":
                break
        return event

    def _hm_quick_commands(self) -> dict:
        """User-defined ``quick_commands`` mapping from config (empty dict when unset/malformed)."""
        cfg = self.config
        qc = (cfg.get("quick_commands") if isinstance(cfg, dict) else getattr(cfg, "quick_commands", None)) or {}
        return qc if isinstance(qc, dict) else {}

    @staticmethod
    def _hm_expand_alias_quick_command(event: MessageEvent, qcmd: dict) -> Optional[str]:
        """Rewrite ``event.text`` to an alias quick command's target; returns the new command name."""
        target = (qcmd.get("target") or "").strip()
        if not target:
            return None
        target = target if target.startswith("/") else f"/{target}"
        event.text = f"{target} {event.get_command_args().strip()}".strip()
        target_command = target.lstrip("/")
        return target_command.split()[0] if target_command else target_command

    async def _hm_command_hooks(
        self, event: MessageEvent, source: SessionSource, _quick_key: str, command: str, canonical: str
    ) -> tuple[bool, Optional[str], Optional[str]]:
        """Fire ``pre_command`` (observer) and ``command:<canonical>`` (interceptor) hooks →
        ``(handled, result, new_command)`` (``new_command`` set when a handler rewrote the command).
        The running-agent path deliberately does NOT fire these — a slow or hostile plugin must not
        interfere with the operator's escape hatches for a live agent."""
        raw_args = event.get_command_args().strip()
        platform = source.platform.value if source.platform else ""
        try:
            from hermes_cli.plugins import fire_pre_command_hook
            fire_pre_command_hook(
                surface="gateway", command=str(canonical), alias_used=str(command),
                args_raw=raw_args, session_key=_quick_key, platform=platform,
            )
        except Exception as _pre_cmd_err:
            logger.debug("pre_command hook dispatch failed (non-fatal): %s", _pre_cmd_err, exc_info=True)

        # Handlers may return ``{"decision": "deny" | "handled" | "rewrite", ...}`` to intercept
        # dispatch; handlers returning nothing behave as plain observers.
        hook_ctx = {
            "platform": platform, "user_id": source.user_id, "command": canonical,
            "raw_command": command, "args": raw_args, "raw_args": raw_args,
        }
        try:
            hook_results = await self.hooks.emit_collect(f"command:{canonical}", hook_ctx)
        except Exception as _hook_err:
            logger.debug("command:%s hook dispatch failed (non-fatal): %s", canonical, _hook_err, exc_info=True)
            hook_results = []

        for hook_result in hook_results:
            if not isinstance(hook_result, dict):
                continue
            decision = str(hook_result.get("decision", "")).strip().lower()
            message = hook_result.get("message")
            message = message if isinstance(message, str) and message else None
            if decision == "deny":
                return True, message or t("gateway.hooks.command_blocked", command=command), None
            if decision == "handled":
                return True, message, None
            if decision == "rewrite":
                new_command = str(hook_result.get("command_name", "")).strip().lstrip("/")
                if new_command:
                    event.text = f"/{new_command} {str(hook_result.get('raw_args', '')).strip()}".strip()
                    return False, None, event.get_command()
        return False, None, None

    async def _hm_run_exec_quick_command(self, command: str, exec_cmd: str, cwd: Optional[str] = None) -> str:
        """Run a ``type: exec`` quick command as a host shell of the gateway process: sanitized env
        (the gateway process has every API key in os.environ), redacted output, its process tree
        killed after 30 s or when the awaiting task is cancelled (gateway shutdown).
        ``cwd`` is a local session's folder; None keeps the gateway's own (messaging)."""
        proc = None
        try:
            from tools.environments.local import build_subprocess_env
            proc = await asyncio.create_subprocess_shell(
                exec_cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
                env=build_subprocess_env(), cwd=cwd,
                # Its own process group, so cleanup can reach what the shell started (POSIX;
                # Windows ignores it and _stop_exec_tree walks the tree with taskkill /T).
                start_new_session=True,  # detached-spawn: ok — awaited; the timeout/cancel path kills its group
            )
            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=_EXEC_QUICK_COMMAND_TIMEOUT)
            output = (stdout or stderr).decode().strip()
            if output:
                from agent.redact import redact_sensitive_text
                output = redact_sensitive_text(output)
            return output or t("gateway.quick_command.no_output")
        except (TimeoutError, asyncio.CancelledError) as stopped:
            # One cleanup for both: a cancelled await must not leave the command running either.
            if proc is not None:
                await asyncio.shield(_stop_exec_tree(proc))
            if isinstance(stopped, asyncio.CancelledError):
                raise
            return t("gateway.quick_command.timed_out")
        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
            return t("gateway.quick_command.error", error=e)

    async def _hm_dispatch_quick_and_plugin_commands(
        self, event: MessageEvent, source: SessionSource, command: Optional[str]
    ) -> tuple[bool, Optional[str], Optional[str]]:
        """Drain gate, user-defined quick commands (exec/alias) and plugin slash commands →
        ``(handled, result, command)``; an alias quick command rewrites ``command``."""
        if self._draining and getattr(event, "_admitted_before_drain", False) is not True:
            return True, t("gateway.busy.drain_rejected_new_work", action=self._status_action_gerund()), command

        # User-defined quick commands (bypass agent loop, no LLM call)
        qcmd = self._hm_quick_commands().get(command) if command else None
        if qcmd is not None:
            # Quick commands are slash capabilities too — and type:exec ones run a shell command in
            # the gateway process. They are never in the registry, so the early gate never fires for
            # them; apply the same admin/user policy to the raw typed name here.
            # The early gate above only fires for registry-known commands, so quick commands (never in the
            # registry) would otherwise reach this dispatch sink unchecked. (#44727)
            _denied = self._check_slash_access(source, command)
            if _denied is not None:
                return True, _denied, command
            qtype = qcmd.get("type")
            if qtype == "exec":
                exec_cmd = qcmd.get("command", "")
                if not exec_cmd:
                    return True, t("gateway.quick_command.no_command", command=command), command
                return True, await self._hm_run_exec_quick_command(command, exec_cmd), command
            if qtype != "alias":
                return True, t("gateway.quick_command.unsupported_type", command=command), command
            new_command = self._hm_expand_alias_quick_command(event, qcmd)
            if new_command is None:
                return True, t("gateway.quick_command.no_target", command=command), command
            command = new_command  # Fall through to normal command dispatch below

        if not command:
            return False, None, command
        return await self._hm_dispatch_plugin_command(event, source, command)

    async def _hm_dispatch_plugin_command(
        self, event: MessageEvent, source: SessionSource, command: str
    ) -> tuple[bool, Optional[str], Optional[str]]:
        """Plugin-registered slash command *command* → ``(handled, result, command)``. No quick
        commands: a local session resolves those in its own profile before calling this."""
        # Underscores normalize to hyphens so Telegram's underscored autocomplete form matches
        # plugin commands registered with hyphens.
        if command:
            try:
                from hermes_cli.plugins import get_plugin_command_handler
                plugin_handler = get_plugin_command_handler(command.replace("_", "-"))
                if plugin_handler:
                    return True, await self._hm_run_plugin_handler(plugin_handler, event, source), command
            except Exception as e:
                logger.warning("Plugin command dispatch failed: %s", e, exc_info=True)
        return False, None, command

    async def _hm_run_plugin_handler(
        self, plugin_handler, event: MessageEvent, source: SessionSource, session_entry=None, args=None
    ) -> Optional[str]:
        """Run a resolved plugin command handler for *source* → its reply text or None; raises what
        the handler raises (``gateway/session_commands.py`` resolves the exact registered name).
        *args* is the argument as typed (a local session's command); otherwise the message's
        command arguments, with the messaging dash repair of ``get_command_args``."""
        # The agent-turn path binds HERMES_SESSION_* via _set_session_env; this dispatch
        # sits before it, so a handler reading get_session_env() would see an empty or a
        # foreign (cron agent's os.environ) session (#108698). A local session's command
        # passes its live *session_entry* (key and id, as its turns bind them); a messaging
        # message has none yet, so session_key is derived from source. Sync handlers run on the
        # gateway pool (contextvars carried), never the loop thread: blocking I/O there starves
        # the liveness watchdog and the process exits 75 mid-handler (#105279).
        if session_entry is None and getattr(self, "session_store", None) is not None:
            # The chat's current session, if it has one (lookup only: a command never creates one), so
            # HERMES_SESSION_ID / session_id name what a later /new reports as old_session_id (#123245).
            session_entry = await self.async_session_store.lookup_by_session_key(
                self._session_key_for_source(source))
        _plugin_context = build_session_context(source, self.config, session_entry)
        if session_entry is None:
            _plugin_context.session_key = self._session_key_for_source(source)
        user_args = event.get_command_args().strip() if args is None else args
        from hermes_cli.plugin_command_dispatch import invoke_plugin_command
        from gateway.plugin_messages import bind_live_source
        from gateway.plugin_command_choice import chat_choices
        call = functools.partial(
            invoke_plugin_command, plugin_handler, user_args, source=source,
            session_id=_plugin_context.session_id or "", session_key=_plugin_context.session_key or "",
            platform=source.platform.value)
        # ctx.post_message from the handler reaches this chat even before its session is stored;
        # ctx.ask_choice asks it with the clarify prompt.
        with (self._session_env_scope(_plugin_context), bind_live_source(source),
              chat_choices(self, source, self._session_key_for_source(source))):
            if inspect.iscoroutinefunction(plugin_handler):
                result = await call()
            else:
                result = await self._run_in_executor_with_context(call)
                if inspect.isawaitable(result):
                    result = await result
        return str(result) if result else None