The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Inbound message pipeline (_handle_message, text/media preparation, durable-turn markers, plugin injection) for GatewayRunner.
Split out of ``gateway/run.py``; bound onto ``GatewayRunner`` via the MRO.
``gateway.run`` internals are imported lazily inside method bodies (import cycle),
so ``patch("gateway.run.X")`` keeps intercepting them at call time.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
import asyncio
import concurrent.futures
import dataclasses
import json
import os
import re
import time
from contextlib import suppress
from pathlib import Path
from agent.i18n import t
from gateway.config import Platform
from gateway.platforms.base import EphemeralReply
from gateway.platforms.event import MessageEvent, MessageType, clean_attachment_filename
from gateway.run_busy import approval_input_words
from gateway.run_inbound_media import rehome_inbound_media
from gateway.run_inbound_hooks import GatewayInboundHooksMixin
from gateway.run_inbound_transcription import GatewayInboundTranscriptionMixin
from gateway.run_plugin_injection import GatewayPluginInjectionMixin
from gateway.run_inbound_unauthorized import (
UnauthorizedOwnerNotifier, pairing_code_reply, pairing_profile_arg, pairing_rate_limited_reply,
unauthorized_owner_hint,
)
from gateway.session import (
SessionSource, build_session_context, is_shared_multi_user_session,
neutralize_untrusted_inline_text,
)
from gateway.turn_lease import TurnLeaseTimeoutError
from hermes_cli.observability.shared_metrics_busy import (
note_busy_admitting, note_busy_outcome, settle_busy_arrival, stamp_busy_arrival)
from typing import Any, Dict, List, Optional, Tuple
if TYPE_CHECKING: # string annotations only; never imported at runtime (cycle)
from gateway.run import GatewayRunner
from gateway.run_turn_runner import TurnRunner
# Log-record parity with the origin module.
logger = logging.getLogger("gateway.run")
# ``RelayMediaClient.download`` temp-file prefix: the rest of such a basename is random, not a name.
_RELAY_MEDIA_PREFIX = "relay_media_"
_UNKNOWN_ATTACHMENT_NAME = "(original filename unknown)"
def discord_triggering_note(message_id: Any) -> str:
"""Model-facing routing note for a Discord turn (rides the API-bound user message only)."""
return (
f"[Triggering message id: `{message_id}` — use as `message_id` for reply/react/pin "
f"via the discord tools.]"
)
def strip_discord_triggering_note(event: Any, message_text: Any) -> Any:
"""Authored text for the durable user row: peel off exactly the note
``_prepend_inbound_reply_context`` added for THIS event, if present. The note is a
model instruction, not something the user wrote — persisted as ``content`` it renders
verbatim in every transcript surface and pollutes FTS/memory (#71304, #114719). It
keeps riding ``message_text`` (and the replay-only ``api_content`` sidecar)."""
message_id = getattr(event, "message_id", None)
if not message_id or not isinstance(message_text, str):
return message_text
prefix = f"{discord_triggering_note(message_id)}\n\n"
return message_text.removeprefix(prefix)
class GatewayInboundMixin(GatewayInboundHooksMixin, GatewayInboundTranscriptionMixin, GatewayPluginInjectionMixin):
"""Inbound message pipeline (_handle_message, text/media preparation, durable-turn markers, plugin injection) for GatewayRunner."""
async def _hm_offer_pairing_code(self, source: SessionSource) -> None:
"""DM an unauthorized sender a pairing code (rate-limited; groups never reach here)."""
platform_name = source.platform.value if source.platform else "unknown"
pairing_store = self._pairing_store_for(source)
if pairing_store is None:
logger.error("Cannot offer pairing code on %s: no pairing store", platform_name)
return
# Rate-limit ALL pairing responses (code or rejection) so a burst of DMs doesn't spam.
if pairing_store._is_rate_limited(platform_name, source.user_id):
return
# Off the event loop: the store edit waits on a cross-process lock (dashboard, CLI).
try:
code = await asyncio.to_thread(
pairing_store.generate_code, platform_name, source.user_id, source.user_name or "",
)
except (OSError, TimeoutError):
logger.warning("Could not record a pairing code on %s", platform_name, exc_info=True)
return
adapter = self._delivery_adapter_for(source)
if code:
reply = pairing_code_reply(platform_name, code, pairing_profile_arg(pairing_store))
else:
reply = pairing_rate_limited_reply()
if adapter:
await adapter.send(source.chat_id, reply)
if not code:
# Record rate limit so subsequent messages are silently ignored
pairing_store._record_rate_limit(platform_name, source.user_id)
async def _hm_send_unauthorized_decline(self, source: SessionSource) -> None:
"""``decline`` behavior: one short refusal per sender per DECLINE_DEDUPE_SECONDS, then silence
(#88028). The stamp is written BEFORE the send so a delivery
hiccup cannot become a decline storm; without a store there is no dedupe state → stay silent."""
from gateway.config import DEFAULT_UNAUTHORIZED_DM_DECLINE_MESSAGE
platform_name = source.platform.value if source.platform else "unknown"
pairing_store = self._pairing_store_for(source)
if pairing_store is None or pairing_store.has_recent_decline(platform_name, source.user_id):
return
# Off the event loop (the stamp waits on a cross-process lock); no stamp → no dedupe → silent.
try:
await asyncio.to_thread(pairing_store.record_decline, platform_name, source.user_id)
except (OSError, TimeoutError):
logger.warning("Could not record an unauthorized-DM decline on %s", platform_name, exc_info=True)
return
adapter = self._delivery_adapter_for(source)
if not adapter:
return
config = getattr(self, "config", None)
text = str(getattr(config, "unauthorized_dm_decline_message", "") or "").strip()
try:
await adapter.send(source.chat_id, text or DEFAULT_UNAUTHORIZED_DM_DECLINE_MESSAGE)
except Exception:
logger.warning("Failed to deliver unauthorized-DM decline on %s", platform_name, exc_info=True)
async def _hm_report_ignored_dm(self, source: SessionSource) -> None:
"""Unauthorized DM under behaviour ``ignore``: nothing goes to the sender. The owner gets the
sender's ID and the allowlist fix in the WARNING log and, once per sender, in the home channel."""
from hermes_constants import display_hermes_home
platform_name = source.platform.value if source.platform else "unknown"
hint = unauthorized_owner_hint(
platform_name, source.user_id, source.user_name or "", hermes_home=display_hermes_home(),
)
logger.warning("Unauthorized user (ignored): %s", hint)
notifier = getattr(self, "_unauthorized_owner_notifier", None)
if notifier is None:
notifier = self._unauthorized_owner_notifier = UnauthorizedOwnerNotifier()
if notifier.first_time(platform_name, source.user_id) and getattr(self, "config", None) is not None:
await notifier.notify(self, source, hint)
async def _hm_admit_event(
self, event: MessageEvent
) -> Optional[tuple[MessageEvent, SessionSource, bool]]:
"""Ingress gates for ``_handle_message``; None when dropped, else ``(event, source, is_internal)``
(the ``pre_gateway_dispatch`` hook may have rewritten ``event``)."""
from gateway.run import _is_slack_ignored_channel
source = event.source
# getattr(self, ...) throughout: bare test runners build GatewayRunner via object.__new__.
_config = getattr(self, "config", None)
# 🔴 Cross-session leak guard: this per-message task was create_task()'d with a copy of the
# spawning context, which may carry ANOTHER message's HERMES_SESSION_* ContextVars; until
# _set_session_env binds ours a subprocess would read the foreign identity. Reset to _UNSET.
try:
from gateway.session_context import reset_session_vars
reset_session_vars()
except Exception:
logger.debug("reset_session_vars failed at handler entry", exc_info=True)
# Identity FIRST. Most adapters canonicalize at their own ingress; internal/voice paths
# construct SessionSource directly, so this is the shared fail-closed gate. Strict boolean
# marker: require the literal True so duck-typed test/internal sources with dynamic
# attributes are not mistaken for a rejection.
if getattr(_config, "multiplex_profiles", False):
self._canonicalize(source)
if getattr(source, "profile_route_rejected", False) is True:
from gateway.parked_route_refusal import drop_rejected_route
_intake = None
with suppress(Exception):
_intake = self._intake_adapter_for(source)
drop_rejected_route(_intake, source) # a parked target is also refused to the sender
return None
is_internal = bool(getattr(event, "internal", False)) # e.g. background-process notifications
# Ignored-channel guard runs FIRST — before startup-restore queueing, plugin hooks, auth,
# and session setup — so an ignored channel can never reach pairing/auth/session state.
_chat_id = getattr(source, "chat_id", None)
if not is_internal and getattr(source, "platform", None) == Platform.SLACK:
# The routed adapter's extra carries a secondary profile's own list; ``_config`` is the default's.
_slack_adapter = None
with suppress(Exception):
_slack_adapter = self._intake_adapter_for(source)
if (
# See #51899.
not is_internal
and getattr(source, "platform", None) == Platform.SLACK
and _is_slack_ignored_channel(_config, _chat_id, _slack_adapter)
):
logger.info("Dropping Slack message from configured ignored channel %s", _chat_id)
return None
# An admission the authority is executing is already ordered by its durable FIFO; parking it
# here would settle the row with no turn and replay the input outside it (GW-2).
from gateway.session_ingress import executing_admission
if (
getattr(self, "_startup_restore_in_progress", False)
and not is_internal
and not getattr(event, "_hermes_startup_restore_replay", False)
and not executing_admission.get()
):
self._queue_startup_restore_event(event)
return None
if is_internal:
return event, source, True
if getattr(event, "_fifo_only", False): # a slash command's queued turn: its command passed ingress
return event, source, False
# scale-to-zero: only real user-originated inbound stamps the last-inbound clock;
# counting internal/system events would keep a genuinely idle gateway awake.
self._scale_to_zero_note_real_inbound()
event = await self._hm_pre_gateway_dispatch_hook(event, source)
if event is None:
return None
source = event.source
if not self._is_user_authorized_for_source(source):
if source.user_id is None:
# No user identity (Telegram service messages, channel forwards, anonymous admin
# posts, sender_chat): can't be paired but may be authorized via a chat allowlist.
logger.debug("Ignoring message with no user_id from %s", source.platform.value)
return None
# DMs get a pairing code or a one-time decline, groups are ignored. A bot cannot pair, and
# answering one mid-cooldown is outbound traffic.
pairable_dm = source.chat_type == "dm" and not getattr(source, "is_bot", False)
behavior = self._get_unauthorized_dm_behavior(source.platform, profile=source.profile) if pairable_dm else None
if behavior == "pair":
logger.warning("Unauthorized user: %s (%s) on %s", source.user_id, source.user_name, source.platform.value)
await self._hm_offer_pairing_code(source)
elif behavior == "decline":
logger.warning("Unauthorized user: %s (%s) on %s", source.user_id, source.user_name, source.platform.value)
await self._hm_send_unauthorized_decline(source)
elif pairable_dm:
await self._hm_report_ignored_dm(source)
else:
logger.warning("Unauthorized user: %s (%s) on %s", source.user_id, source.user_name, source.platform.value)
return None
# The busy path charged this event on arrival; a drained follow-up must not pay twice.
if not getattr(event, "_bot_loop_admitted", False) and not self._admit_bot_message_for_source(source):
return None
return event, source, False
def _hm_estop_turn_allowed(self, event: MessageEvent, source: SessionSource) -> bool:
"""Whether a turn may bypass the global emergency stop: pause blocks NEW agent turns, never
running work or control traffic — recognized slash commands (incl. /pause off, the in-band
resume) and replies owned by in-flight work (pending update prompt, running session,
pending slash-confirm, dangerous-command approval) all pass through."""
with suppress(Exception):
_estop_cmd = event.get_command()
if _estop_cmd:
from hermes_cli.commands import resolve_command as _resolve_estop_cmd
if _resolve_estop_cmd(_estop_cmd) is not None:
return True
with suppress(Exception):
_estop_key = self._session_key_for_source(source)
_estop_state = self._peek_session_state(_estop_key)
if _estop_state is not None and _estop_state.persistent.update_prompt_pending:
return True
# A running session covers steering plus pending clarify / tool approvals it holds.
if self._is_session_running(_estop_key):
return True
from tools import slash_confirm as _estop_confirm_mod
if _estop_confirm_mod.get_pending(_estop_key):
return True
from tools.approval import has_blocking_approval as _estop_has_approval
if _estop_has_approval(_estop_key):
return True
return False
def _hm_estop_gate(
self, event: MessageEvent, source: SessionSource, is_internal: bool
) -> Optional[str]:
"""Global emergency-stop (`hermes pause`) notice when this turn must be blocked, else None.
Placed after auth so unauthorized senders can't probe pause state. A synthetic heartbeat that
slipped past the poller's pause check gets "" (blocked, nothing sent): nobody typed it, and
settle_heartbeat_attempt leaves its tick due for after resume."""
if is_internal:
return None
try:
from agent.estop import paused_reply as _estop_paused_reply
except ImportError:
return None
_paused_notice = _estop_paused_reply()
if _paused_notice is None or self._hm_estop_turn_allowed(event, source):
return None
if getattr(event, "_heartbeat_session_id", None):
logger.debug("Heartbeat turn dropped by global emergency stop")
return ""
logger.info(
"Gateway turn paused by global emergency stop (platform=%s chat=%s)",
getattr(getattr(source, "platform", None), "value", "unknown"),
getattr(source, "chat_id", None) or "unknown",
)
return _paused_notice
@staticmethod
def _hm_write_update_response(response_text: str) -> Optional[str]:
"""Atomically hand *response_text* to the detached update process; returns the OSError str."""
from gateway.run import _hermes_home
response_path = _hermes_home / ".update_response"
try:
tmp = response_path.with_suffix(".tmp")
tmp.write_text(response_text, encoding="utf-8")
tmp.replace(response_path)
(_hermes_home / ".update_prompt.json").unlink(missing_ok=True)
except OSError as e:
return str(e)
return None
def _hm_update_prompt_reply(self, event: MessageEvent, _quick_key: str) -> Optional[str]:
"""Consume a reply to a pending ``/update`` prompt (routed to the detached update process via
``.update_response``); None when nothing was consumed. Recognized slash commands must bypass
this or /new, /help etc. get silently consumed as update answers."""
_up_state = self._peek_session_state(_quick_key)
if _up_state is None or not _up_state.persistent.update_prompt_pending:
return None
# Accept /approve and /deny as shorthand for yes/no
cmd = event.get_command()
_recognized_cmd = None
if cmd in {"approve", "yes"}:
response_text = "y"
elif cmd in {"deny", "no"}:
response_text = "n"
else:
if cmd:
with suppress(Exception):
from hermes_cli.commands import resolve_command as _resolve_update_cmd
_cmd_def = _resolve_update_cmd(cmd)
_recognized_cmd = _cmd_def.name if _cmd_def else None
response_text = "" if _recognized_cmd else (event.text or "").strip()
if response_text:
err = self._hm_write_update_response(response_text)
if err is not None:
logger.warning("Failed to write update response: %s", err)
return t("gateway.update.reply_failed", error=err)
_up_state.persistent.update_prompt_pending = False
label = response_text if len(response_text) <= 20 else response_text[:20] + "…"
return t("gateway.update.reply_sent", label=label)
# Recognized slash command during a pending update prompt: write a blank response so the
# detached update's ``_gateway_prompt`` returns the prompt's default (typically a safe
# "n" / skip) and exits instead of blocking on stdin until the watcher timeout.
if _recognized_cmd:
err = self._hm_write_update_response("")
if err is None:
logger.info(
"Recognized /%s during pending update prompt for %s; "
"cancelled prompt with default and dispatching command",
_recognized_cmd, _quick_key,
)
else:
logger.warning("Failed to write cancel response for pending update prompt: %s", err)
_up_state.persistent.update_prompt_pending = False
return None
async def _hm_clarify_reply(
self, event: MessageEvent, source: SessionSource, _quick_key: str
) -> Optional[str]:
"""Intercept a reply to a pending clarify prompt; None when the message falls through.
Free text answers open-ended/"Other" prompts; "2" answers a multi-choice one. Resolved/retained
replies return "" so adapters don't double-post — the agent produces the next user-facing message."""
try:
from tools import clarify_gateway as _clarify_mod
_pending_clarify = _clarify_mod.get_pending_for_session(_quick_key, include_choice_prompts=True)
except Exception:
return None
if _pending_clarify is None:
return None
_clarify_has_audio = bool(self._pending_event_audio_paths(event))
_raw_clarify_reply = await self._prepare_clarify_reply_text(event)
def _retain(why: str) -> str:
logger.info(
"Gateway retained pending clarify after %s (session=%s, id=%s)",
why, _quick_key, _pending_clarify.clarify_id,
)
return ""
if _clarify_has_audio and not _raw_clarify_reply:
return _retain("voice transcription produced no usable text")
# Slash commands: the user wanted a command, not to answer the clarify. Leave it pending so
# they can retry; on timeout the agent unblocks with an empty response.
if not _raw_clarify_reply or _raw_clarify_reply.startswith("/"):
return None
_text_outcome = _clarify_mod.attempt_text_response_for_session(_quick_key, _raw_clarify_reply)
if _text_outcome == _clarify_mod.TEXT_RESOLVED:
logger.info(
"Gateway intercepted clarify text response (session=%s, id=%s)",
_quick_key, _pending_clarify.clarify_id,
)
# The clarify callback pauses the platform typing/status indicator while waiting so
# Slack users can type; the active agent resumes now, so re-enable its indicator.
_clarify_adapter = self._delivery_adapter_for(source)
if _clarify_adapter:
try:
_clarify_adapter.resume_typing_for_chat(source.chat_id)
except Exception:
logger.debug("Failed to resume typing after clarify response", exc_info=True)
# A typed answer to a native card (numeric pick, or text after "Other") never
# reaches the click handler, so the card would keep its buttons forever.
if callable(getattr(type(_clarify_adapter), "retire_clarify_card", None)):
try:
await _clarify_adapter.retire_clarify_card(
_pending_clarify.clarify_id,
t("gateway.clarify.answered",
response=_raw_clarify_reply if _pending_clarify.response == _clarify_mod.SKIPPED
else _pending_clarify.response or _raw_clarify_reply))
except Exception:
logger.debug("Failed to retire clarify card after typed answer", exc_info=True)
return ""
if _text_outcome == _clarify_mod.TEXT_REJECTED_SELECTION:
# Selection-shaped but invalid (out-of-range number, bad comma-list): keep the clarify
# armed for retry — don't cancel, don't treat as an unrelated follow-up.
return _retain("invalid selection attempt")
if _text_outcome == _clarify_mod.TEXT_REJECTED_PROSE:
# Native-choice prompts reject unmatched prose so it continues through normal busy
# routing. Release this clarify first: redirect() degrades to steer() while tools
# execute, and that steer cannot drain until the clarify tool returns.
if _clarify_mod.resolve_gateway_clarify(_pending_clarify.clarify_id, _clarify_mod.CANCELLED):
# Adapters with a persistent native card (Slack Block Kit) retire it now, before the
# prose is routed, so its buttons stop advertising a dead answer path. The pop inside
# retire_clarify_card runs before its first await, so the agent thread's own expiry
# notice (scheduled once the wait unblocks) finds nothing and stays a no-op.
_clarify_adapter = self._delivery_adapter_for(source)
# Class lookup: a MagicMock adapter must not fabricate the method.
if callable(getattr(type(_clarify_adapter), "retire_clarify_card", None)):
try:
await _clarify_adapter.retire_clarify_card(
_pending_clarify.clarify_id,
t("gateway.clarify.cancelled"))
except Exception:
logger.debug("Failed to retire clarify card after prose cancellation", exc_info=True)
return None
# Reply → choice for a pending slash-confirm prompt; the command spelling wins over the
# bang/slash-stripped free-text spelling.
_SLASH_CONFIRM_CMD_CHOICES = {
"approve": "once", "yes": "once", "ok": "once", "confirm": "once",
"always": "always", "remember": "always",
"cancel": "cancel", "no": "cancel", "deny": "cancel", "nevermind": "cancel",
}
# Free-text spellings: ``approval.inputs.confirm_*`` comma-lists (English ∪ active language).
_SLASH_CONFIRM_TEXT_INPUT_KEYS = (("confirm_once", "once"), ("confirm_always", "always"), ("confirm_cancel", "cancel"))
def _slash_confirm_text_choices(self) -> dict[str, str]:
choices: dict[str, str] = {}
for input_key, choice in self._SLASH_CONFIRM_TEXT_INPUT_KEYS:
for word in approval_input_words(input_key):
choices.setdefault(word, choice)
return choices
async def _hm_slash_confirm_reply(self, event: MessageEvent, _quick_key: str) -> Optional[str]:
"""Resolve a reply (/approve, /always, /cancel + aliases) to a pending slash-confirm prompt;
None when it falls through — a stale pending confirm does NOT block other commands. A pending
dangerous-command approval takes precedence: /approve there unblocks the waiting tool thread."""
from tools import slash_confirm as _slash_confirm_mod
_pending_confirm = _slash_confirm_mod.get_pending(_quick_key)
if not _pending_confirm:
return None
with suppress(Exception):
from tools.approval import has_blocking_approval
if has_blocking_approval(_quick_key):
return None
# Accept bang-prefixed replies (`!always`, `!cancel`) verbatim: Slack/Matrix show the `!`
# prefix (typed `/` is blocked in Slack threads) and adapters only rewrite
# `!<known-command>` — confirm keywords aren't commands, so the `!` survives to here.
_norm_reply = (event.text or "").strip().lstrip("!/").lower()
_confirm_choice = (
self._SLASH_CONFIRM_CMD_CHOICES.get(event.get_command())
or self._slash_confirm_text_choices().get(_norm_reply)
)
if _confirm_choice is not None:
_resolved = await _slash_confirm_mod.resolve(
_quick_key, _pending_confirm.get("confirm_id"), _confirm_choice,
)
return _resolved or ""
# Stale pending + unrelated command: the user moved on, so drop the pending state rather
# than let the confirm block normal usage indefinitely.
_slash_confirm_mod.clear_if_stale(_quick_key)
return None
def _hm_evict_idle_stale_agent(self, _quick_key: str) -> None:
"""Evict a leaked lock from a hung/crashed handler: only when the agent has been *idle* past
the threshold (active tasks can run for hours), or has no activity tracker and an extreme
wall-clock age. The pending sentinel is never evicted (no get_activity_summary() → idle
reads inf and would race the async setup path)."""
from gateway.run import _AGENT_PENDING_SENTINEL, _float_env
_raw_stale_timeout = _float_env("HERMES_AGENT_TIMEOUT", 1800)
_quick_state = self._peek_session_state(_quick_key)
_stale_ts = _quick_state.turn.started_ts if _quick_state else 0
if _quick_state is None or _quick_state.turn.agent is None or not _stale_ts:
return
_stale_age = time.time() - _stale_ts
_stale_agent = _quick_state.turn.agent
_stale_idle = float("inf") # assume idle if we can't check
_stale_detail = ""
_activity_summary_valid = False
if _stale_agent and hasattr(_stale_agent, "get_activity_summary"):
with suppress(Exception):
_sa = _stale_agent.get_activity_summary()
from gateway.session_stall import resolve_session_idle_seconds_from_activity
_sa_d = _sa if isinstance(_sa, dict) else {}
_resolved_idle = resolve_session_idle_seconds_from_activity(
_sa if isinstance(_sa, dict) else None, now=time.time(),
)
if _resolved_idle is not None:
_stale_idle = _resolved_idle
_activity_summary_valid = True
# Host sleep is not idleness: share the turn poll loop's meter (same event loop).
_awake_idle = getattr(_quick_state.turn.ctx, "awake_idle", None)
if _awake_idle is not None:
_stale_idle = _awake_idle.measure(_stale_idle)
_stale_detail = (
f" | last_activity={_sa_d.get('last_activity_desc', 'unknown')} "
f"({_stale_idle:.0f}s ago) "
f"| iteration={_sa_d.get('api_call_count', 0)}/{_sa_d.get('max_iterations', 0)}"
)
# A valid activity clock is authoritative: total age alone never makes an actively
# progressing turn stale. The emergency wall TTL is only a fallback when the agent cannot
# report usable activity.
_wall_ttl = max(_raw_stale_timeout * 10, 7200) if _raw_stale_timeout > 0 else float("inf")
_should_evict = _stale_agent is not _AGENT_PENDING_SENTINEL and (
(_activity_summary_valid and _raw_stale_timeout > 0 and _stale_idle >= _raw_stale_timeout)
or (not _activity_summary_valid and _stale_age > _wall_ttl)
)
if _should_evict:
logger.warning(
"Evicting stale _running_agents entry for %s "
"(age: %.0fs, idle: %.0fs, timeout: %.0fs)%s",
_quick_key, _stale_age, _stale_idle, _raw_stale_timeout, _stale_detail,
)
self._hm_evict_running_agent(_quick_key, "stale_running_agent_eviction")
def _hm_evict_reaped_agent(self, _quick_key: str) -> None:
"""Evict the in-memory turn slot of a session whose durable row was ended while the gateway
lived (``ws_orphan_reap`` / ``agent_close``): otherwise the fast-path queues every next
message into the dead runtime. The cold path re-attaches via ``get_or_create_session``."""
try:
# #99106: durable-reaped guard. This is the live-gateway variant of #54878 and the #632
# detached/ 405 suppressions in production. Evict the stale slot so the next message falls
# through to the cold path and re-attaches or creates a fresh session; /status then correctly
# shows 代理运行中: 否 before the heal and a live turn after.
_reap_store = getattr(self, "session_store", None)
# Public, lock-held accessors: peek_session_id returns a non-str on stubbed stores in
# bare test runners — the isinstance() / ``is True`` gates keep this inert unless a
# real SessionStore answers.
_reap_peek = getattr(_reap_store, "peek_session_id", None)
_is_ended = getattr(_reap_store, "_is_session_ended_in_db", None)
_reap_sid = _reap_peek(_quick_key) if callable(_reap_peek) else None
if isinstance(_reap_sid, str) and _reap_sid and callable(_is_ended) and _is_ended(_reap_sid) is True:
logger.warning(
"Evicting stale _running_agents entry for %s — "
"durable session %s is ended (reaped) in state.db; "
"healing routing on next message (#99106)", _quick_key, _reap_sid,
)
self._hm_evict_running_agent(_quick_key, "reaped_session_eviction")
except Exception:
logger.debug("reaped-session staleness check failed", exc_info=True)
def _hm_evict_running_agent(self, _quick_key: str, reason: str) -> None:
from gateway.run import _INTERRUPT_REASON_EVICTED, _INTERRUPT_TOOL_REASON_EVICTED
_generation_at_interrupt = self._interrupt_running_turn(
_quick_key, interrupt_reason=_INTERRUPT_REASON_EVICTED, invalidation_reason=reason,
tool_reason=_INTERRUPT_TOOL_REASON_EVICTED)
self._drop_turn_slot(_quick_key, run_generation=_generation_at_interrupt)
def _hm_merge_pending_for_source(
self, source: SessionSource, _quick_key: str, event: MessageEvent, *, merge_text: bool = False
) -> None:
"""Merge *event* into the source adapter's pending slot (no-op without an adapter)."""
from gateway.platforms.base import merge_pending_message_event
adapter = self._delivery_adapter_for(source)
if adapter:
merge_pending_message_event(adapter._pending_messages, _quick_key, event, merge_text=merge_text)
async def _hm_busy_slash_or_photo(
self, event: MessageEvent, source: SessionSource, _quick_key: str
) -> tuple[bool, Optional[str]]:
"""Slash-command / photo-burst handling on the busy fast-path → ``(handled, result)``. Each
command's mid-run behavior is declared on its CommandDef (busy_policy / busy_handler)."""
from hermes_cli.commands import resolve_command as _resolve_cmd_inner
_evt_cmd = event.get_command()
_cmd_def_inner = _resolve_cmd_inner(_evt_cmd) if _evt_cmd else None
if _cmd_def_inner:
# /status and /context are intentionally pre-gate so users always see session state.
if _cmd_def_inner.name == "status":
return True, await self._handle_status_command(event)
if _cmd_def_inner.name == "context":
return True, await self._handle_context_command(event)
# Slash access control mirrors the cold-path gate so non-admins can't bypass gating
# just because an agent is busy. /help and /whoami are the always-allowed floor.
_denied = self._check_slash_access(source, _cmd_def_inner.name)
if _denied is not None:
return True, _denied
if _cmd_def_inner.name in ("stop", "new"):
await self._hm_stop_owner_turn(_quick_key)
# Any recognized slash command dispatches per its declared busy_policy (dispatch /
# interrupt_then_dispatch / reject). Unrecognized commands and plain text fall through.
return True, await self._dispatch_busy_slash_command(event, _cmd_def_inner, _quick_key, source)
# Telegram photo bursts arrive as near-simultaneous updates — never interrupt for a
# photo-only follow-up; adapter-level batching absorbs them.
if event.message_type == MessageType.PHOTO:
logger.debug("PRIORITY photo follow-up for session %s — queueing without interrupt", _quick_key)
self._hm_merge_pending_for_source(source, _quick_key, event)
return True, None
return False, None
async def _hm_stop_owner_turn(self, _quick_key: str) -> None:
"""Messaging /stop and /new (busy, idle or confirmed) act on the authority's turn, as main
cancelled the adapter task that ran it and dropped its pending slot. Cancels the still-queued
``messaging:*`` rows of this route's logical owner first (automation wakes, LOCAL/API input
and ``unknown`` rows are untouched; settled silently, no pause notice), then interrupts the
claimed generation: a turn still constructing its agent latches the Stop for adopt_agent."""
from gateway.session_authorities import active_authority
authority = active_authority(self)
sid = authority.logical_owner(self.session_store.peek_session_id(_quick_key)) if authority else None
if not sid or sid not in authority.sessions:
if authority is not None:
# The chat's first input, and a command's turn, not committed yet never commit.
authority.fence_route(_quick_key)
return
from gateway.session_contract import Principal, SessionRef
from hermes_state_runtime import RuntimeStoreError, list_session_admissions
ref = SessionRef(authority.profile_id, sid)
actor = Principal('messaging-control', authority.profile_id,
frozenset({'session:submit', 'session:control'}), 'busy-command')
rows = await asyncio.to_thread(list_session_admissions, authority.db, session_id=sid)
# A FIFO paused on a lost (``unknown``) turn is the operator's to resume: its pause notice
# promised the queued followers stay saved, so a /new from the chat leaves them queued.
paused = any(row['status'] == 'unknown' for row in rows)
if not paused:
# Input (and a command's turn) that arrived before this and is not committed yet never
# commits after it; one that committed before the fence is in the second listing and
# cancelled below. A paused FIFO keeps both, like its queued followers.
authority.fence_route(_quick_key)
rows = await asyncio.to_thread(list_session_admissions, authority.db, session_id=sid)
for row in [] if paused else rows:
if row['status'] == 'queued' and row['principal_id'].startswith('messaging:'):
# Claimed meanwhile (stale_generation): it runs as main's post-claim race does.
with suppress(RuntimeStoreError):
await authority.cancel_queued(actor, ref, row['admission_id'])
handle = authority._handle(ref)
if handle.execution_state == 'running':
# Settled meanwhile (stale_generation): there is no claimed turn left to stop.
with suppress(RuntimeStoreError):
await authority.interrupt(actor, ref, handle.execution_generation)
def _hm_busy_telegram_grace_queue(
self, event: MessageEvent, source: SessionSource, _quick_key: str, effective_busy_input_mode: str
) -> bool:
"""Queue a Telegram text follow-up that lands within the post-start grace window."""
_grace = float(os.getenv("HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS", "3.0"))
_grace_state = self._peek_session_state(_quick_key)
_started_at = _grace_state.turn.started_ts if _grace_state else 0
if not (
source.platform == Platform.TELEGRAM and event.message_type == MessageType.TEXT
and _grace > 0 and _started_at and (time.time() - _started_at) <= _grace
):
return False
logger.debug(
"Telegram follow-up arrived %.2fs after run start for %s — queueing without interrupt",
time.time() - _started_at, _quick_key,
)
if effective_busy_input_mode != "queue":
self._hm_merge_pending_for_source(source, _quick_key, event, merge_text=True)
else:
adapter = self._delivery_adapter_for(source)
if adapter:
self._enqueue_fifo(_quick_key, event, adapter)
return True
@staticmethod
def _hm_text_only(event: MessageEvent) -> bool:
return event.message_type == MessageType.TEXT and not event.media_urls and not event.media_types
def _hm_busy_steer(self, event: MessageEvent, running_agent: Any, _quick_key: str) -> None:
"""Steer mode: inject text mid-run via ``agent.steer()``, else fall back to queue semantics."""
steer_text = (event.text or "").strip()
steered = False
if self._hm_text_only(event) and steer_text and hasattr(running_agent, "steer"):
try:
steered = self._steer_running_agent(running_agent, self._steer_text_with_origin(steer_text, event))
except Exception as exc:
logger.warning("PRIORITY steer failed for session %s: %s", _quick_key, exc)
if steered:
self._fold_into_running_turn(running_agent, _quick_key, event)
logger.debug("PRIORITY steer for session %s", _quick_key)
return
logger.debug("PRIORITY steer-fallback-to-queue for session %s", _quick_key)
self._queue_or_replace_pending_event(_quick_key, event)
async def _hm_busy_interrupt(
self, event: MessageEvent, source: SessionSource, running_agent: Any, _quick_key: str
) -> None:
"""Interrupt path: redirect text-only corrections when supported, else ``agent.interrupt()``."""
from gateway.run import _build_media_placeholder
# Text-only corrections redirect the live turn (preserving displayed context) when the
# runtime supports it; media/voice and older runtimes use the interrupt path below.
_can_redirect = getattr(running_agent, "_supports_active_turn_redirect", False) is True
if self._hm_text_only(event) and _can_redirect and hasattr(running_agent, "redirect"):
if self._redirect_active_turn(running_agent, (event.text or "").strip(), _quick_key, event):
logger.debug("PRIORITY redirect for session %s", _quick_key)
return
logger.debug("PRIORITY interrupt for session %s", _quick_key)
_interrupt_text = event.text
if self._pending_event_audio_paths(event):
_interrupt_text, _ = await self._transcribe_and_echo_pending_voice(
event, self._delivery_adapter_for(source), source, event.text or "",
log_context="Voice-priority-interrupt",
)
elif not _interrupt_text and getattr(event, "media_urls", None):
_interrupt_text = _build_media_placeholder(event)
# Delivered via adapter._pending_messages (read by _run_agent); never also buffered on self
# — that copy was never consumed and grew unbounded.
running_agent.interrupt(_interrupt_text)
async def _hm_busy_preempt(self, event: MessageEvent, source: SessionSource, _quick_key: str) -> bool:
"""busy_input_mode for a follow-up the durable FIFO is about to admit, through main's own busy
resolution (voice transcribed into steer/interrupt, steer folded into the turn, busy ack).
Returns True when the text already landed inside the running turn (steer / redirect), so it
must NOT also be admitted as its own turn; False when the caller should admit it (queue mode,
a demotion, or an interrupt — the ended turn lets the FIFO run the follow-up next)."""
from gateway.run import _AGENT_PENDING_SENTINEL
mode = self._effective_busy_input_mode(source)
state = self._peek_session_state(_quick_key)
running_agent = state.turn.agent if state else None
adapter = self._delivery_adapter_for(source)
if (self._draining or adapter is None or running_agent is None or running_agent is _AGENT_PENDING_SENTINEL
or (event.message_type == MessageType.TEXT and mode != "steer"
and self._effective_busy_text_mode(source) == "queue")):
return False
outcome = await self._resolve_busy_steer_or_redirect(event, _quick_key, mode, running_agent)
note_busy_outcome(event, outcome)
await self._busy_interrupt_and_ack(event, _quick_key, adapter, state, running_agent, outcome)
return bool(outcome.steered or outcome.redirected)
async def _hm_handle_running_session_message(
self, event: MessageEvent, source: SessionSource, _quick_key: str
) -> Optional[str]:
"""Fast-path while this session's agent is running: interrupt by default (minimal latency);
busy_input_mode queue/steer, subagent and compression protection demote to queue."""
from gateway.run import _AGENT_PENDING_SENTINEL
if getattr(event, "internal", False) and not event.get_command():
# Main's rule (run_busy's busy handler, which the shared runtime's busy dispatch skips):
# an internal synthetic event never interrupts or steers the running turn.
self._queue_or_replace_pending_event(_quick_key, event)
return None
_handled, _result = await self._hm_busy_slash_or_photo(event, source, _quick_key)
if not _handled:
_handled, _result = await self._busy_skill_turn(event, source, _quick_key)
if _handled:
return _result
effective_busy_input_mode = self._effective_busy_input_mode(source)
if self._hm_busy_telegram_grace_queue(event, source, _quick_key, effective_busy_input_mode):
return None
_ra_state = self._peek_session_state(_quick_key)
running_agent = _ra_state.turn.agent if _ra_state else None
if running_agent is _AGENT_PENDING_SENTINEL: # agent still being set up
if event.get_command() == "stop": # force-clean the sentinel so the session is unlocked
self._release_running_agent_state(_quick_key)
logger.info("HARD STOP (pending) for session %s — sentinel cleared", _quick_key)
return EphemeralReply(t("gateway.stop.force_stopped_pending"))
self._hm_merge_pending_for_source(source, _quick_key, event, merge_text=True) # picked up after start
return None
if self._draining:
queue_during_drain = self._queue_during_drain_enabled(effective_busy_input_mode)
if queue_during_drain:
self._queue_or_replace_pending_event(_quick_key, event)
return (
t("gateway.busy.drain_queued", action=self._status_action_gerund())
if queue_during_drain
else t("gateway.busy.drain_rejected", action=self._status_action_gerund())
)
if effective_busy_input_mode == "queue":
logger.debug("PRIORITY queue follow-up for session %s", _quick_key)
self._queue_or_replace_pending_event(_quick_key, event)
return None
if effective_busy_input_mode == "steer":
self._hm_busy_steer(event, running_agent, _quick_key)
return None
# Subagent protection: an interrupt cascades through ``_active_children`` and aborts
# in-flight delegate_task work (/stop reached its handler above — still an escape hatch).
# Compression protection: an interrupt would start a new turn on the pre-rotation parent
# while compression rotates the id away, forking orphaned siblings.
if self._agent_has_active_subagents(running_agent):
_demote = "because the running agent has active subagents (#30170)"
elif await self._session_has_compression_in_flight(_quick_key):
_demote = "because context compression is in flight (#56391)"
else:
await self._hm_busy_interrupt(event, source, running_agent, _quick_key)
return None
logger.info("PRIORITY interrupt demoted to queue for session %s %s", _quick_key, _demote)
self._queue_or_replace_pending_event(_quick_key, event)
return None
async def _hm_resolve_command(
self, event: MessageEvent, source: SessionSource, _quick_key: str
) -> tuple[bool, Optional[str], Optional[str], Optional[str]]:
"""Resolve the slash command (aliases, access gate, hooks) → ``(handled, result, command,
canonical)``; when ``handled`` the caller returns ``result`` as-is (may be None)."""
from hermes_cli.commands import is_gateway_known_command, resolve_command as _resolve_cmd
def _canon(cmd):
# Aliases resolve to the canonical name so dispatch and hook names don't depend on them.
_def = _resolve_cmd(cmd) if cmd else None
return _def, (_def.name if _def else cmd)
command = event.get_command()
_cmd_def, canonical = _canon(command)
# Expand alias quick commands before built-in dispatch so targets like /model openai/gpt-5.5
# --provider openrouter reach the /model handler. Built-ins keep precedence: aliases only
# need early handling when the typed command is not already known.
if command and _cmd_def is None:
qcmd = self._hm_quick_commands().get(command)
if qcmd is not None and qcmd.get("type") == "alias":
new_command = self._hm_expand_alias_quick_command(event, qcmd)
if new_command is not None:
command = new_command
_cmd_def, canonical = _canon(command)
if not (command and canonical and is_gateway_known_command(canonical)):
return False, None, command, canonical
# Per-platform slash access control: only active when the operator set ``allow_admin_from``
# for the source's scope; then non-admins get ``user_allowed_commands`` plus the
# /help, /whoami floor. Plain chat is never gated.
_denied = self._check_slash_access(source, canonical)
if _denied is not None:
return True, _denied, command, canonical
_handled, _result, new_command = await self._hm_command_hooks(
event, source, _quick_key, command, canonical
)
if _handled:
return True, _result, command, canonical
if new_command is not None:
command = new_command
_cmd_def, canonical = _canon(command)
return False, None, command, canonical
async def _hm_confirm_destructive(self, event, command: str, detail: str, handler) -> tuple[bool, Optional[str]]:
async def _execute():
return await handler(event)
return True, await self._maybe_confirm_destructive_slash(
event=event, command=command, title=f"/{command}", detail=detail, execute=_execute,
)
async def _hm_cmd_new(self, event, source, _quick_key):
if await asyncio.to_thread(self._is_telegram_topic_root_lobby, source):
return True, self._telegram_topic_root_new_message()
return await self._hm_confirm_destructive(
event, "new", t("gateway.confirm.detail_new"),
self._handle_reset_command,
)
async def _hm_cmd_start(self, event, source, _quick_key):
logger.info("Ignoring /start platform ping for session %s", _quick_key)
return True, ""
async def _hm_cmd_egress(self, event, source, _quick_key):
from hermes_cli.proxy_cli import format_status_text
return True, format_status_text()
async def _hm_rewrite_turn_to_prompt(self, event, source, name: str, ack: str, build) -> tuple[bool, Optional[str]]:
"""Ack, then rewrite the turn to ``build()`` and fall through to the agent (keeps role
alternation; works on any backend). A failing builder replies with a retry hint."""
await self._send_command_ack(source, ack, name)
try:
event.text = await asyncio.to_thread(build)
except Exception:
return True, t("gateway.prompt_command.start_failed", command=name)
return False, None
# /learn and /plan: ack, rewrite the turn to a builder prompt, fall through to the agent.
async def _hm_cmd_learn(self, event, source, _quick_key):
from agent.learn_prompt import build_learn_prompt
req = event.get_command_args().strip()
_ack = t("gateway.learn.ack_described") if req else t("gateway.learn.ack_conversation")
return await self._hm_rewrite_turn_to_prompt(event, source, "learn", _ack, lambda: build_learn_prompt(req))
async def _hm_cmd_plan(self, event, source, _quick_key):
from agent.plan_prompt import build_plan_prompt
task = event.get_command_args().strip()
_ack = (t("gateway.plan.ack_task", task=task[:80] + ("…" if len(task) > 80 else ""))
if task else t("gateway.plan.ack_conversation"))
return await self._hm_rewrite_turn_to_prompt(event, source, "plan", _ack, lambda: build_plan_prompt(task))
async def _hm_cmd_init(self, event, source, _quick_key):
# /init builds the prompt first: the ack wording depends on whether AGENTS.md exists.
from hermes_cli.init_command import build_init_prompt_for_cwd
try:
# The SESSION's active directory, not this process's launch dir: the desktop app
# launches the backend from the home directory, so a bare os.getcwd() scanned and
# updated the HOME's AGENTS.md instead of the workspace attached to the session.
_init_prompt = build_init_prompt_for_cwd(
extra=event.get_command_args().strip(),
session_key=_quick_key or self._session_key_for_source(source),
)
except Exception:
return True, t("gateway.init.start_failed")
_ack = (
t("gateway.init.ack_update")
if "UPDATE the existing AGENTS.md" in _init_prompt
else t("gateway.init.ack_generate")
)
await self._send_command_ack(source, _ack, "init")
event.text = _init_prompt
return False, None
async def _hm_cmd_blueprint(self, event, source, _quick_key):
_blueprint_result = await self._handle_blueprint_command(event)
_text = getattr(_blueprint_result, "text", "") or ""
_blueprint_seed = getattr(_blueprint_result, "agent_seed", None)
if not _blueprint_seed:
return True, _text or None
# Blueprint matched — rewrite the turn to the seed and fall through so the agent collects
# each slot value conversationally, then calls the cronjob tool (the /steer pattern).
if _text:
await self._send_command_ack(source, _text, "blueprint")
try:
event.text = _blueprint_seed
except Exception:
return True, _text or None
return False, None
async def _hm_cmd_undo(self, event, source, _quick_key):
_undo_n = 1
_undo_raw = event.get_command_args().strip()
if _undo_raw:
with suppress(ValueError, IndexError):
_undo_n = max(1, int(_undo_raw.split()[0]))
_undo_detail = (
t("gateway.confirm.detail_undo_one")
if _undo_n == 1
else t("gateway.confirm.detail_undo_many", count=_undo_n)
)
return await self._hm_confirm_destructive(event, "undo", _undo_detail, self._handle_undo_command)
# /queue and /steer on the idle path: no agent is running, so strip the prefix and send the
# payload as a regular user turn; an empty payload surfaces the usage hint.
async def _hm_cmd_queue(self, event, source, _quick_key):
return self._hm_send_payload_as_turn(event, t("gateway.queue.usage"))
async def _hm_cmd_steer(self, event, source, _quick_key):
return self._hm_send_payload_as_turn(event, t("gateway.steer.usage_idle"))
@staticmethod
def _hm_send_payload_as_turn(event, usage: str) -> tuple[bool, Optional[str]]:
payload = event.get_command_args().strip()
if not payload:
return True, usage
with suppress(Exception):
event.text = payload
return False, None
async def _hm_cmd_moa(self, event, source, _quick_key):
# /moa is one-shot sugar only: run a single prompt through the default MoA preset, then
# restore the prior model. To *switch* to a MoA preset for the session, pick it from the
# model picker (MoA presets surface as a virtual "Mixture of Agents" provider).
from hermes_cli.moa_config import moa_usage, normalize_moa_config
from hermes_cli.config import load_config
moa_payload = event.get_command_args().strip()
if not moa_payload:
return True, moa_usage()
try:
cfg = load_config()
moa_cfg = normalize_moa_config(cfg.get("moa") if isinstance(cfg, dict) else {})
except Exception:
moa_cfg = normalize_moa_config({})
try:
event.text = moa_payload
_moa_state = self._session_state(_quick_key)
# Same one-shot snapshot `/model --once` uses, so eviction/stop/finalizer settle both alike.
self._claim_one_turn_restore(_quick_key)
_moa_state.conversation.model_override = {
"provider": "moa", "model": moa_cfg["default_preset"], "base_url": "moa://local",
"api_key": "moa-virtual-provider", "api_mode": "chat_completions",
}
self._evict_cached_agent(_quick_key)
except Exception:
return True, t("gateway.moa.prepare_failed")
return False, None
# Idle-path built-ins with bespoke flow (confirmations, prompt rewrites, one-shot MoA), each
# handled by ``_hm_cmd_<name>`` → ``(handled, result)``; ``(False, None)`` falls through to the agent.
_HM_CANONICAL_COMMANDS = frozenset({
"new", "start", "egress", "learn", "plan", "init", "blueprint", "undo", "queue", "steer", "moa",
})
async def _hm_dispatch_canonical_command(
self, event: MessageEvent, source: SessionSource, _quick_key: str,
canonical: Optional[str],
) -> tuple[bool, Optional[str]]:
"""Dispatch built-in idle-path commands → ``(handled, result)``; prompt-rewriting commands
mutate ``event.text`` and return ``(False, None)`` to fall through to the agent."""
plain_handler = (
self._gateway_plain_command_handlers().get(canonical)
or self._gateway_idle_command_handlers().get(canonical)
)
if plain_handler is not None:
async with self._async_profile_scope_for_source(source):
return True, await plain_handler(event)
if canonical in self._HM_CANONICAL_COMMANDS:
return await getattr(self, f"_hm_cmd_{canonical}")(event, source, _quick_key)
return False, None
def _hm_bundle_slash_rewrite(
self, event: MessageEvent, source: SessionSource, _quick_key: str, command: str
) -> bool:
"""Rewrite ``/<bundle>`` to the bundle invocation message; True when handled.
Skill bundles take precedence over individual skill commands (mirrors CLI dispatch)."""
try:
from agent.skill_bundles import (
build_bundle_invocation_message, resolve_bundle_command_key
)
bundle_key = resolve_bundle_command_key(command)
if bundle_key is None:
return False
# Pass the platform explicitly: bundle skill loading bypasses get_skill_commands()'
# scan-time disabled filter, and one gateway process serves several platforms, so
# env-var platform resolution can't be trusted here.
# Mirrors the stacked-skill gate (#58888).
bundle_result = build_bundle_invocation_message(
bundle_key, event.get_command_args().strip(), task_id=_quick_key,
platform=source.platform.value if source.platform else None,
)
if not bundle_result:
return False
event.text, _loaded, missing = bundle_result
if missing:
logger.info("Bundle %s skipped missing skills: %s", bundle_key, ", ".join(missing))
return True # Fall through to normal message processing with bundle content
except Exception as exc:
logger.warning("Bundle dispatch failed: %s", exc)
return False
@staticmethod
def _hm_unknown_slash_reply(command: str, source: SessionSource) -> Optional[str]:
"""Reply for a /command that is not built-in/plugin/skill; None when it is known."""
from gateway.run import _check_unavailable_skill
from hermes_cli.commands import GATEWAY_KNOWN_COMMANDS
# Known commands never need an unavailable-skill hint (which can require a cold scan).
if command.replace("_", "-") in GATEWAY_KNOWN_COMMANDS:
return None
# Known-but-disabled or uninstalled skill → actionable guidance.
_unavail_msg = _check_unavailable_skill(command)
if _unavail_msg:
return _unavail_msg
# Genuinely unrecognized: warn instead of forwarding to the LLM as free text (it invents
# tool calls). Normalize to hyphenated form first: the quick-command block may have set an
# alias target, so the resolved def can be stale.
logger.warning(
"Unrecognized slash command /%s from %s — replying with unknown-command notice",
command, source.platform.value if source.platform else "?",
)
return t("gateway.unknown_command", command=command)
def _hm_skill_slash_rewrite(
self, event: MessageEvent, source: SessionSource, _quick_key: str, command: Optional[str]
) -> Optional[str]:
"""Rewrite ``/<bundle>`` / ``/<skill>`` invocations into the skill prompt on ``event.text``;
returns a reply string when the command is disabled/unknown/failed, else None.
resolve_skill_command_key() handles the Telegram underscore/hyphen round-trip (/claude_code)."""
if not command or self._hm_bundle_slash_rewrite(event, source, _quick_key, command):
return None
try:
from agent.skill_commands import (
get_skill_commands, build_skill_invocation_message, resolve_skill_command_key
)
skill_cmds = get_skill_commands()
cmd_key = resolve_skill_command_key(command)
if cmd_key is None:
return self._hm_unknown_slash_reply(command, source)
_plat = source.platform.value if source.platform else None
user_instruction = event.get_command_args().strip()
# Stacked slash-skill invocations: `/skill-a /skill-b do XYZ` loads every leading skill
# (up to 5), not just the first. Mirrors CLI. Native split: plugin skills are interactive-only.
try:
from agent.skill_commands import (
build_stacked_skill_invocation_message as _build_stacked,
split_stacked_skill_commands,
)
extra_keys, stacked_instruction = split_stacked_skill_commands(user_instruction)
except Exception:
_build_stacked = None
extra_keys, stacked_instruction = [], user_instruction
_skill_name = skill_cmds[cmd_key].get("name", "")
if _plat and (_skill_name or extra_keys):
# Per-platform disabled check: get_skill_commands() only applies the *global*
# disabled list at scan time (process-global cache across platforms), and
# split_stacked_skill_commands() only checks each extra token is a KNOWN skill.
from agent.skill_utils import get_disabled_skill_names as _get_plat_disabled
_plat_disabled = _get_plat_disabled(platform=_plat)
if _skill_name and _skill_name in _plat_disabled:
return t("gateway.skills.disabled_for_platform", name=_skill_name, platform=_plat)
_disabled_extra = [
skill_cmds.get(k, {}).get("name", "")
for k in extra_keys
if skill_cmds.get(k, {}).get("name", "") in _plat_disabled
]
if _disabled_extra:
return t("gateway.skills.stacked_disabled", names=", ".join(_disabled_extra), platform=_plat)
if extra_keys and _build_stacked is not None:
stacked_result = _build_stacked(
[cmd_key, *extra_keys], stacked_instruction, task_id=_quick_key,
)
if not stacked_result:
return t("gateway.skills.stacked_load_failed", command=command)
event.text, _loaded, _missing = stacked_result
else:
msg = build_skill_invocation_message(cmd_key, user_instruction, task_id=_quick_key)
if msg:
event.text = msg
# Fall through to normal message processing with skill content
except Exception as e:
logger.debug("Skill command check failed (non-fatal): %s", e)
return None
async def _hm_pending_reply_intercepts(
self, event: MessageEvent, source: SessionSource, _quick_key: str
) -> Optional[str]:
"""Replies owned by in-flight work: pending /update prompt, clarify, slash-confirm.
Only events that may control the gateway (``allow_gateway_control``) can answer them, never
an admitted turn: it was offered here before its commit, or a slash command queued it."""
from gateway.session_ingress import executing_admission
if not event.allow_gateway_control or getattr(event, "_fifo_only", False) or executing_admission.get():
return None
_reply = self._hm_update_prompt_reply(event, _quick_key)
if _reply is None:
_reply = await self._hm_clarify_reply(event, source, _quick_key)
if _reply is None:
_reply = await self._hm_slash_confirm_reply(event, _quick_key)
return _reply
async def _hm_dispatch_idle_commands(
self, event: MessageEvent, source: SessionSource, _quick_key: str
) -> tuple[bool, Optional[str]]:
"""Idle path: resolve + dispatch slash commands; rewriting commands fall through to the agent.
A command rewritten into a turn keeps the /stop and /new epoch it arrived under, read before
the (slow, off-loop) rewrite, so a reset during it drops the command, as on the busy path."""
stop_epoch = self._route_stop_epoch(_quick_key)
_handled, _result, command, canonical = await self._hm_resolve_command(event, source, _quick_key)
if not _handled:
_handled, _result = await self._hm_dispatch_canonical_command(event, source, _quick_key, canonical)
if not _handled:
_handled, _result, command = await self._hm_dispatch_quick_and_plugin_commands(event, source, command)
if not _handled:
# Skill-slash resolution is disk-bound (cold skill scan, skill file loads, the
# unavailable-skill rglob over every skills dir) and uncached on a first hit; on a
# large install it held the loop past the liveness watchdog (#111091). The executor
# hop carries the profile contextvars the scan is scoped to.
_result = await self._run_in_executor_with_context(
self._hm_skill_slash_rewrite, event, source, _quick_key, command)
_handled = _result is not None
if not _handled and command: # rewritten into a turn: the authority's FIFO, like text
_handled, _result = await self._admit_command_turn(event, source, _quick_key, stop_epoch)
return _handled, _result
def _hm_rescue_orphaned_fifo(
self, event: MessageEvent, source: SessionSource, is_internal: bool, _quick_key: str
) -> tuple[MessageEvent, SessionSource, bool]:
"""FIFO orphan rescue: a session that went idle with a populated overflow (post-turn drain
never promoted, e.g. a compression-demoted follow-up) silently orphaned those events. The
oldest orphan runs as THIS turn and the incoming event is parked behind the chain. Skipped
for control commands and internal events."""
try:
# ── FIFO orphan rescue (#99882) ──────────────────────────────── If this session went idle with
# a populated overflow (queued during a busy window whose post-turn drain never promoted — e.g.
# a compression-demoted follow-up after the compression window ended through an exit that
# skipped the promotion site), those events were silently orphaned. We are starting the next
# turn for this session NOW: re-stage the orphans in FIFO order and enqueue the incoming event
# behind them, so arrival order (#28503) holds: oldest orphan runs as this turn, the rest drain
# in order, the new message last.
_orphan_adapter = self._delivery_adapter_for(source)
if _orphan_adapter is None or getattr(event, "internal", False) or event.get_command():
return event, source, is_internal
_rescued = self._rescue_orphaned_overflow(_quick_key, _orphan_adapter)
if _rescued is None:
return event, source, is_internal
# Into the slot when the chain was a single orphan (post-turn drain picks it up),
# otherwise into overflow behind the already-staged next orphan.
self._enqueue_fifo(_quick_key, event, _orphan_adapter)
# Same session key by construction; carry the orphan's own source so reply anchors /
# thread metadata point at the message actually being answered.
_rescued_source = getattr(_rescued, "source", None)
source = _rescued_source if _rescued_source is not None else source
return _rescued, source, bool(getattr(_rescued, "internal", False))
except Exception:
logger.debug("FIFO orphan rescue pre-claim failed for %s", _quick_key, exc_info=True)
return event, source, is_internal
async def _hm_authority_admission(
self, event: MessageEvent, source: SessionSource, _quick_key: str, is_internal: bool,
) -> tuple[bool, Optional[str]]:
"""``(True, reply)`` when the routed profile's session authority owned this message
(preempted, plugin-consumed or admitted to its durable FIFO); ``(False, None)`` to continue
on the in-process path. Raises ``RuntimeStoreError('profile_mismatch')`` for a scope this
process does not serve."""
# The message handler entered the routed profile's scope; its authority owns this turn.
from gateway.session_authorities import active_authority
authority = active_authority(self)
if authority is not None and not event.get_command() and not is_internal:
from gateway.session_ingress import executing_admission
if not executing_admission.get():
# A message the adapter saw as idle still waits when an earlier queued turn runs
# outside its session guard: the running-turn check is the busy test that counts.
busy = self._is_session_running(_quick_key) and not getattr(event, "_fifo_only", False)
if busy:
stamp_busy_arrival(self._delivery_adapter_for(source), event)
try:
return await self._hm_admit_to_fifo(authority, event, source, _quick_key, busy)
finally:
settle_busy_arrival(event) # never admitted, refused or dropped: its fate is known
if (authority is None and not is_internal and not event.get_command()
and getattr(self, 'session_authority', None) is not None):
# Scoped to a home this process does not serve: never fall back to the launch ledger.
from hermes_state_runtime import RuntimeStoreError
raise RuntimeStoreError('profile_mismatch')
return False, None
async def _hm_admit_to_fifo(
self, authority: Any, event: MessageEvent, source: SessionSource, _quick_key: str, busy: bool,
) -> tuple[bool, Optional[str]]:
"""The authority-owned path of ``_hm_authority_admission`` (not inside a FIFO execution)."""
from gateway.session_ingress import admit_message
# The durable FIFO only orders turns; busy_input_mode still decides what a follow-up
# does to the RUNNING one (steer into it, redirect it, or end it so the FIFO advances).
# Without this, ``interrupt`` degrades to ``queue`` behind a turn that may hang for
# its whole request timeout.
# A bare "yes"/"no" to a blocking dangerous-command approval answers it (#46866):
# never an interrupt (read as deny) nor a queued turn (auto-deny deadlock).
# A turn a slash command produced (``/queue yes``) is never live typing.
if busy and (await self._route_plaintext_approval_while_busy(event, _quick_key)
or await self._hm_busy_preempt(event, source, _quick_key)):
return True, None
_consumed, _consumer_reply = await self._hm_post_admission_consume(event, source, _quick_key)
if _consumed:
return True, _consumer_reply
if getattr(event, "_fifo_only", False) and event._stop_epoch != self._route_stop_epoch(_quick_key):
return True, None # a /stop or /new came after its command, as it clears the slot
# A failed admit stays the authority's answer (refusal notice or turn error), never a
# pending legacy turn: that would run unadmitted, outside the FIFO's order.
note_busy_admitting(event)
return True, await admit_message(authority, event)
async def _handle_message(self, event: MessageEvent) -> Optional[str]:
"""Handle an incoming message from any platform: auth → command check → running-agent
interrupt → get/create session → build context → run agent → return response."""
from gateway.run import _AGENT_PENDING_SENTINEL
_admitted = await self._hm_admit_event(event)
if _admitted is None:
return None
event, source, is_internal = _admitted
if not is_internal:
from hermes_cli.observability.shared_metrics_events import record_gateway_slash_command
record_gateway_slash_command(event)
# TERMINAL-DECLINE LATCH TEARDOWN. Deliberately placed AFTER admission,
# not on the adapter's raw inbound: profile routing, the ignored-channel
# guard, plugin hooks and user authorization all reject events above,
# and a rejected event must not be able to clear a refusal belonging to
# an active turn. This is also the single entry point every lane shares
# — Discord interaction passthrough builds its own MessageEvent and
# calls handle_message directly, so a teardown on the relay's inbound
# handler left those turns muted.
_paused_notice = self._hm_estop_gate(event, source, is_internal)
if _paused_notice is not None:
return _paused_notice
_quick_key = self._session_key_for_source(source)
_reply = None if is_internal else await self._hm_pending_reply_intercepts(event, source, _quick_key)
if _reply is not None:
return _reply
_owned, _authority_reply = await self._hm_authority_admission(event, source, _quick_key, is_internal)
if _owned:
return _authority_reply
# Evict a leaked/reaped ``_running_agents`` slot before the busy-session fast-path.
self._hm_evict_idle_stale_agent(_quick_key)
if self._is_session_running(_quick_key):
self._hm_evict_reaped_agent(_quick_key)
if self._is_session_running(_quick_key):
return await self._hm_handle_running_session_message(event, source, _quick_key)
_handled, _result = await self._hm_dispatch_idle_commands(event, source, _quick_key)
if _handled:
return _result
# Pending exec approvals go through /approve and /deny only — no bare-text matching, or a
# conversational "yes" would execute a dangerous command.
if not is_internal:
if await asyncio.to_thread(self._is_telegram_topic_root_lobby, source):
# Debounced so a user who forgets about topic mode doesn't get ten reminders.
if self._should_send_telegram_lobby_reminder(source):
return self._telegram_topic_root_lobby_message()
return None
# External-drain new-turn gate: when NAS engaged an external drain (.drain_request.json,
# seen by _drain_control_watcher), refuse to START new turns so the in-flight set can
# only fall to zero. Reversible.
if self._external_drain_active:
logger.info("Refusing new turn for session %s — external drain active.", _quick_key)
return t("gateway.busy.draining_maintenance")
# Claim this session before any await: many awaits sit between here and _run_agent
# registering the real AIAgent; without this sentinel a second message during any of them
# passes the "already running" guard and spins up a duplicate agent for the same session.
_active_session_lease, _limit_message = self._claim_active_session_slot(_quick_key, source)
if _limit_message is not None:
logger.info("Rejecting new active session %s: max_concurrent_sessions reached", _quick_key)
return _limit_message
event, source, is_internal = self._hm_rescue_orphaned_fifo(event, source, is_internal, _quick_key)
_claim_state = self._session_state(_quick_key)
if _active_session_lease is not None:
_claim_state.turn.lease = _active_session_lease
_claim_state.turn.agent = _AGENT_PENDING_SENTINEL
_claim_state.turn.event = event
_claim_state.turn.started_ts = time.time()
from hermes_cli.observability.shared_metrics_gateway import start_reply_clock
start_reply_clock(source, internal=is_internal)
self._persist_active_agents()
_run_generation = self._begin_session_run_generation(_quick_key)
try:
# Fail-open plugin consume inside the claimed slot (#129958); once per message.
if not is_internal:
_consumed, _consumer_reply = await self._hm_post_admission_consume(event, source, _quick_key)
if _consumed:
return _consumer_reply
try:
_agent_result = await self._handle_message_with_agent(event, source, _quick_key, _run_generation)
except TurnLeaseTimeoutError as exc:
# A rejected message, not a completed turn: return before the /goal judge so it
# cannot consume the resend notice and enqueue a synthetic continuation loop.
logger.error(
"Rejecting turn for routing key %s on session %s after "
"turn-lease timeout; transcript load was not started and "
"the user must resend",
_quick_key, exc.session_id,
)
return t("gateway.busy.another_turn_running")
try:
await self._run_post_turn_hooks(
agent_result=_agent_result, source=source, is_internal=is_internal, event=event,
)
except Exception as _goal_exc:
logger.debug("post-turn hook failed: %s", _goal_exc)
return _agent_result
finally:
# One-shot restore (/moa, /model --once) must run on EVERY exit path (success,
# exception, interrupt); the generation guard makes a displaced turn's finalizer a no-op.
self._restore_pending_one_turn_model_override(_quick_key, _run_generation)
# SIGKILL/OOM skips finally, leaving the durable marker for the next unclean startup's
# recovery pass. A turn the adapter delivers hands its marker to that lifecycle, which
# clears it only once the reply is in the delivery ledger (else a kill in between
# left neither marker nor ledger row and the persisted reply was never sent).
if not getattr(event, "_turn_marker_handoff", False):
await self._clear_durable_active_turn(event)
# Release only this turn's generation. Eviction may immediately admit a replacement
# through the cold path; an unconditional release here would then clear the replacement
# sentinel/agent and lease. Reset/stop release their stale slot before installing a
# successor, preserving reset-zombie cleanup without granting gen-N successor authority.
self._release_running_agent_state(_quick_key, run_generation=_run_generation)
# Turn lease is keyed by (routing key, run generation) so this unwind can only free
# the lease its own turn acquired, never a newer turn's.
self._release_turn_lease(_quick_key, _run_generation)
def _restore_pending_one_turn_model_override(self, session_key: str, run_generation: int | None = None) -> None:
"""Restore the per-session model override captured by ``/model --once`` or ``/moa``.
With ``run_generation`` (the turn finalizer) the restore happens only while that generation
is still current; a stop/reset/eviction has already settled the snapshot itself (see
``_invalidate_session_run_generation``), so the displaced finalizer finds nothing to do.
Without it (the settlement paths) the restore is unconditional."""
if not session_key:
return
try:
_otr_state = self._peek_session_state(session_key)
if _otr_state is None or not _otr_state.conversation.one_turn_restore:
return
if run_generation is not None and not self._is_session_run_current(session_key, run_generation):
return
snapshot = _otr_state.conversation.one_turn_restore
_otr_state.conversation.one_turn_restore = None
self._restore_session_model_override(session_key, snapshot)
except Exception:
logger.debug("Failed to restore one-turn model override", exc_info=True)
def _prefix_inbound_sender_context(self, event: MessageEvent, source: SessionSource, message_text: str) -> str:
"""Attribute the sender in shared multi-user sessions and prepend history-backfill channel context."""
_is_shared_multi_user = is_shared_multi_user_session(
source, group_sessions_per_user=getattr(self.config, "group_sessions_per_user", True),
thread_sessions_per_user=getattr(self.config, "thread_sessions_per_user", False),
)
if _is_shared_multi_user and source.user_name:
# Display names are attacker-influenceable: neutralize newlines/control chars or a
# hostile name masquerades as a fake markdown section (mirrors build_session_context_prompt).
_safe_user_name = neutralize_untrusted_inline_text(source.user_name)
# Slack: expose the CURRENT speaker's verifiable `<@U...>` id so "mention me again" has a
# trusted target (display names are ambiguous). user_id comes from the envelope, not user-editable.
# See #17916.
if source.platform == Platform.SLACK and source.user_id:
_safe_user_name = f"{_safe_user_name} | Slack user <@{source.user_id}>"
message_text = f"[{_safe_user_name}] {message_text}"
# After the sender-prefix so the prefix applies only to the trigger message, not the backfill.
if getattr(event, "channel_context", None):
message_text = f"{event.channel_context}\n\n[New message]\n{message_text}"
return message_text
@staticmethod
def _classify_inbound_media(
event: MessageEvent, pending_stt_prepared: bool
) -> tuple[list, list, list, list]:
"""Split ``event.media_urls`` into (image, STT-voice, audio-file, video) paths. Per-attachment
MIME wins over the message-level type (a document sent alongside an image must not be routed
as an image). MessageType.AUDIO / mixed DOCUMENT audio is a file attachment, never STT."""
from gateway.run import _event_media_is_audio, _event_media_is_image, _event_media_is_stt_input
image_paths, audio_paths, audio_file_paths, video_paths = [], [], [], []
for i, path in enumerate(event.media_urls or []):
mtype = event.media_types[i] if i < len(event.media_types) else ""
if _event_media_is_image(event, i):
image_paths.append(path)
if _event_media_is_audio(event, i):
if event.message_type in {MessageType.AUDIO, MessageType.DOCUMENT}:
audio_file_paths.append(path)
elif not pending_stt_prepared and _event_media_is_stt_input(event, i):
audio_paths.append(path)
if mtype.startswith("video/") or (not mtype and event.message_type == MessageType.VIDEO):
video_paths.append(path)
return image_paths, audio_paths, audio_file_paths, video_paths
async def _enrich_inbound_images(
self, source: SessionSource, session_key: str, message_text: str, image_paths: list[str]
) -> str:
"""Route images natively (attach pixels at run_conversation) or pre-analyze them into text."""
# See agent/image_routing.py. Offloaded to a thread: the decision does blocking network I/O
# (models.dev fetch on cache miss, Ollama /api/show probe) that would stall the event loop.
_img_mode = await asyncio.to_thread(
self._decide_image_input_mode, source=source, session_key=session_key,
)
if _img_mode == "native":
self._session_state(session_key).persistent.native_image_paths = list(image_paths)
logger.info(
"Image routing: native (model supports vision). %d image(s) will be attached inline.",
len(image_paths),
)
return message_text
logger.info(
"Image routing: text (mode=%s). Pre-analyzing %d image(s) via vision_analyze.",
_img_mode, len(image_paths),
)
# Vision enrichment runs before AIAgent.run_conversation(), so bind this session's resolved
# runtime explicitly rather than consulting process-global compatibility mirrors.
vision_runtime = None
try:
turn_model, runtime_kwargs = self._resolve_session_agent_runtime(
source=source, session_key=session_key,
)
vision_runtime = {**(runtime_kwargs or {}), "model": turn_model}
except Exception:
logger.debug("vision enrichment: session runtime resolution failed", exc_info=True)
from agent.auxiliary_client import scoped_runtime_main
with scoped_runtime_main(vision_runtime):
return await self._enrich_message_with_vision(message_text, image_paths)
async def _echo_stt_transcripts(
self, adapter, source: SessionSource, transcripts: list[str], *, metadata=None, log_context: str = "Transcript"
) -> None:
"""Send each transcript back as ``🎙️ "…"`` (best-effort; failures are logged, never raised)."""
for tx in transcripts:
try:
await adapter.send(source.chat_id, t("gateway.voice.transcript_echo_short", text=tx), metadata=metadata)
except Exception as echo_exc:
logger.debug("%s echo failed (non-fatal): %s", log_context, echo_exc)
async def _enrich_inbound_voice(
self, event: MessageEvent, source: SessionSource, message_text: str, audio_paths: list[str]
) -> str:
message_text, _successful_transcripts = await self._enrich_message_with_transcription(
message_text, audio_paths,
)
# Echo each successful transcript back immediately when configured so users can verify STT
# quality in real time. On transcription failure do NOT send a hardcoded notice: that
# bypassed the LLM and produced two replies; enrichment leaves one neutral marker instead.
if _successful_transcripts and self._should_echo_stt_transcripts():
_echo_adapter = self._delivery_adapter_for(source)
if _echo_adapter:
_echo_meta = self._thread_metadata_for_source(source, self._reply_anchor_for_event(event))
await self._echo_stt_transcripts(_echo_adapter, source, _successful_transcripts, metadata=_echo_meta)
return message_text
@staticmethod
def _inbound_attachment_display_name(path: str, original_name: str = "") -> tuple[str, str]:
"""``(display_name, agent_visible_path)``. The display name is the adapter-supplied
original name when known (``MessageEvent.media_filenames``), else parsed from the native
cache filename ``<id>_<id>_<original>``. A relay temp file (``relay_media_<random>``)
carries no name, so it is labelled unknown rather than shown as the random basename.
The path is translated to the in-container mount under a Docker backend."""
from tools.credential_files import to_agent_visible_cache_path
basename = os.path.basename(path)
name = clean_attachment_filename(original_name)
if not name and basename.startswith(_RELAY_MEDIA_PREFIX):
return _UNKNOWN_ATTACHMENT_NAME, to_agent_visible_cache_path(path)
if not name:
parts = basename.split("_", 2)
name = parts[2] if len(parts) >= 3 else basename
return re.sub(r'[^\w.\- ]', '_', name), to_agent_visible_cache_path(path)
@staticmethod
def _inbound_original_names(event: MessageEvent) -> dict[str, str]:
"""``{path: original_name}`` for the attachments whose original name the adapter kept."""
names = getattr(event, "media_filenames", None) or []
return {p: n for p, n in zip(event.media_urls or [], names) if n}
@classmethod
def _prepend_inbound_media_file_notes(
cls, message_text: str, audio_file_paths: list[str], video_paths: list[str],
original_names: Optional[dict[str, str]] = None,
) -> str:
"""Prepend a path-pointing note per audio-file / video attachment (content is not inlined)."""
names = original_names or {}
for kind, noun, verb, tool, paths in (
("an audio file attachment", "audio", "transcribe or process", "a transcription or media tool", audio_file_paths),
("a video attachment", "video", "inspect or process", "a video analysis or media tool", video_paths),
):
for _path in paths:
_display, _agent_path = cls._inbound_attachment_display_name(_path, names.get(_path, ""))
message_text = (
f"[The user sent {kind}: '{_display}'. "
f"It is saved at: {_agent_path}. "
f"Its content is not inlined here. If the user's request involves "
f"what the {noun} contains, {verb} it yourself — for "
f"example by passing the path to {tool} — "
f"instead of asking the user to describe it. Only ask what to do "
f"with it if their intent is genuinely unclear.]"
f"\n\n{message_text}"
)
return message_text
@classmethod
def _prepend_inbound_document_notes(cls, event: MessageEvent, message_text: str) -> str:
"""Prepend a context note per non-media attachment (anything not routed as image/audio/video)."""
from gateway.run import (
_build_document_context_note, _event_media_is_audio, _event_media_is_image,
_event_media_is_video,
)
if not event.media_urls:
return message_text
import mimetypes as _mimetypes
_TEXT_EXTENSIONS = {".txt", ".md", ".csv", ".log", ".json", ".xml", ".yaml", ".yml", ".toml", ".ini", ".cfg"}
inline_flags = getattr(event, "media_text_inlined", None) or []
names = getattr(event, "media_filenames", None) or []
for i, path in enumerate(event.media_urls):
# A document mixed into a PHOTO/VOICE message (message-level type != DOCUMENT) still
# reaches the agent; only genuine non-media files get a note.
if any(f(event, i) for f in (_event_media_is_image, _event_media_is_audio, _event_media_is_video)):
continue
mtype = event.media_types[i] if i < len(event.media_types) else ""
if mtype in {"", "application/octet-stream"}:
_is_text = os.path.splitext(path)[1].lower() in _TEXT_EXTENSIONS
mtype = "text/plain" if _is_text else (_mimetypes.guess_type(path)[0] or "application/octet-stream")
# Every accepted file gets a note — a non-text/non-application MIME (font/*, model/*)
# must still tell the agent the file exists.
display_name, agent_path = cls._inbound_attachment_display_name(
path, names[i] if i < len(names) else "")
inline_flag = inline_flags[i] if i < len(inline_flags) else None
context_note = _build_document_context_note(
display_name, agent_path, mtype, content_inlined=inline_flag is not False,
)
message_text = f"{context_note}\n\n{message_text}"
return message_text
@staticmethod
def _prepend_inbound_reply_context(event: MessageEvent, source: SessionSource, message_text: str) -> str:
"""Prepend the reply-to pointer, then the Discord triggering-message note (outermost)."""
if getattr(event, "reply_to_text", None) and event.reply_to_message_id:
# Always inject the reply-to pointer even when the quoted text is already in history:
# it's disambiguation (*which* prior message), not deduplication.
# Adapters resolve the original message (or the user's native partial quote).
# A preview here silently loses later list items and code; keep that context intact.
reply_text = event.reply_to_text
_who = " your previous message" if getattr(event, "reply_to_is_own_message", False) else ""
message_text = f'[Replying to{_who}: "{reply_text}"]\n\n{message_text}'
# Discord: the triggering message id goes on the per-turn user message, never the cached
# system prompt — it changes every turn and would bust the agent-cache signature. It is
# the OUTERMOST prefix so strip_discord_triggering_note can peel exactly it off the
# persisted transcript row without touching the reply pointer.
if (
source is not None
and getattr(source, "platform", None) == Platform.DISCORD
and getattr(event, "message_id", None)
):
from gateway.session import _discord_tools_loaded as _disc_tools_loaded
if _disc_tools_loaded():
message_text = f"{discord_triggering_note(event.message_id)}\n\n{message_text}"
return message_text
async def _inbound_model_context_length(self, source: SessionSource, session_key: str) -> int:
"""Context length of the model this turn runs on. A global ``model.context_length`` pin
belongs to the configured model, not a /model or channel override; custom-provider limits win."""
from gateway.run import _load_gateway_config
from agent.model_metadata import get_model_context_length_async
_msg_config_ctx = None
_msg_cfg = None
_msg_model_cfg = {}
_msg_custom_providers = []
with suppress(Exception):
_msg_cfg = _load_gateway_config()
_msg_model_cfg = _msg_cfg.get("model", {})
if isinstance(_msg_model_cfg, dict):
_msg_raw_ctx = _msg_model_cfg.get("context_length")
if _msg_raw_ctx is not None:
_msg_config_ctx = int(_msg_raw_ctx)
try:
from hermes_cli.config import get_compatible_custom_providers
_msg_custom_providers = get_compatible_custom_providers(_msg_cfg)
except Exception:
_msg_custom_providers = _msg_cfg.get("custom_providers") or []
# GatewayRunner has no self._model/self._base_url; resolve the session's actual runtime.
_msg_model, _msg_runtime = self._resolve_session_agent_runtime(
source=source, session_key=session_key, user_config=_msg_cfg,
)
_msg_base_url = _msg_runtime.get("base_url") or ""
if isinstance(_msg_model_cfg, dict):
_msg_configured_model = _msg_model_cfg.get("default") or _msg_model_cfg.get("model")
else:
_msg_configured_model = _msg_model_cfg # (no dict → no pin was read; ctx is already None)
if _msg_model != _msg_configured_model:
_msg_config_ctx = None
if _msg_config_ctx is not None:
try:
from hermes_cli.route_identity import should_clear_context_pin_async
if await should_clear_context_pin_async(
None, None, # model match already checked above
_msg_model_cfg.get("base_url"), _msg_base_url,
_msg_model_cfg.get("provider"), _msg_runtime.get("provider"),
):
_msg_config_ctx = None
except Exception:
_msg_config_ctx = None
if _msg_custom_providers and _msg_base_url:
with suppress(Exception):
from hermes_cli.config import get_custom_provider_context_length
_msg_config_ctx = get_custom_provider_context_length(
model=_msg_model, base_url=_msg_base_url, custom_providers=_msg_custom_providers,
) or _msg_config_ctx
return await get_model_context_length_async(
_msg_model, base_url=_msg_base_url, api_key=_msg_runtime.get("api_key") or "",
config_context_length=_msg_config_ctx, provider=_msg_runtime.get("provider") or "",
custom_providers=_msg_custom_providers,
)
async def _expand_inbound_context_references(
self, source: SessionSource, session_key: str, message_text: str
) -> Optional[str]:
"""Expand ``@`` context references; returns None when the injection was refused (user notified)."""
from gateway.session_context_refs import inbound_references
expanded, refusal = await inbound_references(self, source, session_key, message_text)
if refusal is None:
return expanded
_adapter = self._delivery_adapter_for(source)
if _adapter:
await _adapter.send(source.chat_id, refusal)
return None
async def _prepare_inbound_message_text(
self, *, event: MessageEvent, source: SessionSource, history: list[dict[str, Any]],
session_key: Optional[str] = None,
) -> Optional[str]:
"""Prepare inbound event text for the agent. Shared by the normal inbound and queued
follow-up paths so attribution, image enrichment, STT, document notes, reply context and
@ references behave the same. Side effect: buffers per-session native image paths when the
model supports native vision; the caller consumes that buffer at ``run_conversation``."""
rehome_inbound_media(event) # before any consumer (vision, STT, document notes) reads media_urls
_pending_stt_prepared = hasattr(event, "_gateway_pending_stt_text")
message_text = (event._gateway_pending_stt_text if _pending_stt_prepared else event.text) or ""
# Prefer the caller's resolved session key so this write key matches the consume key at the
# run_conversation site; derive it here only for tests and legacy standalone callers.
session_key = session_key or self._session_key_for_source(source)
# Reset only this session's per-call buffer; other sessions may be concurrently preparing.
self._consume_pending_native_image_paths(session_key)
message_text = self._prefix_inbound_sender_context(event, source, message_text)
image_paths, audio_paths, audio_file_paths, video_paths = self._classify_inbound_media(event, _pending_stt_prepared)
if image_paths:
message_text = await self._enrich_inbound_images(source, session_key, message_text, image_paths)
if audio_paths:
message_text = await self._enrich_inbound_voice(event, source, message_text, audio_paths)
message_text = self._prepend_inbound_media_file_notes(
message_text, audio_file_paths, video_paths, self._inbound_original_names(event))
message_text = self._prepend_inbound_document_notes(event, message_text)
from gateway.session_context_refs import turn_references
message_text = await turn_references(self, event, source, session_key, message_text)
if message_text is None:
return None
# After expansion: the quoted reply is someone else's text and stays literal — an
# ``@file:`` inside it must never read a local file on the replier's behalf.
return self._prepend_inbound_reply_context(event, source, message_text)
async def _prepare_profile_scoped_inbound_message_text(
self, *, event: MessageEvent, source: SessionSource, history: list[dict[str, Any]],
session_key: Optional[str] = None,
) -> Optional[str]:
"""Run inbound preprocessing under the routed profile when multiplexed."""
from gateway.run import _async_profile_runtime_scope
kwargs = dict(event=event, source=source, history=history, session_key=session_key)
if getattr(getattr(self, "config", None), "multiplex_profiles", False):
async with _async_profile_runtime_scope(self._resolve_profile_home_for_source(source)):
return await self._prepare_inbound_message_text(**kwargs)
return await self._prepare_inbound_message_text(**kwargs)
async def _prepare_clarify_reply_text(self, event) -> str:
"""Return raw text or successful voice transcripts for a clarify reply."""
if not self._pending_event_audio_paths(event):
return (event.text or "").strip()
_, successful_transcripts = await self._transcribe_pending_audio_event_once(event, "")
return "\n\n".join(t.strip() for t in successful_transcripts if t.strip())
def _consume_pending_native_image_paths(self, session_key: str) -> list[str]:
state = self._peek_session_state(session_key)
paths = list(state.persistent.native_image_paths or []) if state is not None else []
if paths:
state.persistent.native_image_paths = []
return paths
async def _mark_durable_active_turn(self, event: MessageEvent, session_key: str) -> bool:
"""Persist the exact resolved routing key for this running turn."""
try:
token = await self.async_session_store.mark_turn_active(session_key)
except Exception as exc:
logger.warning("Could not persist active-turn marker for %s: %s", session_key, exc)
return False
if not token:
return False
# Private event attributes are process-local ownership state: keep the token out of public
# metadata, transcripts, and platform payloads.
event._gateway_active_turn_session_key = session_key
event._gateway_active_turn_token = token
return True
async def _clear_durable_active_turn(self, event: MessageEvent) -> bool:
"""Best-effort CAS clear of the marker owned by *event* (3 attempts; never blocks agent/lease
release — a stale marker is bounded by the agent timeout and clean-start discard)."""
session_key = getattr(event, "_gateway_active_turn_session_key", None)
token = getattr(event, "_gateway_active_turn_token", None)
try:
if not session_key or not token:
return False
last_error: Optional[Exception] = None
for attempt in range(1, 4):
try:
return bool(await self.async_session_store.clear_turn_active(session_key, token))
except Exception as exc:
last_error = exc
if attempt < 3:
logger.debug(
"Retrying active-turn marker cleanup for %s (%d/3): %s",
session_key, attempt, exc,
)
logger.warning(
"Could not clear active-turn marker for %s after 3 attempts: %s", session_key, last_error,
)
return False
finally:
for attr in ("_gateway_active_turn_session_key", "_gateway_active_turn_token"):
with suppress(AttributeError):
delattr(event, attr)
def _decide_image_input_mode(
self, *, source: Optional[SessionSource] = None, session_key: Optional[str] = None,
user_config: Optional[dict] = None, provider: Optional[str] = None,
model: Optional[str] = None,
) -> str:
"""Resolve image-input routing (``"native"`` / ``"text"``) for the effective model this turn
(see agent/image_routing.py). Sessions can carry /model overrides and this runs before AIAgent
sets the auxiliary_client runtime globals, so resolve the per-session runtime bundle the
upcoming turn will use, not just the persisted default."""
try:
from agent.image_routing import decide_image_input_mode
from agent.auxiliary_client import _read_main_model, _read_main_provider
from hermes_cli.config import load_config
cfg = user_config if isinstance(user_config, dict) else load_config()
resolved_provider = (provider or "").strip()
resolved_model = (model or "").strip()
resolved_requested_provider = ""
if (not resolved_provider or not resolved_model) and (source is not None or session_key):
try:
turn_model, runtime_kwargs = self._resolve_session_agent_runtime(
source=source, session_key=session_key, user_config=cfg,
)
rk = runtime_kwargs if isinstance(runtime_kwargs, dict) else {}
if not resolved_model and isinstance(turn_model, str):
resolved_model = turn_model.strip()
if not resolved_provider and isinstance(rk.get("provider"), str):
resolved_provider = rk["provider"].strip()
if isinstance(rk.get("requested_provider"), str):
resolved_requested_provider = rk["requested_provider"].strip()
except Exception as exc:
logger.debug(
"image_routing: session runtime resolution failed, falling back to config — %s",
exc,
)
return decide_image_input_mode(
resolved_provider or _read_main_provider(), resolved_model or _read_main_model(),
cfg, requested_provider=resolved_requested_provider,
)
except Exception as exc:
logger.debug("image_routing: decision failed, falling back to text — %s", exc)
return "text"
async def _enrich_message_with_vision(self, user_text: str, image_paths: list[str]) -> str:
"""Auto-analyze user-attached images with the vision tool and prepend the descriptions.
Description *and* local cache path are injected so the model understands the image without
a tool call and can re-examine it with vision_analyze."""
from tools.vision_tools import vision_analyze_tool
from agent.memory_context import sanitize_context
analysis_prompt = (
"Concisely describe this image in 2-4 sentences "
"(~200 Chinese characters or ~150 English words). "
"Cover the main subject, key visible text/data/code, and overall context. "
"If it is a chart, diagram, or scientific figure, include the important "
"labels, legend, and key values. Skip decorative details."
)
enriched_parts = []
for path in image_paths:
try:
logger.debug("Auto-analyzing user image: %s", path)
result = json.loads(await vision_analyze_tool(image_url=path, user_prompt=analysis_prompt))
if result.get("success"):
description = sanitize_context(result.get("analysis", ""))
note = (
f"[The user sent an image~ Here's what I can see:\n{description}]\n"
f"[If you need a closer look, use vision_analyze with "
f"image_url: {path} ~]"
)
else:
note = (
"[The user sent an image but I couldn't quite see it "
"this time (>_<) You can try looking at it yourself "
f"with vision_analyze using image_url: {path}]"
)
except Exception as e:
logger.error("Vision auto-analysis error: %s", e)
note = (
f"[The user sent an image but something went wrong when I "
f"tried to look at it~ You can try examining it yourself "
f"with vision_analyze using image_url: {path}]"
)
enriched_parts.append(note)
if not enriched_parts:
return user_text
prefix = "\n\n".join(enriched_parts)
return f"{prefix}\n\n{user_text}" if user_text else prefix