run_inbound.py 107 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888
  1. """Inbound message pipeline (_handle_message, text/media preparation, durable-turn markers, plugin injection) for GatewayRunner.
  2. Split out of ``gateway/run.py``; bound onto ``GatewayRunner`` via the MRO.
  3. ``gateway.run`` internals are imported lazily inside method bodies (import cycle),
  4. so ``patch("gateway.run.X")`` keeps intercepting them at call time.
  5. """
  6. from __future__ import annotations
  7. import logging
  8. from typing import TYPE_CHECKING
  9. import asyncio
  10. import concurrent.futures
  11. import dataclasses
  12. import json
  13. import os
  14. import re
  15. import time
  16. from contextlib import suppress
  17. from pathlib import Path
  18. from agent.i18n import t
  19. from gateway.config import Platform
  20. from gateway.platforms.base import EphemeralReply
  21. from gateway.platforms.event import MessageEvent, MessageType, clean_attachment_filename
  22. from gateway.run_busy import approval_input_words
  23. from gateway.run_inbound_media import rehome_inbound_media
  24. from gateway.run_inbound_hooks import GatewayInboundHooksMixin
  25. from gateway.run_inbound_transcription import GatewayInboundTranscriptionMixin
  26. from gateway.run_plugin_injection import GatewayPluginInjectionMixin
  27. from gateway.run_inbound_unauthorized import (
  28. UnauthorizedOwnerNotifier, pairing_code_reply, pairing_profile_arg, pairing_rate_limited_reply,
  29. unauthorized_owner_hint,
  30. )
  31. from gateway.session import (
  32. SessionSource, build_session_context, is_shared_multi_user_session,
  33. neutralize_untrusted_inline_text,
  34. )
  35. from gateway.turn_lease import TurnLeaseTimeoutError
  36. from hermes_cli.observability.shared_metrics_busy import (
  37. note_busy_admitting, note_busy_outcome, settle_busy_arrival, stamp_busy_arrival)
  38. from typing import Any, Dict, List, Optional, Tuple
  39. if TYPE_CHECKING: # string annotations only; never imported at runtime (cycle)
  40. from gateway.run import GatewayRunner
  41. from gateway.run_turn_runner import TurnRunner
  42. # Log-record parity with the origin module.
  43. logger = logging.getLogger("gateway.run")
  44. # ``RelayMediaClient.download`` temp-file prefix: the rest of such a basename is random, not a name.
  45. _RELAY_MEDIA_PREFIX = "relay_media_"
  46. _UNKNOWN_ATTACHMENT_NAME = "(original filename unknown)"
  47. def discord_triggering_note(message_id: Any) -> str:
  48. """Model-facing routing note for a Discord turn (rides the API-bound user message only)."""
  49. return (
  50. f"[Triggering message id: `{message_id}` — use as `message_id` for reply/react/pin "
  51. f"via the discord tools.]"
  52. )
  53. def strip_discord_triggering_note(event: Any, message_text: Any) -> Any:
  54. """Authored text for the durable user row: peel off exactly the note
  55. ``_prepend_inbound_reply_context`` added for THIS event, if present. The note is a
  56. model instruction, not something the user wrote — persisted as ``content`` it renders
  57. verbatim in every transcript surface and pollutes FTS/memory (#71304, #114719). It
  58. keeps riding ``message_text`` (and the replay-only ``api_content`` sidecar)."""
  59. message_id = getattr(event, "message_id", None)
  60. if not message_id or not isinstance(message_text, str):
  61. return message_text
  62. prefix = f"{discord_triggering_note(message_id)}\n\n"
  63. return message_text.removeprefix(prefix)
  64. class GatewayInboundMixin(GatewayInboundHooksMixin, GatewayInboundTranscriptionMixin, GatewayPluginInjectionMixin):
  65. """Inbound message pipeline (_handle_message, text/media preparation, durable-turn markers, plugin injection) for GatewayRunner."""
  66. async def _hm_offer_pairing_code(self, source: SessionSource) -> None:
  67. """DM an unauthorized sender a pairing code (rate-limited; groups never reach here)."""
  68. platform_name = source.platform.value if source.platform else "unknown"
  69. pairing_store = self._pairing_store_for(source)
  70. if pairing_store is None:
  71. logger.error("Cannot offer pairing code on %s: no pairing store", platform_name)
  72. return
  73. # Rate-limit ALL pairing responses (code or rejection) so a burst of DMs doesn't spam.
  74. if pairing_store._is_rate_limited(platform_name, source.user_id):
  75. return
  76. # Off the event loop: the store edit waits on a cross-process lock (dashboard, CLI).
  77. try:
  78. code = await asyncio.to_thread(
  79. pairing_store.generate_code, platform_name, source.user_id, source.user_name or "",
  80. )
  81. except (OSError, TimeoutError):
  82. logger.warning("Could not record a pairing code on %s", platform_name, exc_info=True)
  83. return
  84. adapter = self._delivery_adapter_for(source)
  85. if code:
  86. reply = pairing_code_reply(platform_name, code, pairing_profile_arg(pairing_store))
  87. else:
  88. reply = pairing_rate_limited_reply()
  89. if adapter:
  90. await adapter.send(source.chat_id, reply)
  91. if not code:
  92. # Record rate limit so subsequent messages are silently ignored
  93. pairing_store._record_rate_limit(platform_name, source.user_id)
  94. async def _hm_send_unauthorized_decline(self, source: SessionSource) -> None:
  95. """``decline`` behavior: one short refusal per sender per DECLINE_DEDUPE_SECONDS, then silence
  96. (#88028). The stamp is written BEFORE the send so a delivery
  97. hiccup cannot become a decline storm; without a store there is no dedupe state → stay silent."""
  98. from gateway.config import DEFAULT_UNAUTHORIZED_DM_DECLINE_MESSAGE
  99. platform_name = source.platform.value if source.platform else "unknown"
  100. pairing_store = self._pairing_store_for(source)
  101. if pairing_store is None or pairing_store.has_recent_decline(platform_name, source.user_id):
  102. return
  103. # Off the event loop (the stamp waits on a cross-process lock); no stamp → no dedupe → silent.
  104. try:
  105. await asyncio.to_thread(pairing_store.record_decline, platform_name, source.user_id)
  106. except (OSError, TimeoutError):
  107. logger.warning("Could not record an unauthorized-DM decline on %s", platform_name, exc_info=True)
  108. return
  109. adapter = self._delivery_adapter_for(source)
  110. if not adapter:
  111. return
  112. config = getattr(self, "config", None)
  113. text = str(getattr(config, "unauthorized_dm_decline_message", "") or "").strip()
  114. try:
  115. await adapter.send(source.chat_id, text or DEFAULT_UNAUTHORIZED_DM_DECLINE_MESSAGE)
  116. except Exception:
  117. logger.warning("Failed to deliver unauthorized-DM decline on %s", platform_name, exc_info=True)
  118. async def _hm_report_ignored_dm(self, source: SessionSource) -> None:
  119. """Unauthorized DM under behaviour ``ignore``: nothing goes to the sender. The owner gets the
  120. sender's ID and the allowlist fix in the WARNING log and, once per sender, in the home channel."""
  121. from hermes_constants import display_hermes_home
  122. platform_name = source.platform.value if source.platform else "unknown"
  123. hint = unauthorized_owner_hint(
  124. platform_name, source.user_id, source.user_name or "", hermes_home=display_hermes_home(),
  125. )
  126. logger.warning("Unauthorized user (ignored): %s", hint)
  127. notifier = getattr(self, "_unauthorized_owner_notifier", None)
  128. if notifier is None:
  129. notifier = self._unauthorized_owner_notifier = UnauthorizedOwnerNotifier()
  130. if notifier.first_time(platform_name, source.user_id) and getattr(self, "config", None) is not None:
  131. await notifier.notify(self, source, hint)
  132. async def _hm_admit_event(
  133. self, event: MessageEvent
  134. ) -> Optional[tuple[MessageEvent, SessionSource, bool]]:
  135. """Ingress gates for ``_handle_message``; None when dropped, else ``(event, source, is_internal)``
  136. (the ``pre_gateway_dispatch`` hook may have rewritten ``event``)."""
  137. from gateway.run import _is_slack_ignored_channel
  138. source = event.source
  139. # getattr(self, ...) throughout: bare test runners build GatewayRunner via object.__new__.
  140. _config = getattr(self, "config", None)
  141. # 🔴 Cross-session leak guard: this per-message task was create_task()'d with a copy of the
  142. # spawning context, which may carry ANOTHER message's HERMES_SESSION_* ContextVars; until
  143. # _set_session_env binds ours a subprocess would read the foreign identity. Reset to _UNSET.
  144. try:
  145. from gateway.session_context import reset_session_vars
  146. reset_session_vars()
  147. except Exception:
  148. logger.debug("reset_session_vars failed at handler entry", exc_info=True)
  149. # Identity FIRST. Most adapters canonicalize at their own ingress; internal/voice paths
  150. # construct SessionSource directly, so this is the shared fail-closed gate. Strict boolean
  151. # marker: require the literal True so duck-typed test/internal sources with dynamic
  152. # attributes are not mistaken for a rejection.
  153. if getattr(_config, "multiplex_profiles", False):
  154. self._canonicalize(source)
  155. if getattr(source, "profile_route_rejected", False) is True:
  156. from gateway.parked_route_refusal import drop_rejected_route
  157. _intake = None
  158. with suppress(Exception):
  159. _intake = self._intake_adapter_for(source)
  160. drop_rejected_route(_intake, source) # a parked target is also refused to the sender
  161. return None
  162. is_internal = bool(getattr(event, "internal", False)) # e.g. background-process notifications
  163. # Ignored-channel guard runs FIRST — before startup-restore queueing, plugin hooks, auth,
  164. # and session setup — so an ignored channel can never reach pairing/auth/session state.
  165. _chat_id = getattr(source, "chat_id", None)
  166. if not is_internal and getattr(source, "platform", None) == Platform.SLACK:
  167. # The routed adapter's extra carries a secondary profile's own list; ``_config`` is the default's.
  168. _slack_adapter = None
  169. with suppress(Exception):
  170. _slack_adapter = self._intake_adapter_for(source)
  171. if (
  172. # See #51899.
  173. not is_internal
  174. and getattr(source, "platform", None) == Platform.SLACK
  175. and _is_slack_ignored_channel(_config, _chat_id, _slack_adapter)
  176. ):
  177. logger.info("Dropping Slack message from configured ignored channel %s", _chat_id)
  178. return None
  179. # An admission the authority is executing is already ordered by its durable FIFO; parking it
  180. # here would settle the row with no turn and replay the input outside it (GW-2).
  181. from gateway.session_ingress import executing_admission
  182. if (
  183. getattr(self, "_startup_restore_in_progress", False)
  184. and not is_internal
  185. and not getattr(event, "_hermes_startup_restore_replay", False)
  186. and not executing_admission.get()
  187. ):
  188. self._queue_startup_restore_event(event)
  189. return None
  190. if is_internal:
  191. return event, source, True
  192. if getattr(event, "_fifo_only", False): # a slash command's queued turn: its command passed ingress
  193. return event, source, False
  194. # scale-to-zero: only real user-originated inbound stamps the last-inbound clock;
  195. # counting internal/system events would keep a genuinely idle gateway awake.
  196. self._scale_to_zero_note_real_inbound()
  197. event = await self._hm_pre_gateway_dispatch_hook(event, source)
  198. if event is None:
  199. return None
  200. source = event.source
  201. if not self._is_user_authorized_for_source(source):
  202. if source.user_id is None:
  203. # No user identity (Telegram service messages, channel forwards, anonymous admin
  204. # posts, sender_chat): can't be paired but may be authorized via a chat allowlist.
  205. logger.debug("Ignoring message with no user_id from %s", source.platform.value)
  206. return None
  207. # DMs get a pairing code or a one-time decline, groups are ignored. A bot cannot pair, and
  208. # answering one mid-cooldown is outbound traffic.
  209. pairable_dm = source.chat_type == "dm" and not getattr(source, "is_bot", False)
  210. behavior = self._get_unauthorized_dm_behavior(source.platform, profile=source.profile) if pairable_dm else None
  211. if behavior == "pair":
  212. logger.warning("Unauthorized user: %s (%s) on %s", source.user_id, source.user_name, source.platform.value)
  213. await self._hm_offer_pairing_code(source)
  214. elif behavior == "decline":
  215. logger.warning("Unauthorized user: %s (%s) on %s", source.user_id, source.user_name, source.platform.value)
  216. await self._hm_send_unauthorized_decline(source)
  217. elif pairable_dm:
  218. await self._hm_report_ignored_dm(source)
  219. else:
  220. logger.warning("Unauthorized user: %s (%s) on %s", source.user_id, source.user_name, source.platform.value)
  221. return None
  222. # The busy path charged this event on arrival; a drained follow-up must not pay twice.
  223. if not getattr(event, "_bot_loop_admitted", False) and not (
  224. self._admit_bot_message_for_source(source) and self._admit_bot_chain(event)):
  225. return None
  226. return event, source, False
  227. def _hm_estop_turn_allowed(self, event: MessageEvent, source: SessionSource) -> bool:
  228. """Whether a turn may bypass the global emergency stop: pause blocks NEW agent turns, never
  229. running work or control traffic — recognized slash commands (incl. /pause off, the in-band
  230. resume) and replies owned by in-flight work (pending update prompt, running session,
  231. pending slash-confirm, dangerous-command approval) all pass through."""
  232. with suppress(Exception):
  233. _estop_cmd = event.get_command()
  234. if _estop_cmd:
  235. from hermes_cli.commands import resolve_command as _resolve_estop_cmd
  236. if _resolve_estop_cmd(_estop_cmd) is not None:
  237. return True
  238. with suppress(Exception):
  239. _estop_key = self._session_key_for_source(source)
  240. _estop_state = self._peek_session_state(_estop_key)
  241. if _estop_state is not None and _estop_state.persistent.update_prompt_pending:
  242. return True
  243. # A running session covers steering plus pending clarify / tool approvals it holds.
  244. if self._is_session_running(_estop_key):
  245. return True
  246. from tools import slash_confirm as _estop_confirm_mod
  247. if _estop_confirm_mod.get_pending(_estop_key):
  248. return True
  249. from tools.approval import has_blocking_approval as _estop_has_approval
  250. if _estop_has_approval(_estop_key):
  251. return True
  252. return False
  253. def _hm_estop_gate(
  254. self, event: MessageEvent, source: SessionSource, is_internal: bool
  255. ) -> Optional[str]:
  256. """Global emergency-stop (`hermes pause`) notice when this turn must be blocked, else None.
  257. Placed after auth so unauthorized senders can't probe pause state. A synthetic heartbeat that
  258. slipped past the poller's pause check gets "" (blocked, nothing sent): nobody typed it, and
  259. settle_heartbeat_attempt leaves its tick due for after resume."""
  260. if is_internal:
  261. return None
  262. try:
  263. from agent.estop import paused_reply as _estop_paused_reply
  264. except ImportError:
  265. return None
  266. _paused_notice = _estop_paused_reply()
  267. if _paused_notice is None or self._hm_estop_turn_allowed(event, source):
  268. return None
  269. if getattr(event, "_heartbeat_session_id", None):
  270. logger.debug("Heartbeat turn dropped by global emergency stop")
  271. return ""
  272. logger.info(
  273. "Gateway turn paused by global emergency stop (platform=%s chat=%s)",
  274. getattr(getattr(source, "platform", None), "value", "unknown"),
  275. getattr(source, "chat_id", None) or "unknown",
  276. )
  277. return _paused_notice
  278. @staticmethod
  279. def _hm_write_update_response(response_text: str) -> Optional[str]:
  280. """Atomically hand *response_text* to the detached update process; returns the OSError str."""
  281. from gateway.run import _hermes_home
  282. response_path = _hermes_home / ".update_response"
  283. try:
  284. tmp = response_path.with_suffix(".tmp")
  285. tmp.write_text(response_text, encoding="utf-8")
  286. tmp.replace(response_path)
  287. (_hermes_home / ".update_prompt.json").unlink(missing_ok=True)
  288. except OSError as e:
  289. return str(e)
  290. return None
  291. def _hm_update_prompt_reply(self, event: MessageEvent, _quick_key: str) -> Optional[str]:
  292. """Consume a reply to a pending ``/update`` prompt (routed to the detached update process via
  293. ``.update_response``); None when nothing was consumed. Recognized slash commands must bypass
  294. this or /new, /help etc. get silently consumed as update answers."""
  295. _up_state = self._peek_session_state(_quick_key)
  296. if _up_state is None or not _up_state.persistent.update_prompt_pending:
  297. return None
  298. # Accept /approve and /deny as shorthand for yes/no
  299. cmd = event.get_command()
  300. _recognized_cmd = None
  301. if cmd in {"approve", "yes"}:
  302. response_text = "y"
  303. elif cmd in {"deny", "no"}:
  304. response_text = "n"
  305. else:
  306. if cmd:
  307. with suppress(Exception):
  308. from hermes_cli.commands import resolve_command as _resolve_update_cmd
  309. _cmd_def = _resolve_update_cmd(cmd)
  310. _recognized_cmd = _cmd_def.name if _cmd_def else None
  311. response_text = "" if _recognized_cmd else (event.text or "").strip()
  312. if response_text:
  313. err = self._hm_write_update_response(response_text)
  314. if err is not None:
  315. logger.warning("Failed to write update response: %s", err)
  316. return t("gateway.update.reply_failed", error=err)
  317. _up_state.persistent.update_prompt_pending = False
  318. label = response_text if len(response_text) <= 20 else response_text[:20] + "…"
  319. return t("gateway.update.reply_sent", label=label)
  320. # Recognized slash command during a pending update prompt: write a blank response so the
  321. # detached update's ``_gateway_prompt`` returns the prompt's default (typically a safe
  322. # "n" / skip) and exits instead of blocking on stdin until the watcher timeout.
  323. if _recognized_cmd:
  324. err = self._hm_write_update_response("")
  325. if err is None:
  326. logger.info(
  327. "Recognized /%s during pending update prompt for %s; "
  328. "cancelled prompt with default and dispatching command",
  329. _recognized_cmd, _quick_key,
  330. )
  331. else:
  332. logger.warning("Failed to write cancel response for pending update prompt: %s", err)
  333. _up_state.persistent.update_prompt_pending = False
  334. return None
  335. async def _hm_clarify_reply(
  336. self, event: MessageEvent, source: SessionSource, _quick_key: str
  337. ) -> Optional[str]:
  338. """Intercept a reply to a pending clarify prompt; None when the message falls through.
  339. Free text answers open-ended/"Other" prompts; "2" answers a multi-choice one. Resolved/retained
  340. replies return "" so adapters don't double-post — the agent produces the next user-facing message."""
  341. try:
  342. from tools import clarify_gateway as _clarify_mod
  343. _pending_clarify = _clarify_mod.get_pending_for_session(_quick_key, include_choice_prompts=True)
  344. except Exception:
  345. return None
  346. if _pending_clarify is None:
  347. return None
  348. _clarify_has_audio = bool(self._pending_event_audio_paths(event))
  349. _raw_clarify_reply = await self._prepare_clarify_reply_text(event)
  350. def _retain(why: str) -> str:
  351. logger.info(
  352. "Gateway retained pending clarify after %s (session=%s, id=%s)",
  353. why, _quick_key, _pending_clarify.clarify_id,
  354. )
  355. return ""
  356. if _clarify_has_audio and not _raw_clarify_reply:
  357. return _retain("voice transcription produced no usable text")
  358. # Slash commands: the user wanted a command, not to answer the clarify. Leave it pending so
  359. # they can retry; on timeout the agent unblocks with an empty response.
  360. if not _raw_clarify_reply or _raw_clarify_reply.startswith("/"):
  361. return None
  362. _text_outcome = _clarify_mod.attempt_text_response_for_session(_quick_key, _raw_clarify_reply)
  363. if _text_outcome == _clarify_mod.TEXT_RESOLVED:
  364. logger.info(
  365. "Gateway intercepted clarify text response (session=%s, id=%s)",
  366. _quick_key, _pending_clarify.clarify_id,
  367. )
  368. # The clarify callback pauses the platform typing/status indicator while waiting so
  369. # Slack users can type; the active agent resumes now, so re-enable its indicator.
  370. _clarify_adapter = self._delivery_adapter_for(source)
  371. if _clarify_adapter:
  372. try:
  373. _clarify_adapter.resume_typing_for_chat(source.chat_id)
  374. except Exception:
  375. logger.debug("Failed to resume typing after clarify response", exc_info=True)
  376. # A typed answer to a native card (numeric pick, or text after "Other") never
  377. # reaches the click handler, so the card would keep its buttons forever.
  378. if callable(getattr(type(_clarify_adapter), "retire_clarify_card", None)):
  379. try:
  380. await _clarify_adapter.retire_clarify_card(
  381. _pending_clarify.clarify_id,
  382. t("gateway.clarify.answered",
  383. response=_raw_clarify_reply if _pending_clarify.response == _clarify_mod.SKIPPED
  384. else _pending_clarify.response or _raw_clarify_reply))
  385. except Exception:
  386. logger.debug("Failed to retire clarify card after typed answer", exc_info=True)
  387. return ""
  388. if _text_outcome == _clarify_mod.TEXT_REJECTED_SELECTION:
  389. # Selection-shaped but invalid (out-of-range number, bad comma-list): keep the clarify
  390. # armed for retry — don't cancel, don't treat as an unrelated follow-up.
  391. return _retain("invalid selection attempt")
  392. if _text_outcome == _clarify_mod.TEXT_REJECTED_PROSE:
  393. # Native-choice prompts reject unmatched prose so it continues through normal busy
  394. # routing. Release this clarify first: redirect() degrades to steer() while tools
  395. # execute, and that steer cannot drain until the clarify tool returns.
  396. if _clarify_mod.resolve_gateway_clarify(_pending_clarify.clarify_id, _clarify_mod.CANCELLED):
  397. # Adapters with a persistent native card (Slack Block Kit) retire it now, before the
  398. # prose is routed, so its buttons stop advertising a dead answer path. The pop inside
  399. # retire_clarify_card runs before its first await, so the agent thread's own expiry
  400. # notice (scheduled once the wait unblocks) finds nothing and stays a no-op.
  401. _clarify_adapter = self._delivery_adapter_for(source)
  402. # Class lookup: a MagicMock adapter must not fabricate the method.
  403. if callable(getattr(type(_clarify_adapter), "retire_clarify_card", None)):
  404. try:
  405. await _clarify_adapter.retire_clarify_card(
  406. _pending_clarify.clarify_id,
  407. t("gateway.clarify.cancelled"))
  408. except Exception:
  409. logger.debug("Failed to retire clarify card after prose cancellation", exc_info=True)
  410. return None
  411. # Reply → choice for a pending slash-confirm prompt; the command spelling wins over the
  412. # bang/slash-stripped free-text spelling.
  413. _SLASH_CONFIRM_CMD_CHOICES = {
  414. "approve": "once", "yes": "once", "ok": "once", "confirm": "once",
  415. "always": "always", "remember": "always",
  416. "cancel": "cancel", "no": "cancel", "deny": "cancel", "nevermind": "cancel",
  417. }
  418. # Free-text spellings: ``approval.inputs.confirm_*`` comma-lists (English ∪ active language).
  419. _SLASH_CONFIRM_TEXT_INPUT_KEYS = (("confirm_once", "once"), ("confirm_always", "always"), ("confirm_cancel", "cancel"))
  420. def _slash_confirm_text_choices(self) -> dict[str, str]:
  421. choices: dict[str, str] = {}
  422. for input_key, choice in self._SLASH_CONFIRM_TEXT_INPUT_KEYS:
  423. for word in approval_input_words(input_key):
  424. choices.setdefault(word, choice)
  425. return choices
  426. async def _hm_slash_confirm_reply(self, event: MessageEvent, _quick_key: str) -> Optional[str]:
  427. """Resolve a reply (/approve, /always, /cancel + aliases) to a pending slash-confirm prompt;
  428. None when it falls through — a stale pending confirm does NOT block other commands. A pending
  429. dangerous-command approval takes precedence: /approve there unblocks the waiting tool thread."""
  430. from tools import slash_confirm as _slash_confirm_mod
  431. _pending_confirm = _slash_confirm_mod.get_pending(_quick_key)
  432. if not _pending_confirm:
  433. return None
  434. with suppress(Exception):
  435. from tools.approval import has_blocking_approval
  436. if has_blocking_approval(_quick_key):
  437. return None
  438. # Accept bang-prefixed replies (`!always`, `!cancel`) verbatim: Slack/Matrix show the `!`
  439. # prefix (typed `/` is blocked in Slack threads) and adapters only rewrite
  440. # `!<known-command>` — confirm keywords aren't commands, so the `!` survives to here.
  441. _norm_reply = (event.text or "").strip().lstrip("!/").lower()
  442. _confirm_choice = (
  443. self._SLASH_CONFIRM_CMD_CHOICES.get(event.get_command())
  444. or self._slash_confirm_text_choices().get(_norm_reply)
  445. )
  446. if _confirm_choice is not None:
  447. _resolved = await _slash_confirm_mod.resolve(
  448. _quick_key, _pending_confirm.get("confirm_id"), _confirm_choice,
  449. )
  450. return _resolved or ""
  451. # Stale pending + unrelated command: the user moved on, so drop the pending state rather
  452. # than let the confirm block normal usage indefinitely.
  453. _slash_confirm_mod.clear_if_stale(_quick_key)
  454. return None
  455. def _hm_evict_idle_stale_agent(self, _quick_key: str) -> None:
  456. """Evict a leaked lock from a hung/crashed handler: only when the agent has been *idle* past
  457. the threshold (active tasks can run for hours), or has no activity tracker and an extreme
  458. wall-clock age. The pending sentinel is never evicted (no get_activity_summary() → idle
  459. reads inf and would race the async setup path)."""
  460. from gateway.run import _AGENT_PENDING_SENTINEL, _float_env
  461. _raw_stale_timeout = _float_env("HERMES_AGENT_TIMEOUT", 1800)
  462. _quick_state = self._peek_session_state(_quick_key)
  463. _stale_ts = _quick_state.turn.started_ts if _quick_state else 0
  464. if _quick_state is None or _quick_state.turn.agent is None or not _stale_ts:
  465. return
  466. _stale_age = time.time() - _stale_ts
  467. _stale_agent = _quick_state.turn.agent
  468. _stale_idle = float("inf") # assume idle if we can't check
  469. _stale_detail = ""
  470. _activity_summary_valid = False
  471. if _stale_agent and hasattr(_stale_agent, "get_activity_summary"):
  472. with suppress(Exception):
  473. _sa = _stale_agent.get_activity_summary()
  474. from gateway.session_stall import resolve_session_idle_seconds_from_activity
  475. _sa_d = _sa if isinstance(_sa, dict) else {}
  476. _resolved_idle = resolve_session_idle_seconds_from_activity(
  477. _sa if isinstance(_sa, dict) else None, now=time.time(),
  478. )
  479. if _resolved_idle is not None:
  480. _stale_idle = _resolved_idle
  481. _activity_summary_valid = True
  482. # Host sleep is not idleness: share the turn poll loop's meter (same event loop).
  483. _awake_idle = getattr(_quick_state.turn.ctx, "awake_idle", None)
  484. if _awake_idle is not None:
  485. _stale_idle = _awake_idle.measure(_stale_idle)
  486. _stale_detail = (
  487. f" | last_activity={_sa_d.get('last_activity_desc', 'unknown')} "
  488. f"({_stale_idle:.0f}s ago) "
  489. f"| iteration={_sa_d.get('api_call_count', 0)}/{_sa_d.get('max_iterations', 0)}"
  490. )
  491. # A valid activity clock is authoritative: total age alone never makes an actively
  492. # progressing turn stale. The emergency wall TTL is only a fallback when the agent cannot
  493. # report usable activity.
  494. _wall_ttl = max(_raw_stale_timeout * 10, 7200) if _raw_stale_timeout > 0 else float("inf")
  495. _should_evict = _stale_agent is not _AGENT_PENDING_SENTINEL and (
  496. (_activity_summary_valid and _raw_stale_timeout > 0 and _stale_idle >= _raw_stale_timeout)
  497. or (not _activity_summary_valid and _stale_age > _wall_ttl)
  498. )
  499. if _should_evict:
  500. logger.warning(
  501. "Evicting stale _running_agents entry for %s "
  502. "(age: %.0fs, idle: %.0fs, timeout: %.0fs)%s",
  503. _quick_key, _stale_age, _stale_idle, _raw_stale_timeout, _stale_detail,
  504. )
  505. self._hm_evict_running_agent(_quick_key, "stale_running_agent_eviction")
  506. def _hm_evict_reaped_agent(self, _quick_key: str) -> None:
  507. """Evict the in-memory turn slot of a session whose durable row was ended while the gateway
  508. lived (``ws_orphan_reap`` / ``agent_close``): otherwise the fast-path queues every next
  509. message into the dead runtime. The cold path re-attaches via ``get_or_create_session``."""
  510. try:
  511. # #99106: durable-reaped guard. This is the live-gateway variant of #54878 and the #632
  512. # detached/ 405 suppressions in production. Evict the stale slot so the next message falls
  513. # through to the cold path and re-attaches or creates a fresh session; /status then correctly
  514. # shows 代理运行中: 否 before the heal and a live turn after.
  515. _reap_store = getattr(self, "session_store", None)
  516. # Public, lock-held accessors: peek_session_id returns a non-str on stubbed stores in
  517. # bare test runners — the isinstance() / ``is True`` gates keep this inert unless a
  518. # real SessionStore answers.
  519. _reap_peek = getattr(_reap_store, "peek_session_id", None)
  520. _is_ended = getattr(_reap_store, "_is_session_ended_in_db", None)
  521. _reap_sid = _reap_peek(_quick_key) if callable(_reap_peek) else None
  522. if isinstance(_reap_sid, str) and _reap_sid and callable(_is_ended) and _is_ended(_reap_sid) is True:
  523. logger.warning(
  524. "Evicting stale _running_agents entry for %s — "
  525. "durable session %s is ended (reaped) in state.db; "
  526. "healing routing on next message (#99106)", _quick_key, _reap_sid,
  527. )
  528. self._hm_evict_running_agent(_quick_key, "reaped_session_eviction")
  529. except Exception:
  530. logger.debug("reaped-session staleness check failed", exc_info=True)
  531. def _hm_evict_running_agent(self, _quick_key: str, reason: str) -> None:
  532. from gateway.run import _INTERRUPT_REASON_EVICTED, _INTERRUPT_TOOL_REASON_EVICTED
  533. _generation_at_interrupt = self._interrupt_running_turn(
  534. _quick_key, interrupt_reason=_INTERRUPT_REASON_EVICTED, invalidation_reason=reason,
  535. tool_reason=_INTERRUPT_TOOL_REASON_EVICTED)
  536. self._drop_turn_slot(_quick_key, run_generation=_generation_at_interrupt)
  537. def _hm_merge_pending_for_source(
  538. self, source: SessionSource, _quick_key: str, event: MessageEvent, *, merge_text: bool = False
  539. ) -> None:
  540. """Merge *event* into the source adapter's pending slot (no-op without an adapter)."""
  541. from gateway.platforms.base import merge_pending_message_event
  542. adapter = self._delivery_adapter_for(source)
  543. if adapter:
  544. merge_pending_message_event(adapter._pending_messages, _quick_key, event, merge_text=merge_text)
  545. async def _hm_busy_slash_or_photo(
  546. self, event: MessageEvent, source: SessionSource, _quick_key: str
  547. ) -> tuple[bool, Optional[str]]:
  548. """Slash-command / photo-burst handling on the busy fast-path → ``(handled, result)``. Each
  549. command's mid-run behavior is declared on its CommandDef (busy_policy / busy_handler)."""
  550. from hermes_cli.commands import resolve_command as _resolve_cmd_inner
  551. _evt_cmd = event.get_command()
  552. _cmd_def_inner = _resolve_cmd_inner(_evt_cmd) if _evt_cmd else None
  553. if _cmd_def_inner:
  554. # /status and /context are intentionally pre-gate so users always see session state.
  555. if _cmd_def_inner.name == "status":
  556. return True, await self._handle_status_command(event)
  557. if _cmd_def_inner.name == "context":
  558. return True, await self._handle_context_command(event)
  559. # Slash access control mirrors the cold-path gate so non-admins can't bypass gating
  560. # just because an agent is busy. /help and /whoami are the always-allowed floor.
  561. _denied = self._check_slash_access(source, _cmd_def_inner.name)
  562. if _denied is not None:
  563. return True, _denied
  564. if _cmd_def_inner.name in ("stop", "new"):
  565. await self._hm_stop_owner_turn(_quick_key)
  566. # Any recognized slash command dispatches per its declared busy_policy (dispatch /
  567. # interrupt_then_dispatch / reject). Unrecognized commands and plain text fall through.
  568. return True, await self._dispatch_busy_slash_command(event, _cmd_def_inner, _quick_key, source)
  569. # Telegram photo bursts arrive as near-simultaneous updates — never interrupt for a
  570. # photo-only follow-up; adapter-level batching absorbs them.
  571. if event.message_type == MessageType.PHOTO:
  572. logger.debug("PRIORITY photo follow-up for session %s — queueing without interrupt", _quick_key)
  573. self._hm_merge_pending_for_source(source, _quick_key, event)
  574. return True, None
  575. return False, None
  576. async def _hm_stop_owner_turn(self, _quick_key: str) -> None:
  577. """Messaging /stop and /new (busy, idle or confirmed) act on the authority's turn, as main
  578. cancelled the adapter task that ran it and dropped its pending slot. Cancels the still-queued
  579. ``messaging:*`` rows of this route's logical owner first (automation wakes, LOCAL/API input
  580. and ``unknown`` rows are untouched; settled silently, no pause notice), then interrupts the
  581. claimed generation: a turn still constructing its agent latches the Stop for adopt_agent."""
  582. from gateway.session_authorities import active_authority
  583. authority = active_authority(self)
  584. sid = authority.logical_owner(self.session_store.peek_session_id(_quick_key)) if authority else None
  585. if not sid or sid not in authority.sessions:
  586. if authority is not None:
  587. # The chat's first input, and a command's turn, not committed yet never commit.
  588. authority.fence_route(_quick_key)
  589. return
  590. from gateway.session_contract import SessionActor, SessionRef
  591. from hermes_state_runtime import RuntimeStoreError, list_session_admissions
  592. ref = SessionRef(authority.profile_id, sid)
  593. actor = SessionActor('messaging-control', authority.profile_id,
  594. frozenset({'session:submit', 'session:control'}), 'busy-command')
  595. rows = await asyncio.to_thread(list_session_admissions, authority.db, session_id=sid)
  596. # A FIFO paused on a lost (``unknown``) turn is the operator's to resume: its pause notice
  597. # promised the queued followers stay saved, so a /new from the chat leaves them queued.
  598. paused = any(row['status'] == 'unknown' for row in rows)
  599. if not paused:
  600. # Input (and a command's turn) that arrived before this and is not committed yet never
  601. # commits after it; one that committed before the fence is in the second listing and
  602. # cancelled below. A paused FIFO keeps both, like its queued followers.
  603. authority.fence_route(_quick_key)
  604. rows = await asyncio.to_thread(list_session_admissions, authority.db, session_id=sid)
  605. for row in [] if paused else rows:
  606. if row['status'] == 'queued' and row['principal_id'].startswith('messaging:'):
  607. # Claimed meanwhile (stale_generation): it runs as main's post-claim race does.
  608. with suppress(RuntimeStoreError):
  609. await authority.cancel_queued(actor, ref, row['admission_id'])
  610. handle = authority._handle(ref)
  611. if handle.execution_state == 'running':
  612. # Settled meanwhile (stale_generation): there is no claimed turn left to stop.
  613. with suppress(RuntimeStoreError):
  614. await authority.interrupt(actor, ref, handle.execution_generation)
  615. def _hm_busy_telegram_grace_queue(
  616. self, event: MessageEvent, source: SessionSource, _quick_key: str, effective_busy_input_mode: str
  617. ) -> bool:
  618. """Queue a Telegram text follow-up that lands within the post-start grace window."""
  619. _grace = float(os.getenv("HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS", "3.0"))
  620. _grace_state = self._peek_session_state(_quick_key)
  621. _started_at = _grace_state.turn.started_ts if _grace_state else 0
  622. if not (
  623. source.platform == Platform.TELEGRAM and event.message_type == MessageType.TEXT
  624. and _grace > 0 and _started_at and (time.time() - _started_at) <= _grace
  625. ):
  626. return False
  627. logger.debug(
  628. "Telegram follow-up arrived %.2fs after run start for %s — queueing without interrupt",
  629. time.time() - _started_at, _quick_key,
  630. )
  631. if effective_busy_input_mode != "queue":
  632. self._hm_merge_pending_for_source(source, _quick_key, event, merge_text=True)
  633. else:
  634. adapter = self._delivery_adapter_for(source)
  635. if adapter:
  636. self._enqueue_fifo(_quick_key, event, adapter)
  637. return True
  638. @staticmethod
  639. def _hm_text_only(event: MessageEvent) -> bool:
  640. return event.message_type == MessageType.TEXT and not event.media_urls and not event.media_types
  641. def _hm_busy_steer(self, event: MessageEvent, running_agent: Any, _quick_key: str) -> None:
  642. """Steer mode: inject text mid-run via ``agent.steer()``, else fall back to queue semantics."""
  643. steer_text = (event.text or "").strip()
  644. steered = False
  645. if self._hm_text_only(event) and steer_text and hasattr(running_agent, "steer"):
  646. try:
  647. steered = self._steer_running_agent(running_agent, self._steer_text_with_origin(steer_text, event))
  648. except Exception as exc:
  649. logger.warning("PRIORITY steer failed for session %s: %s", _quick_key, exc)
  650. if steered:
  651. self._fold_into_running_turn(running_agent, _quick_key, event)
  652. logger.debug("PRIORITY steer for session %s", _quick_key)
  653. return
  654. logger.debug("PRIORITY steer-fallback-to-queue for session %s", _quick_key)
  655. self._queue_or_replace_pending_event(_quick_key, event)
  656. async def _hm_busy_interrupt(
  657. self, event: MessageEvent, source: SessionSource, running_agent: Any, _quick_key: str
  658. ) -> None:
  659. """Interrupt path: redirect text-only corrections when supported, else ``agent.interrupt()``."""
  660. from gateway.run import _build_media_placeholder
  661. # Text-only corrections redirect the live turn (preserving displayed context) when the
  662. # runtime supports it; media/voice and older runtimes use the interrupt path below.
  663. _can_redirect = getattr(running_agent, "_supports_active_turn_redirect", False) is True
  664. if self._hm_text_only(event) and _can_redirect and hasattr(running_agent, "redirect"):
  665. if self._redirect_active_turn(running_agent, (event.text or "").strip(), _quick_key, event):
  666. logger.debug("PRIORITY redirect for session %s", _quick_key)
  667. return
  668. logger.debug("PRIORITY interrupt for session %s", _quick_key)
  669. _interrupt_text = event.text
  670. if self._pending_event_audio_paths(event):
  671. _interrupt_text, _ = await self._transcribe_and_echo_pending_voice(
  672. event, self._delivery_adapter_for(source), source, event.text or "",
  673. log_context="Voice-priority-interrupt",
  674. )
  675. elif not _interrupt_text and getattr(event, "media_urls", None):
  676. _interrupt_text = _build_media_placeholder(event)
  677. # Delivered via adapter._pending_messages (read by _run_agent); never also buffered on self
  678. # — that copy was never consumed and grew unbounded.
  679. running_agent.interrupt(_interrupt_text)
  680. async def _hm_busy_preempt(self, event: MessageEvent, source: SessionSource, _quick_key: str) -> bool:
  681. """busy_input_mode for a follow-up the durable FIFO is about to admit, through main's own busy
  682. resolution (voice transcribed into steer/interrupt, steer folded into the turn, busy ack).
  683. Returns True when the text already landed inside the running turn (steer / redirect), so it
  684. must NOT also be admitted as its own turn; False when the caller should admit it (queue mode,
  685. a demotion, or an interrupt — the ended turn lets the FIFO run the follow-up next)."""
  686. from gateway.run import _AGENT_PENDING_SENTINEL
  687. mode = self._effective_busy_input_mode(source)
  688. state = self._peek_session_state(_quick_key)
  689. running_agent = state.turn.agent if state else None
  690. adapter = self._delivery_adapter_for(source)
  691. if (self._draining or adapter is None or running_agent is None or running_agent is _AGENT_PENDING_SENTINEL
  692. or (event.message_type == MessageType.TEXT and mode != "steer"
  693. and self._effective_busy_text_mode(source) == "queue")):
  694. return False
  695. outcome = await self._resolve_busy_steer_or_redirect(event, _quick_key, mode, running_agent)
  696. note_busy_outcome(event, outcome)
  697. await self._busy_interrupt_and_ack(event, _quick_key, adapter, state, running_agent, outcome)
  698. return bool(outcome.steered or outcome.redirected)
  699. async def _hm_handle_running_session_message(
  700. self, event: MessageEvent, source: SessionSource, _quick_key: str
  701. ) -> Optional[str]:
  702. """Fast-path while this session's agent is running: interrupt by default (minimal latency);
  703. busy_input_mode queue/steer, subagent and compression protection demote to queue."""
  704. from gateway.run import _AGENT_PENDING_SENTINEL
  705. if getattr(event, "internal", False) and not event.get_command():
  706. # Main's rule (run_busy's busy handler, which the shared runtime's busy dispatch skips):
  707. # an internal synthetic event never interrupts or steers the running turn.
  708. self._queue_or_replace_pending_event(_quick_key, event)
  709. return None
  710. _handled, _result = await self._hm_busy_slash_or_photo(event, source, _quick_key)
  711. if not _handled:
  712. _handled, _result = await self._busy_skill_turn(event, source, _quick_key)
  713. if _handled:
  714. return _result
  715. effective_busy_input_mode = self._effective_busy_input_mode(source)
  716. if self._hm_busy_telegram_grace_queue(event, source, _quick_key, effective_busy_input_mode):
  717. return None
  718. _ra_state = self._peek_session_state(_quick_key)
  719. running_agent = _ra_state.turn.agent if _ra_state else None
  720. if running_agent is _AGENT_PENDING_SENTINEL: # agent still being set up
  721. if event.get_command() == "stop": # force-clean the sentinel so the session is unlocked
  722. self._release_running_agent_state(_quick_key)
  723. logger.info("HARD STOP (pending) for session %s — sentinel cleared", _quick_key)
  724. return EphemeralReply(t("gateway.stop.force_stopped_pending"))
  725. self._hm_merge_pending_for_source(source, _quick_key, event, merge_text=True) # picked up after start
  726. return None
  727. if self._draining:
  728. queue_during_drain = self._queue_during_drain_enabled(effective_busy_input_mode)
  729. if queue_during_drain:
  730. self._queue_or_replace_pending_event(_quick_key, event)
  731. return (
  732. t("gateway.busy.drain_queued", action=self._status_action_gerund())
  733. if queue_during_drain
  734. else t("gateway.busy.drain_rejected", action=self._status_action_gerund())
  735. )
  736. if effective_busy_input_mode == "queue":
  737. logger.debug("PRIORITY queue follow-up for session %s", _quick_key)
  738. self._queue_or_replace_pending_event(_quick_key, event)
  739. return None
  740. if effective_busy_input_mode == "steer":
  741. self._hm_busy_steer(event, running_agent, _quick_key)
  742. return None
  743. # Subagent protection: an interrupt cascades through ``_active_children`` and aborts
  744. # in-flight delegate_task work (/stop reached its handler above — still an escape hatch).
  745. # Compression protection: an interrupt would start a new turn on the pre-rotation parent
  746. # while compression rotates the id away, forking orphaned siblings.
  747. if self._agent_has_active_subagents(running_agent):
  748. _demote = "because the running agent has active subagents (#30170)"
  749. elif await self._session_has_compression_in_flight(_quick_key):
  750. _demote = "because context compression is in flight (#56391)"
  751. else:
  752. await self._hm_busy_interrupt(event, source, running_agent, _quick_key)
  753. return None
  754. logger.info("PRIORITY interrupt demoted to queue for session %s %s", _quick_key, _demote)
  755. self._queue_or_replace_pending_event(_quick_key, event)
  756. return None
  757. async def _hm_resolve_command(
  758. self, event: MessageEvent, source: SessionSource, _quick_key: str
  759. ) -> tuple[bool, Optional[str], Optional[str], Optional[str]]:
  760. """Resolve the slash command (aliases, access gate, hooks) → ``(handled, result, command,
  761. canonical)``; when ``handled`` the caller returns ``result`` as-is (may be None)."""
  762. from hermes_cli.commands import is_gateway_known_command, resolve_command as _resolve_cmd
  763. def _canon(cmd):
  764. # Aliases resolve to the canonical name so dispatch and hook names don't depend on them.
  765. _def = _resolve_cmd(cmd) if cmd else None
  766. return _def, (_def.name if _def else cmd)
  767. command = event.get_command()
  768. _cmd_def, canonical = _canon(command)
  769. # Expand alias quick commands before built-in dispatch so targets like /model openai/gpt-5.5
  770. # --provider openrouter reach the /model handler. Built-ins keep precedence: aliases only
  771. # need early handling when the typed command is not already known.
  772. if command and _cmd_def is None:
  773. qcmd = self._hm_quick_commands().get(command)
  774. if qcmd is not None and qcmd.get("type") == "alias":
  775. new_command = self._hm_expand_alias_quick_command(event, qcmd)
  776. if new_command is not None:
  777. command = new_command
  778. _cmd_def, canonical = _canon(command)
  779. if not (command and canonical and is_gateway_known_command(canonical)):
  780. return False, None, command, canonical
  781. # Per-platform slash access control: only active when the operator set ``allow_admin_from``
  782. # for the source's scope; then non-admins get ``user_allowed_commands`` plus the
  783. # /help, /whoami floor. Plain chat is never gated.
  784. _denied = self._check_slash_access(source, canonical)
  785. if _denied is not None:
  786. return True, _denied, command, canonical
  787. _handled, _result, new_command = await self._hm_command_hooks(
  788. event, source, _quick_key, command, canonical
  789. )
  790. if _handled:
  791. return True, _result, command, canonical
  792. if new_command is not None:
  793. command = new_command
  794. _cmd_def, canonical = _canon(command)
  795. return False, None, command, canonical
  796. async def _hm_confirm_destructive(self, event, command: str, detail: str, handler) -> tuple[bool, Optional[str]]:
  797. async def _execute():
  798. return await handler(event)
  799. return True, await self._maybe_confirm_destructive_slash(
  800. event=event, command=command, title=f"/{command}", detail=detail, execute=_execute,
  801. )
  802. async def _hm_cmd_new(self, event, source, _quick_key):
  803. if await asyncio.to_thread(self._is_telegram_topic_root_lobby, source):
  804. return True, self._telegram_topic_root_new_message()
  805. return await self._hm_confirm_destructive(
  806. event, "new", t("gateway.confirm.detail_new"),
  807. self._handle_reset_command,
  808. )
  809. async def _hm_cmd_start(self, event, source, _quick_key):
  810. logger.info("Ignoring /start platform ping for session %s", _quick_key)
  811. return True, ""
  812. async def _hm_cmd_egress(self, event, source, _quick_key):
  813. from hermes_cli.proxy_cli import format_status_text
  814. return True, format_status_text()
  815. async def _hm_rewrite_turn_to_prompt(self, event, source, name: str, ack: str, build) -> tuple[bool, Optional[str]]:
  816. """Ack, then rewrite the turn to ``build()`` and fall through to the agent (keeps role
  817. alternation; works on any backend). A failing builder replies with a retry hint."""
  818. await self._send_command_ack(source, ack, name)
  819. try:
  820. event.text = await asyncio.to_thread(build)
  821. except Exception:
  822. return True, t("gateway.prompt_command.start_failed", command=name)
  823. return False, None
  824. # /learn and /plan: ack, rewrite the turn to a builder prompt, fall through to the agent.
  825. async def _hm_cmd_learn(self, event, source, _quick_key):
  826. from agent.learn_prompt import build_learn_prompt
  827. req = event.get_command_args().strip()
  828. _ack = t("gateway.learn.ack_described") if req else t("gateway.learn.ack_conversation")
  829. return await self._hm_rewrite_turn_to_prompt(event, source, "learn", _ack, lambda: build_learn_prompt(req))
  830. async def _hm_cmd_plan(self, event, source, _quick_key):
  831. from agent.plan_prompt import build_plan_prompt
  832. task = event.get_command_args().strip()
  833. _ack = (t("gateway.plan.ack_task", task=task[:80] + ("…" if len(task) > 80 else ""))
  834. if task else t("gateway.plan.ack_conversation"))
  835. return await self._hm_rewrite_turn_to_prompt(event, source, "plan", _ack, lambda: build_plan_prompt(task))
  836. async def _hm_cmd_init(self, event, source, _quick_key):
  837. # /init builds the prompt first: the ack wording depends on whether AGENTS.md exists.
  838. from hermes_cli.init_command import build_init_prompt_for_cwd
  839. try:
  840. # The SESSION's active directory, not this process's launch dir: the desktop app
  841. # launches the backend from the home directory, so a bare os.getcwd() scanned and
  842. # updated the HOME's AGENTS.md instead of the workspace attached to the session.
  843. _init_prompt = build_init_prompt_for_cwd(
  844. extra=event.get_command_args().strip(),
  845. session_key=_quick_key or self._session_key_for_source(source),
  846. )
  847. except Exception:
  848. return True, t("gateway.init.start_failed")
  849. _ack = (
  850. t("gateway.init.ack_update")
  851. if "UPDATE the existing AGENTS.md" in _init_prompt
  852. else t("gateway.init.ack_generate")
  853. )
  854. await self._send_command_ack(source, _ack, "init")
  855. event.text = _init_prompt
  856. return False, None
  857. async def _hm_cmd_blueprint(self, event, source, _quick_key):
  858. _blueprint_result = await self._handle_blueprint_command(event)
  859. _text = getattr(_blueprint_result, "text", "") or ""
  860. _blueprint_seed = getattr(_blueprint_result, "agent_seed", None)
  861. if not _blueprint_seed:
  862. return True, _text or None
  863. # Blueprint matched — rewrite the turn to the seed and fall through so the agent collects
  864. # each slot value conversationally, then calls the cronjob tool (the /steer pattern).
  865. if _text:
  866. await self._send_command_ack(source, _text, "blueprint")
  867. try:
  868. event.text = _blueprint_seed
  869. except Exception:
  870. return True, _text or None
  871. return False, None
  872. async def _hm_cmd_undo(self, event, source, _quick_key):
  873. _undo_n = 1
  874. _undo_raw = event.get_command_args().strip()
  875. if _undo_raw:
  876. with suppress(ValueError, IndexError):
  877. _undo_n = max(1, int(_undo_raw.split()[0]))
  878. _undo_detail = (
  879. t("gateway.confirm.detail_undo_one")
  880. if _undo_n == 1
  881. else t("gateway.confirm.detail_undo_many", count=_undo_n)
  882. )
  883. return await self._hm_confirm_destructive(event, "undo", _undo_detail, self._handle_undo_command)
  884. # /queue and /steer on the idle path: no agent is running, so strip the prefix and send the
  885. # payload as a regular user turn; an empty payload surfaces the usage hint.
  886. async def _hm_cmd_queue(self, event, source, _quick_key):
  887. return self._hm_send_payload_as_turn(event, t("gateway.queue.usage"))
  888. async def _hm_cmd_steer(self, event, source, _quick_key):
  889. return self._hm_send_payload_as_turn(event, t("gateway.steer.usage_idle"))
  890. @staticmethod
  891. def _hm_send_payload_as_turn(event, usage: str) -> tuple[bool, Optional[str]]:
  892. payload = event.get_command_args().strip()
  893. if not payload:
  894. return True, usage
  895. with suppress(Exception):
  896. event.text = payload
  897. return False, None
  898. async def _hm_cmd_moa(self, event, source, _quick_key):
  899. # /moa is one-shot sugar only: run a single prompt through the default MoA preset, then
  900. # restore the prior model. To *switch* to a MoA preset for the session, pick it from the
  901. # model picker (MoA presets surface as a virtual "Mixture of Agents" provider).
  902. from hermes_cli.moa_config import moa_usage, normalize_moa_config
  903. from hermes_cli.config import load_config
  904. moa_payload = event.get_command_args().strip()
  905. if not moa_payload:
  906. return True, moa_usage()
  907. try:
  908. cfg = load_config()
  909. moa_cfg = normalize_moa_config(cfg.get("moa") if isinstance(cfg, dict) else {})
  910. except Exception:
  911. moa_cfg = normalize_moa_config({})
  912. try:
  913. event.text = moa_payload
  914. _moa_state = self._session_state(_quick_key)
  915. # Same one-shot snapshot `/model --once` uses, so eviction/stop/finalizer settle both alike.
  916. self._claim_one_turn_restore(_quick_key)
  917. _moa_state.conversation.model_override = {
  918. "provider": "moa", "model": moa_cfg["default_preset"], "base_url": "moa://local",
  919. "api_key": "moa-virtual-provider", "api_mode": "chat_completions",
  920. }
  921. self._evict_cached_agent(_quick_key)
  922. except Exception:
  923. return True, t("gateway.moa.prepare_failed")
  924. return False, None
  925. # Idle-path built-ins with bespoke flow (confirmations, prompt rewrites, one-shot MoA), each
  926. # handled by ``_hm_cmd_<name>`` → ``(handled, result)``; ``(False, None)`` falls through to the agent.
  927. _HM_CANONICAL_COMMANDS = frozenset({
  928. "new", "start", "egress", "learn", "plan", "init", "blueprint", "undo", "queue", "steer", "moa",
  929. })
  930. async def _hm_dispatch_canonical_command(
  931. self, event: MessageEvent, source: SessionSource, _quick_key: str,
  932. canonical: Optional[str],
  933. ) -> tuple[bool, Optional[str]]:
  934. """Dispatch built-in idle-path commands → ``(handled, result)``; prompt-rewriting commands
  935. mutate ``event.text`` and return ``(False, None)`` to fall through to the agent."""
  936. plain_handler = (
  937. self._gateway_plain_command_handlers().get(canonical)
  938. or self._gateway_idle_command_handlers().get(canonical)
  939. )
  940. if plain_handler is not None:
  941. async with self._async_profile_scope_for_source(source):
  942. return True, await plain_handler(event)
  943. if canonical in self._HM_CANONICAL_COMMANDS:
  944. return await getattr(self, f"_hm_cmd_{canonical}")(event, source, _quick_key)
  945. return False, None
  946. def _hm_bundle_slash_rewrite(
  947. self, event: MessageEvent, source: SessionSource, _quick_key: str, command: str
  948. ) -> bool:
  949. """Rewrite ``/<bundle>`` to the bundle invocation message; True when handled.
  950. Skill bundles take precedence over individual skill commands (mirrors CLI dispatch)."""
  951. try:
  952. from agent.skill_bundles import (
  953. build_bundle_invocation_message, resolve_bundle_command_key
  954. )
  955. bundle_key = resolve_bundle_command_key(command)
  956. if bundle_key is None:
  957. return False
  958. # Pass the platform explicitly: bundle skill loading bypasses get_skill_commands()'
  959. # scan-time disabled filter, and one gateway process serves several platforms, so
  960. # env-var platform resolution can't be trusted here.
  961. # Mirrors the stacked-skill gate (#58888).
  962. bundle_result = build_bundle_invocation_message(
  963. bundle_key, event.get_command_args().strip(), task_id=_quick_key,
  964. platform=source.platform.value if source.platform else None,
  965. )
  966. if not bundle_result:
  967. return False
  968. event.text, _loaded, missing = bundle_result
  969. if missing:
  970. logger.info("Bundle %s skipped missing skills: %s", bundle_key, ", ".join(missing))
  971. return True # Fall through to normal message processing with bundle content
  972. except Exception as exc:
  973. logger.warning("Bundle dispatch failed: %s", exc)
  974. return False
  975. @staticmethod
  976. def _hm_unknown_slash_reply(command: str, source: SessionSource) -> Optional[str]:
  977. """Reply for a /command that is not built-in/plugin/skill; None when it is known."""
  978. from gateway.run import _check_unavailable_skill
  979. from hermes_cli.commands import GATEWAY_KNOWN_COMMANDS
  980. # Known commands never need an unavailable-skill hint (which can require a cold scan).
  981. if command.replace("_", "-") in GATEWAY_KNOWN_COMMANDS:
  982. return None
  983. # Known-but-disabled or uninstalled skill → actionable guidance.
  984. _unavail_msg = _check_unavailable_skill(command)
  985. if _unavail_msg:
  986. return _unavail_msg
  987. # Genuinely unrecognized: warn instead of forwarding to the LLM as free text (it invents
  988. # tool calls). Normalize to hyphenated form first: the quick-command block may have set an
  989. # alias target, so the resolved def can be stale.
  990. logger.warning(
  991. "Unrecognized slash command /%s from %s — replying with unknown-command notice",
  992. command, source.platform.value if source.platform else "?",
  993. )
  994. return t("gateway.unknown_command", command=command)
  995. def _hm_skill_slash_rewrite(
  996. self, event: MessageEvent, source: SessionSource, _quick_key: str, command: Optional[str]
  997. ) -> Optional[str]:
  998. """Rewrite ``/<bundle>`` / ``/<skill>`` invocations into the skill prompt on ``event.text``;
  999. returns a reply string when the command is disabled/unknown/failed, else None.
  1000. resolve_skill_command_key() handles the Telegram underscore/hyphen round-trip (/claude_code)."""
  1001. if not command or self._hm_bundle_slash_rewrite(event, source, _quick_key, command):
  1002. return None
  1003. try:
  1004. from agent.skill_commands import (
  1005. get_skill_commands, build_skill_invocation_message, resolve_skill_command_key
  1006. )
  1007. skill_cmds = get_skill_commands()
  1008. cmd_key = resolve_skill_command_key(command)
  1009. if cmd_key is None:
  1010. return self._hm_unknown_slash_reply(command, source)
  1011. _plat = source.platform.value if source.platform else None
  1012. user_instruction = event.get_command_args().strip()
  1013. # Stacked slash-skill invocations: `/skill-a /skill-b do XYZ` loads every leading skill
  1014. # (up to 5), not just the first. Mirrors CLI. Native split: plugin skills are interactive-only.
  1015. try:
  1016. from agent.skill_commands import (
  1017. build_stacked_skill_invocation_message as _build_stacked,
  1018. split_stacked_skill_commands,
  1019. )
  1020. extra_keys, stacked_instruction = split_stacked_skill_commands(user_instruction)
  1021. except Exception:
  1022. _build_stacked = None
  1023. extra_keys, stacked_instruction = [], user_instruction
  1024. _skill_name = skill_cmds[cmd_key].get("name", "")
  1025. if _plat and (_skill_name or extra_keys):
  1026. # Per-platform disabled check: get_skill_commands() only applies the *global*
  1027. # disabled list at scan time (process-global cache across platforms), and
  1028. # split_stacked_skill_commands() only checks each extra token is a KNOWN skill.
  1029. from agent.skill_utils import get_disabled_skill_names as _get_plat_disabled
  1030. _plat_disabled = _get_plat_disabled(platform=_plat)
  1031. if _skill_name and _skill_name in _plat_disabled:
  1032. return t("gateway.skills.disabled_for_platform", name=_skill_name, platform=_plat)
  1033. _disabled_extra = [
  1034. skill_cmds.get(k, {}).get("name", "")
  1035. for k in extra_keys
  1036. if skill_cmds.get(k, {}).get("name", "") in _plat_disabled
  1037. ]
  1038. if _disabled_extra:
  1039. return t("gateway.skills.stacked_disabled", names=", ".join(_disabled_extra), platform=_plat)
  1040. if extra_keys and _build_stacked is not None:
  1041. stacked_result = _build_stacked(
  1042. [cmd_key, *extra_keys], stacked_instruction, task_id=_quick_key,
  1043. )
  1044. if not stacked_result:
  1045. return t("gateway.skills.stacked_load_failed", command=command)
  1046. event.text, _loaded, _missing = stacked_result
  1047. else:
  1048. msg = build_skill_invocation_message(cmd_key, user_instruction, task_id=_quick_key)
  1049. if msg:
  1050. event.text = msg
  1051. # Fall through to normal message processing with skill content
  1052. except Exception as e:
  1053. logger.debug("Skill command check failed (non-fatal): %s", e)
  1054. return None
  1055. async def _hm_pending_reply_intercepts(
  1056. self, event: MessageEvent, source: SessionSource, _quick_key: str
  1057. ) -> Optional[str]:
  1058. """Replies owned by in-flight work: pending /update prompt, clarify, slash-confirm.
  1059. Only events that may control the gateway (``allow_gateway_control``) can answer them, never
  1060. an admitted turn: it was offered here before its commit, or a slash command queued it."""
  1061. from gateway.session_ingress import executing_admission
  1062. if not event.allow_gateway_control or getattr(event, "_fifo_only", False) or executing_admission.get():
  1063. return None
  1064. _reply = self._hm_update_prompt_reply(event, _quick_key)
  1065. if _reply is None:
  1066. _reply = await self._hm_clarify_reply(event, source, _quick_key)
  1067. if _reply is None:
  1068. _reply = await self._hm_slash_confirm_reply(event, _quick_key)
  1069. return _reply
  1070. async def _hm_dispatch_idle_commands(
  1071. self, event: MessageEvent, source: SessionSource, _quick_key: str
  1072. ) -> tuple[bool, Optional[str]]:
  1073. """Idle path: resolve + dispatch slash commands; rewriting commands fall through to the agent.
  1074. A command rewritten into a turn keeps the /stop and /new epoch it arrived under, read before
  1075. the (slow, off-loop) rewrite, so a reset during it drops the command, as on the busy path."""
  1076. stop_epoch = self._route_stop_epoch(_quick_key)
  1077. _handled, _result, command, canonical = await self._hm_resolve_command(event, source, _quick_key)
  1078. if not _handled:
  1079. _handled, _result = await self._hm_dispatch_canonical_command(event, source, _quick_key, canonical)
  1080. if not _handled:
  1081. _handled, _result, command = await self._hm_dispatch_quick_and_plugin_commands(event, source, command)
  1082. if not _handled:
  1083. # Skill-slash resolution is disk-bound (cold skill scan, skill file loads, the
  1084. # unavailable-skill rglob over every skills dir) and uncached on a first hit; on a
  1085. # large install it held the loop past the liveness watchdog (#111091). The executor
  1086. # hop carries the profile contextvars the scan is scoped to.
  1087. _result = await self._run_in_executor_with_context(
  1088. self._hm_skill_slash_rewrite, event, source, _quick_key, command)
  1089. _handled = _result is not None
  1090. if not _handled and command: # rewritten into a turn: the authority's FIFO, like text
  1091. _handled, _result = await self._admit_command_turn(event, source, _quick_key, stop_epoch)
  1092. return _handled, _result
  1093. def _hm_rescue_orphaned_fifo(
  1094. self, event: MessageEvent, source: SessionSource, is_internal: bool, _quick_key: str
  1095. ) -> tuple[MessageEvent, SessionSource, bool]:
  1096. """FIFO orphan rescue: a session that went idle with a populated overflow (post-turn drain
  1097. never promoted, e.g. a compression-demoted follow-up) silently orphaned those events. The
  1098. oldest orphan runs as THIS turn and the incoming event is parked behind the chain. Skipped
  1099. for control commands and internal events."""
  1100. try:
  1101. # ── FIFO orphan rescue (#99882) ──────────────────────────────── If this session went idle with
  1102. # a populated overflow (queued during a busy window whose post-turn drain never promoted — e.g.
  1103. # a compression-demoted follow-up after the compression window ended through an exit that
  1104. # skipped the promotion site), those events were silently orphaned. We are starting the next
  1105. # turn for this session NOW: re-stage the orphans in FIFO order and enqueue the incoming event
  1106. # behind them, so arrival order (#28503) holds: oldest orphan runs as this turn, the rest drain
  1107. # in order, the new message last.
  1108. _orphan_adapter = self._delivery_adapter_for(source)
  1109. if _orphan_adapter is None or getattr(event, "internal", False) or event.get_command():
  1110. return event, source, is_internal
  1111. _rescued = self._rescue_orphaned_overflow(_quick_key, _orphan_adapter)
  1112. if _rescued is None:
  1113. return event, source, is_internal
  1114. # Into the slot when the chain was a single orphan (post-turn drain picks it up),
  1115. # otherwise into overflow behind the already-staged next orphan.
  1116. self._enqueue_fifo(_quick_key, event, _orphan_adapter)
  1117. # Same session key by construction; carry the orphan's own source so reply anchors /
  1118. # thread metadata point at the message actually being answered.
  1119. _rescued_source = getattr(_rescued, "source", None)
  1120. source = _rescued_source if _rescued_source is not None else source
  1121. return _rescued, source, bool(getattr(_rescued, "internal", False))
  1122. except Exception:
  1123. logger.debug("FIFO orphan rescue pre-claim failed for %s", _quick_key, exc_info=True)
  1124. return event, source, is_internal
  1125. async def _hm_authority_admission(
  1126. self, event: MessageEvent, source: SessionSource, _quick_key: str, is_internal: bool,
  1127. ) -> tuple[bool, Optional[str]]:
  1128. """``(True, reply)`` when the routed profile's session authority owned this message
  1129. (preempted, plugin-consumed or admitted to its durable FIFO); ``(False, None)`` to continue
  1130. on the in-process path. Raises ``RuntimeStoreError('profile_mismatch')`` for a scope this
  1131. process does not serve."""
  1132. # The message handler entered the routed profile's scope; its authority owns this turn.
  1133. from gateway.session_authorities import active_authority
  1134. authority = active_authority(self)
  1135. if authority is not None and not event.get_command() and not is_internal:
  1136. from gateway.session_ingress import executing_admission
  1137. if not executing_admission.get():
  1138. # A message the adapter saw as idle still waits when an earlier queued turn runs
  1139. # outside its session guard: the running-turn check is the busy test that counts.
  1140. busy = self._is_session_running(_quick_key) and not getattr(event, "_fifo_only", False)
  1141. if busy:
  1142. stamp_busy_arrival(self._delivery_adapter_for(source), event)
  1143. try:
  1144. return await self._hm_admit_to_fifo(authority, event, source, _quick_key, busy)
  1145. finally:
  1146. settle_busy_arrival(event) # never admitted, refused or dropped: its fate is known
  1147. if (authority is None and not is_internal and not event.get_command()
  1148. and getattr(self, 'session_authority', None) is not None):
  1149. # Scoped to a home this process does not serve: never fall back to the launch ledger.
  1150. from hermes_state_runtime import RuntimeStoreError
  1151. raise RuntimeStoreError('profile_mismatch')
  1152. return False, None
  1153. async def _hm_admit_to_fifo(
  1154. self, authority: Any, event: MessageEvent, source: SessionSource, _quick_key: str, busy: bool,
  1155. ) -> tuple[bool, Optional[str]]:
  1156. """The authority-owned path of ``_hm_authority_admission`` (not inside a FIFO execution)."""
  1157. from gateway.session_ingress import admit_message
  1158. # The durable FIFO only orders turns; busy_input_mode still decides what a follow-up
  1159. # does to the RUNNING one (steer into it, redirect it, or end it so the FIFO advances).
  1160. # Without this, ``interrupt`` degrades to ``queue`` behind a turn that may hang for
  1161. # its whole request timeout.
  1162. # A bare "yes"/"no" to a blocking dangerous-command approval answers it (#46866):
  1163. # never an interrupt (read as deny) nor a queued turn (auto-deny deadlock).
  1164. # A turn a slash command produced (``/queue yes``) is never live typing.
  1165. if busy and (await self._route_plaintext_approval_while_busy(event, _quick_key)
  1166. or await self._hm_busy_preempt(event, source, _quick_key)):
  1167. return True, None
  1168. _consumed, _consumer_reply = await self._hm_post_admission_consume(event, source, _quick_key)
  1169. if _consumed:
  1170. return True, _consumer_reply
  1171. if getattr(event, "_fifo_only", False) and event._stop_epoch != self._route_stop_epoch(_quick_key):
  1172. return True, None # a /stop or /new came after its command, as it clears the slot
  1173. # A failed admit stays the authority's answer (refusal notice or turn error), never a
  1174. # pending legacy turn: that would run unadmitted, outside the FIFO's order.
  1175. note_busy_admitting(event)
  1176. return True, await admit_message(authority, event)
  1177. async def _handle_message(self, event: MessageEvent) -> Optional[str]:
  1178. """Handle an incoming message from any platform: auth → command check → running-agent
  1179. interrupt → get/create session → build context → run agent → return response."""
  1180. from gateway.run import _AGENT_PENDING_SENTINEL
  1181. _admitted = await self._hm_admit_event(event)
  1182. if _admitted is None:
  1183. return None
  1184. event, source, is_internal = _admitted
  1185. if not is_internal:
  1186. from hermes_cli.observability.shared_metrics_events import record_gateway_slash_command
  1187. record_gateway_slash_command(event)
  1188. # TERMINAL-DECLINE LATCH TEARDOWN. Deliberately placed AFTER admission,
  1189. # not on the adapter's raw inbound: profile routing, the ignored-channel
  1190. # guard, plugin hooks and user authorization all reject events above,
  1191. # and a rejected event must not be able to clear a refusal belonging to
  1192. # an active turn. This is also the single entry point every lane shares
  1193. # — Discord interaction passthrough builds its own MessageEvent and
  1194. # calls handle_message directly, so a teardown on the relay's inbound
  1195. # handler left those turns muted.
  1196. _paused_notice = self._hm_estop_gate(event, source, is_internal)
  1197. if _paused_notice is not None:
  1198. return _paused_notice
  1199. _quick_key = self._session_key_for_source(source)
  1200. _reply = None if is_internal else await self._hm_pending_reply_intercepts(event, source, _quick_key)
  1201. if _reply is not None:
  1202. return _reply
  1203. _owned, _authority_reply = await self._hm_authority_admission(event, source, _quick_key, is_internal)
  1204. if _owned:
  1205. return _authority_reply
  1206. # Evict a leaked/reaped ``_running_agents`` slot before the busy-session fast-path.
  1207. self._hm_evict_idle_stale_agent(_quick_key)
  1208. if self._is_session_running(_quick_key):
  1209. self._hm_evict_reaped_agent(_quick_key)
  1210. if self._is_session_running(_quick_key):
  1211. return await self._hm_handle_running_session_message(event, source, _quick_key)
  1212. _handled, _result = await self._hm_dispatch_idle_commands(event, source, _quick_key)
  1213. if _handled:
  1214. return _result
  1215. # Pending exec approvals go through /approve and /deny only — no bare-text matching, or a
  1216. # conversational "yes" would execute a dangerous command.
  1217. if not is_internal:
  1218. if await asyncio.to_thread(self._is_telegram_topic_root_lobby, source):
  1219. # Debounced so a user who forgets about topic mode doesn't get ten reminders.
  1220. if self._should_send_telegram_lobby_reminder(source):
  1221. return self._telegram_topic_root_lobby_message()
  1222. return None
  1223. # External-drain new-turn gate: when NAS engaged an external drain (.drain_request.json,
  1224. # seen by _drain_control_watcher), refuse to START new turns so the in-flight set can
  1225. # only fall to zero. Reversible.
  1226. if self._external_drain_active:
  1227. logger.info("Refusing new turn for session %s — external drain active.", _quick_key)
  1228. return t("gateway.busy.draining_maintenance")
  1229. # Claim this session before any await: many awaits sit between here and _run_agent
  1230. # registering the real AIAgent; without this sentinel a second message during any of them
  1231. # passes the "already running" guard and spins up a duplicate agent for the same session.
  1232. _active_session_lease, _limit_message = self._claim_active_session_slot(_quick_key, source)
  1233. if _limit_message is not None:
  1234. logger.info("Rejecting new active session %s: max_concurrent_sessions reached", _quick_key)
  1235. return _limit_message
  1236. event, source, is_internal = self._hm_rescue_orphaned_fifo(event, source, is_internal, _quick_key)
  1237. _claim_state = self._session_state(_quick_key)
  1238. if _active_session_lease is not None:
  1239. _claim_state.turn.lease = _active_session_lease
  1240. _claim_state.turn.agent = _AGENT_PENDING_SENTINEL
  1241. _claim_state.turn.event = event
  1242. _claim_state.turn.started_ts = time.time()
  1243. from hermes_cli.observability.shared_metrics_gateway import start_reply_clock
  1244. start_reply_clock(source, internal=is_internal)
  1245. self._persist_active_agents()
  1246. _run_generation = self._begin_session_run_generation(_quick_key)
  1247. try:
  1248. # Fail-open plugin consume inside the claimed slot (#129958); once per message.
  1249. if not is_internal:
  1250. _consumed, _consumer_reply = await self._hm_post_admission_consume(event, source, _quick_key)
  1251. if _consumed:
  1252. return _consumer_reply
  1253. try:
  1254. _agent_result = await self._handle_message_with_agent(event, source, _quick_key, _run_generation)
  1255. except TurnLeaseTimeoutError as exc:
  1256. # A rejected message, not a completed turn: return before the /goal judge so it
  1257. # cannot consume the resend notice and enqueue a synthetic continuation loop.
  1258. logger.error(
  1259. "Rejecting turn for routing key %s on session %s after "
  1260. "turn-lease timeout; transcript load was not started and "
  1261. "the user must resend",
  1262. _quick_key, exc.session_id,
  1263. )
  1264. return t("gateway.busy.another_turn_running")
  1265. try:
  1266. await self._run_post_turn_hooks(
  1267. agent_result=_agent_result, source=source, is_internal=is_internal, event=event,
  1268. )
  1269. except Exception as _goal_exc:
  1270. logger.debug("post-turn hook failed: %s", _goal_exc)
  1271. return _agent_result
  1272. finally:
  1273. # One-shot restore (/moa, /model --once) must run on EVERY exit path (success,
  1274. # exception, interrupt); the generation guard makes a displaced turn's finalizer a no-op.
  1275. self._restore_pending_one_turn_model_override(_quick_key, _run_generation)
  1276. # SIGKILL/OOM skips finally, leaving the durable marker for the next unclean startup's
  1277. # recovery pass. A turn the adapter delivers hands its marker to that lifecycle, which
  1278. # clears it only once the reply is in the delivery ledger (else a kill in between
  1279. # left neither marker nor ledger row and the persisted reply was never sent).
  1280. if not getattr(event, "_turn_marker_handoff", False):
  1281. await self._clear_durable_active_turn(event)
  1282. # Release only this turn's generation. Eviction may immediately admit a replacement
  1283. # through the cold path; an unconditional release here would then clear the replacement
  1284. # sentinel/agent and lease. Reset/stop release their stale slot before installing a
  1285. # successor, preserving reset-zombie cleanup without granting gen-N successor authority.
  1286. self._release_running_agent_state(_quick_key, run_generation=_run_generation)
  1287. # Turn lease is keyed by (routing key, run generation) so this unwind can only free
  1288. # the lease its own turn acquired, never a newer turn's.
  1289. self._release_turn_lease(_quick_key, _run_generation)
  1290. def _restore_pending_one_turn_model_override(self, session_key: str, run_generation: int | None = None) -> None:
  1291. """Restore the per-session model override captured by ``/model --once`` or ``/moa``.
  1292. With ``run_generation`` (the turn finalizer) the restore happens only while that generation
  1293. is still current; a stop/reset/eviction has already settled the snapshot itself (see
  1294. ``_invalidate_session_run_generation``), so the displaced finalizer finds nothing to do.
  1295. Without it (the settlement paths) the restore is unconditional."""
  1296. if not session_key:
  1297. return
  1298. try:
  1299. _otr_state = self._peek_session_state(session_key)
  1300. if _otr_state is None or not _otr_state.conversation.one_turn_restore:
  1301. return
  1302. if run_generation is not None and not self._is_session_run_current(session_key, run_generation):
  1303. return
  1304. snapshot = _otr_state.conversation.one_turn_restore
  1305. _otr_state.conversation.one_turn_restore = None
  1306. self._restore_session_model_override(session_key, snapshot)
  1307. except Exception:
  1308. logger.debug("Failed to restore one-turn model override", exc_info=True)
  1309. def _prefix_inbound_sender_context(self, event: MessageEvent, source: SessionSource, message_text: str) -> str:
  1310. """Attribute the sender in shared multi-user sessions and prepend history-backfill channel context."""
  1311. _is_shared_multi_user = is_shared_multi_user_session(
  1312. source, group_sessions_per_user=getattr(self.config, "group_sessions_per_user", True),
  1313. thread_sessions_per_user=getattr(self.config, "thread_sessions_per_user", False),
  1314. )
  1315. if _is_shared_multi_user and source.user_name:
  1316. # Display names are attacker-influenceable: neutralize newlines/control chars or a
  1317. # hostile name masquerades as a fake markdown section (mirrors build_session_context_prompt).
  1318. _safe_user_name = neutralize_untrusted_inline_text(source.user_name)
  1319. # Slack: expose the CURRENT speaker's verifiable `<@U...>` id so "mention me again" has a
  1320. # trusted target (display names are ambiguous). user_id comes from the envelope, not user-editable.
  1321. # See #17916.
  1322. if source.platform == Platform.SLACK and source.user_id:
  1323. _safe_user_name = f"{_safe_user_name} | Slack user <@{source.user_id}>"
  1324. message_text = f"[{_safe_user_name}] {message_text}"
  1325. # After the sender-prefix so the prefix applies only to the trigger message, not the backfill.
  1326. if getattr(event, "channel_context", None):
  1327. message_text = f"{event.channel_context}\n\n[New message]\n{message_text}"
  1328. return message_text
  1329. @staticmethod
  1330. def _classify_inbound_media(
  1331. event: MessageEvent, pending_stt_prepared: bool
  1332. ) -> tuple[list, list, list, list]:
  1333. """Split ``event.media_urls`` into (image, STT-voice, audio-file, video) paths. Per-attachment
  1334. MIME wins over the message-level type (a document sent alongside an image must not be routed
  1335. as an image). MessageType.AUDIO / mixed DOCUMENT audio is a file attachment, never STT."""
  1336. from gateway.run import _event_media_is_audio, _event_media_is_image, _event_media_is_stt_input
  1337. image_paths, audio_paths, audio_file_paths, video_paths = [], [], [], []
  1338. for i, path in enumerate(event.media_urls or []):
  1339. mtype = event.media_types[i] if i < len(event.media_types) else ""
  1340. if _event_media_is_image(event, i):
  1341. image_paths.append(path)
  1342. if _event_media_is_audio(event, i):
  1343. if event.message_type in {MessageType.AUDIO, MessageType.DOCUMENT}:
  1344. audio_file_paths.append(path)
  1345. elif not pending_stt_prepared and _event_media_is_stt_input(event, i):
  1346. audio_paths.append(path)
  1347. if mtype.startswith("video/") or (not mtype and event.message_type == MessageType.VIDEO):
  1348. video_paths.append(path)
  1349. return image_paths, audio_paths, audio_file_paths, video_paths
  1350. async def _enrich_inbound_images(
  1351. self, source: SessionSource, session_key: str, message_text: str, image_paths: list[str]
  1352. ) -> str:
  1353. """Route images natively (attach pixels at run_conversation) or pre-analyze them into text."""
  1354. # See agent/image_routing.py. Offloaded to a thread: the decision does blocking network I/O
  1355. # (models.dev fetch on cache miss, Ollama /api/show probe) that would stall the event loop.
  1356. _img_mode = await asyncio.to_thread(
  1357. self._decide_image_input_mode, source=source, session_key=session_key,
  1358. )
  1359. if _img_mode == "native":
  1360. self._session_state(session_key).persistent.native_image_paths = list(image_paths)
  1361. logger.info(
  1362. "Image routing: native (model supports vision). %d image(s) will be attached inline.",
  1363. len(image_paths),
  1364. )
  1365. return message_text
  1366. logger.info(
  1367. "Image routing: text (mode=%s). Pre-analyzing %d image(s) via vision_analyze.",
  1368. _img_mode, len(image_paths),
  1369. )
  1370. # Vision enrichment runs before AIAgent.run_conversation(), so bind this session's resolved
  1371. # runtime explicitly rather than consulting process-global compatibility mirrors.
  1372. vision_runtime = None
  1373. try:
  1374. turn_model, runtime_kwargs = self._resolve_session_agent_runtime(
  1375. source=source, session_key=session_key,
  1376. )
  1377. vision_runtime = {**(runtime_kwargs or {}), "model": turn_model}
  1378. except Exception:
  1379. logger.debug("vision enrichment: session runtime resolution failed", exc_info=True)
  1380. from agent.auxiliary_client import scoped_runtime_main
  1381. with scoped_runtime_main(vision_runtime):
  1382. return await self._enrich_message_with_vision(message_text, image_paths)
  1383. async def _echo_stt_transcripts(
  1384. self, adapter, source: SessionSource, transcripts: list[str], *, metadata=None, log_context: str = "Transcript"
  1385. ) -> None:
  1386. """Send each transcript back as ``🎙️ "…"`` (best-effort; failures are logged, never raised)."""
  1387. from gateway.bot_peer_notices import automatic_notices_allowed
  1388. for tx in transcripts if automatic_notices_allowed(source) else ():
  1389. try:
  1390. await adapter.send(source.chat_id, t("gateway.voice.transcript_echo_short", text=tx), metadata=metadata)
  1391. except Exception as echo_exc:
  1392. logger.debug("%s echo failed (non-fatal): %s", log_context, echo_exc)
  1393. async def _enrich_inbound_voice(
  1394. self, event: MessageEvent, source: SessionSource, message_text: str, audio_paths: list[str]
  1395. ) -> str:
  1396. message_text, _successful_transcripts = await self._enrich_message_with_transcription(
  1397. message_text, audio_paths,
  1398. )
  1399. # Echo each successful transcript back immediately when configured so users can verify STT
  1400. # quality in real time. On transcription failure do NOT send a hardcoded notice: that
  1401. # bypassed the LLM and produced two replies; enrichment leaves one neutral marker instead.
  1402. if _successful_transcripts and self._should_echo_stt_transcripts():
  1403. _echo_adapter = self._delivery_adapter_for(source)
  1404. if _echo_adapter:
  1405. _echo_meta = self._thread_metadata_for_source(source, self._reply_anchor_for_event(event))
  1406. await self._echo_stt_transcripts(_echo_adapter, source, _successful_transcripts, metadata=_echo_meta)
  1407. return message_text
  1408. @staticmethod
  1409. def _inbound_attachment_display_name(path: str, original_name: str = "") -> tuple[str, str]:
  1410. """``(display_name, agent_visible_path)``. The display name is the adapter-supplied
  1411. original name when known (``MessageEvent.media_filenames``), else parsed from the native
  1412. cache filename ``<id>_<id>_<original>``. A relay temp file (``relay_media_<random>``)
  1413. carries no name, so it is labelled unknown rather than shown as the random basename.
  1414. The path is translated to the in-container mount under a Docker backend."""
  1415. from tools.credential_files import to_agent_visible_cache_path
  1416. basename = os.path.basename(path)
  1417. name = clean_attachment_filename(original_name)
  1418. if not name and basename.startswith(_RELAY_MEDIA_PREFIX):
  1419. return _UNKNOWN_ATTACHMENT_NAME, to_agent_visible_cache_path(path)
  1420. if not name:
  1421. parts = basename.split("_", 2)
  1422. name = parts[2] if len(parts) >= 3 else basename
  1423. return re.sub(r'[^\w.\- ]', '_', name), to_agent_visible_cache_path(path)
  1424. @staticmethod
  1425. def _inbound_original_names(event: MessageEvent) -> dict[str, str]:
  1426. """``{path: original_name}`` for the attachments whose original name the adapter kept."""
  1427. names = getattr(event, "media_filenames", None) or []
  1428. return {p: n for p, n in zip(event.media_urls or [], names) if n}
  1429. @classmethod
  1430. def _prepend_inbound_media_file_notes(
  1431. cls, message_text: str, audio_file_paths: list[str], video_paths: list[str],
  1432. original_names: Optional[dict[str, str]] = None,
  1433. ) -> str:
  1434. """Prepend a path-pointing note per audio-file / video attachment (content is not inlined)."""
  1435. names = original_names or {}
  1436. for kind, noun, verb, tool, paths in (
  1437. ("an audio file attachment", "audio", "transcribe or process", "a transcription or media tool", audio_file_paths),
  1438. ("a video attachment", "video", "inspect or process", "a video analysis or media tool", video_paths),
  1439. ):
  1440. for _path in paths:
  1441. _display, _agent_path = cls._inbound_attachment_display_name(_path, names.get(_path, ""))
  1442. message_text = (
  1443. f"[The user sent {kind}: '{_display}'. "
  1444. f"It is saved at: {_agent_path}. "
  1445. f"Its content is not inlined here. If the user's request involves "
  1446. f"what the {noun} contains, {verb} it yourself — for "
  1447. f"example by passing the path to {tool} — "
  1448. f"instead of asking the user to describe it. Only ask what to do "
  1449. f"with it if their intent is genuinely unclear.]"
  1450. f"\n\n{message_text}"
  1451. )
  1452. return message_text
  1453. @classmethod
  1454. def _prepend_inbound_document_notes(cls, event: MessageEvent, message_text: str) -> str:
  1455. """Prepend a context note per non-media attachment (anything not routed as image/audio/video)."""
  1456. from gateway.run import (
  1457. _build_document_context_note, _event_media_is_audio, _event_media_is_image,
  1458. _event_media_is_video,
  1459. )
  1460. if not event.media_urls:
  1461. return message_text
  1462. import mimetypes as _mimetypes
  1463. _TEXT_EXTENSIONS = {".txt", ".md", ".csv", ".log", ".json", ".xml", ".yaml", ".yml", ".toml", ".ini", ".cfg"}
  1464. inline_flags = getattr(event, "media_text_inlined", None) or []
  1465. names = getattr(event, "media_filenames", None) or []
  1466. for i, path in enumerate(event.media_urls):
  1467. # A document mixed into a PHOTO/VOICE message (message-level type != DOCUMENT) still
  1468. # reaches the agent; only genuine non-media files get a note.
  1469. if any(f(event, i) for f in (_event_media_is_image, _event_media_is_audio, _event_media_is_video)):
  1470. continue
  1471. mtype = event.media_types[i] if i < len(event.media_types) else ""
  1472. if mtype in {"", "application/octet-stream"}:
  1473. _is_text = os.path.splitext(path)[1].lower() in _TEXT_EXTENSIONS
  1474. mtype = "text/plain" if _is_text else (_mimetypes.guess_type(path)[0] or "application/octet-stream")
  1475. # Every accepted file gets a note — a non-text/non-application MIME (font/*, model/*)
  1476. # must still tell the agent the file exists.
  1477. display_name, agent_path = cls._inbound_attachment_display_name(
  1478. path, names[i] if i < len(names) else "")
  1479. inline_flag = inline_flags[i] if i < len(inline_flags) else None
  1480. context_note = _build_document_context_note(
  1481. display_name, agent_path, mtype, content_inlined=inline_flag is not False,
  1482. )
  1483. message_text = f"{context_note}\n\n{message_text}"
  1484. return message_text
  1485. @staticmethod
  1486. def _prepend_inbound_reply_context(event: MessageEvent, source: SessionSource, message_text: str) -> str:
  1487. """Prepend the reply-to pointer, then the Discord triggering-message note (outermost)."""
  1488. if getattr(event, "reply_to_text", None) and event.reply_to_message_id:
  1489. # Always inject the reply-to pointer even when the quoted text is already in history:
  1490. # it's disambiguation (*which* prior message), not deduplication.
  1491. # Adapters resolve the original message (or the user's native partial quote).
  1492. # A preview here silently loses later list items and code; keep that context intact.
  1493. reply_text = event.reply_to_text
  1494. _who = " your previous message" if getattr(event, "reply_to_is_own_message", False) else ""
  1495. message_text = f'[Replying to{_who}: "{reply_text}"]\n\n{message_text}'
  1496. # Discord: the triggering message id goes on the per-turn user message, never the cached
  1497. # system prompt — it changes every turn and would bust the agent-cache signature. It is
  1498. # the OUTERMOST prefix so strip_discord_triggering_note can peel exactly it off the
  1499. # persisted transcript row without touching the reply pointer.
  1500. if (
  1501. source is not None
  1502. and getattr(source, "platform", None) == Platform.DISCORD
  1503. and getattr(event, "message_id", None)
  1504. ):
  1505. from gateway.session import _discord_tools_loaded as _disc_tools_loaded
  1506. if _disc_tools_loaded():
  1507. message_text = f"{discord_triggering_note(event.message_id)}\n\n{message_text}"
  1508. return message_text
  1509. async def _inbound_model_context_length(self, source: SessionSource, session_key: str) -> int:
  1510. """Context length of the model this turn runs on. A global ``model.context_length`` pin
  1511. belongs to the configured model, not a /model or channel override; custom-provider limits win."""
  1512. from gateway.run import _load_gateway_config
  1513. from agent.model_metadata import get_model_context_length_async
  1514. _msg_config_ctx = None
  1515. _msg_cfg = None
  1516. _msg_model_cfg = {}
  1517. _msg_custom_providers = []
  1518. with suppress(Exception):
  1519. _msg_cfg = _load_gateway_config()
  1520. _msg_model_cfg = _msg_cfg.get("model", {})
  1521. if isinstance(_msg_model_cfg, dict):
  1522. _msg_raw_ctx = _msg_model_cfg.get("context_length")
  1523. if _msg_raw_ctx is not None:
  1524. _msg_config_ctx = int(_msg_raw_ctx)
  1525. try:
  1526. from hermes_cli.config import get_compatible_custom_providers
  1527. _msg_custom_providers = get_compatible_custom_providers(_msg_cfg)
  1528. except Exception:
  1529. _msg_custom_providers = _msg_cfg.get("custom_providers") or []
  1530. # GatewayRunner has no self._model/self._base_url; resolve the session's actual runtime.
  1531. _msg_model, _msg_runtime = self._resolve_session_agent_runtime(
  1532. source=source, session_key=session_key, user_config=_msg_cfg,
  1533. )
  1534. _msg_base_url = _msg_runtime.get("base_url") or ""
  1535. if isinstance(_msg_model_cfg, dict):
  1536. _msg_configured_model = _msg_model_cfg.get("default") or _msg_model_cfg.get("model")
  1537. else:
  1538. _msg_configured_model = _msg_model_cfg # (no dict → no pin was read; ctx is already None)
  1539. if _msg_model != _msg_configured_model:
  1540. _msg_config_ctx = None
  1541. if _msg_config_ctx is not None:
  1542. try:
  1543. from hermes_cli.route_identity import should_clear_context_pin_async
  1544. if await should_clear_context_pin_async(
  1545. None, None, # model match already checked above
  1546. _msg_model_cfg.get("base_url"), _msg_base_url,
  1547. _msg_model_cfg.get("provider"), _msg_runtime.get("provider"),
  1548. ):
  1549. _msg_config_ctx = None
  1550. except Exception:
  1551. _msg_config_ctx = None
  1552. if _msg_custom_providers and _msg_base_url:
  1553. with suppress(Exception):
  1554. from hermes_cli.config import get_custom_provider_context_length
  1555. _msg_config_ctx = get_custom_provider_context_length(
  1556. model=_msg_model, base_url=_msg_base_url, custom_providers=_msg_custom_providers,
  1557. ) or _msg_config_ctx
  1558. return await get_model_context_length_async(
  1559. _msg_model, base_url=_msg_base_url, api_key=_msg_runtime.get("api_key") or "",
  1560. config_context_length=_msg_config_ctx, provider=_msg_runtime.get("provider") or "",
  1561. custom_providers=_msg_custom_providers,
  1562. )
  1563. async def _expand_inbound_context_references(
  1564. self, source: SessionSource, session_key: str, message_text: str
  1565. ) -> Optional[str]:
  1566. """Expand ``@`` context references; returns None when the injection was refused (user notified)."""
  1567. from gateway.session_context_refs import inbound_references
  1568. expanded, refusal = await inbound_references(self, source, session_key, message_text)
  1569. if refusal is None:
  1570. return expanded
  1571. from gateway.bot_peer_notices import automatic_notices_allowed
  1572. _adapter = self._delivery_adapter_for(source) if automatic_notices_allowed(source) else None
  1573. if _adapter:
  1574. await _adapter.send(source.chat_id, refusal)
  1575. return None
  1576. async def _prepare_inbound_message_text(
  1577. self, *, event: MessageEvent, source: SessionSource, history: list[dict[str, Any]],
  1578. session_key: Optional[str] = None,
  1579. ) -> Optional[str]:
  1580. """Prepare inbound event text for the agent. Shared by the normal inbound and queued
  1581. follow-up paths so attribution, image enrichment, STT, document notes, reply context and
  1582. @ references behave the same. Side effect: buffers per-session native image paths when the
  1583. model supports native vision; the caller consumes that buffer at ``run_conversation``."""
  1584. rehome_inbound_media(event) # before any consumer (vision, STT, document notes) reads media_urls
  1585. _pending_stt_prepared = hasattr(event, "_gateway_pending_stt_text")
  1586. message_text = (event._gateway_pending_stt_text if _pending_stt_prepared else event.text) or ""
  1587. # Prefer the caller's resolved session key so this write key matches the consume key at the
  1588. # run_conversation site; derive it here only for tests and legacy standalone callers.
  1589. session_key = session_key or self._session_key_for_source(source)
  1590. # Reset only this session's per-call buffer; other sessions may be concurrently preparing.
  1591. self._consume_pending_native_image_paths(session_key)
  1592. message_text = self._prefix_inbound_sender_context(event, source, message_text)
  1593. image_paths, audio_paths, audio_file_paths, video_paths = self._classify_inbound_media(event, _pending_stt_prepared)
  1594. if image_paths:
  1595. message_text = await self._enrich_inbound_images(source, session_key, message_text, image_paths)
  1596. if audio_paths:
  1597. message_text = await self._enrich_inbound_voice(event, source, message_text, audio_paths)
  1598. message_text = self._prepend_inbound_media_file_notes(
  1599. message_text, audio_file_paths, video_paths, self._inbound_original_names(event))
  1600. message_text = self._prepend_inbound_document_notes(event, message_text)
  1601. from gateway.session_context_refs import turn_references
  1602. message_text = await turn_references(self, event, source, session_key, message_text)
  1603. if message_text is None:
  1604. return None
  1605. # After expansion: the quoted reply is someone else's text and stays literal — an
  1606. # ``@file:`` inside it must never read a local file on the replier's behalf.
  1607. return self._prepend_inbound_reply_context(event, source, message_text)
  1608. async def _prepare_profile_scoped_inbound_message_text(
  1609. self, *, event: MessageEvent, source: SessionSource, history: list[dict[str, Any]],
  1610. session_key: Optional[str] = None,
  1611. ) -> Optional[str]:
  1612. """Run inbound preprocessing under the routed profile when multiplexed."""
  1613. from gateway.run import _async_profile_runtime_scope
  1614. kwargs = dict(event=event, source=source, history=history, session_key=session_key)
  1615. if getattr(getattr(self, "config", None), "multiplex_profiles", False):
  1616. async with _async_profile_runtime_scope(self._resolve_profile_home_for_source(source)):
  1617. return await self._prepare_inbound_message_text(**kwargs)
  1618. return await self._prepare_inbound_message_text(**kwargs)
  1619. async def _prepare_clarify_reply_text(self, event) -> str:
  1620. """Return raw text or successful voice transcripts for a clarify reply."""
  1621. if not self._pending_event_audio_paths(event):
  1622. return (event.text or "").strip()
  1623. _, successful_transcripts = await self._transcribe_pending_audio_event_once(event, "")
  1624. return "\n\n".join(t.strip() for t in successful_transcripts if t.strip())
  1625. def _consume_pending_native_image_paths(self, session_key: str) -> list[str]:
  1626. state = self._peek_session_state(session_key)
  1627. paths = list(state.persistent.native_image_paths or []) if state is not None else []
  1628. if paths:
  1629. state.persistent.native_image_paths = []
  1630. return paths
  1631. async def _mark_durable_active_turn(self, event: MessageEvent, session_key: str) -> bool:
  1632. """Persist the exact resolved routing key for this running turn."""
  1633. try:
  1634. token = await self.async_session_store.mark_turn_active(session_key)
  1635. except Exception as exc:
  1636. logger.warning("Could not persist active-turn marker for %s: %s", session_key, exc)
  1637. return False
  1638. if not token:
  1639. return False
  1640. # Private event attributes are process-local ownership state: keep the token out of public
  1641. # metadata, transcripts, and platform payloads.
  1642. event._gateway_active_turn_session_key = session_key
  1643. event._gateway_active_turn_token = token
  1644. return True
  1645. async def _clear_durable_active_turn(self, event: MessageEvent) -> bool:
  1646. """Best-effort CAS clear of the marker owned by *event* (3 attempts; never blocks agent/lease
  1647. release — a stale marker is bounded by the agent timeout and clean-start discard)."""
  1648. session_key = getattr(event, "_gateway_active_turn_session_key", None)
  1649. token = getattr(event, "_gateway_active_turn_token", None)
  1650. try:
  1651. if not session_key or not token:
  1652. return False
  1653. last_error: Optional[Exception] = None
  1654. for attempt in range(1, 4):
  1655. try:
  1656. return bool(await self.async_session_store.clear_turn_active(session_key, token))
  1657. except Exception as exc:
  1658. last_error = exc
  1659. if attempt < 3:
  1660. logger.debug(
  1661. "Retrying active-turn marker cleanup for %s (%d/3): %s",
  1662. session_key, attempt, exc,
  1663. )
  1664. logger.warning(
  1665. "Could not clear active-turn marker for %s after 3 attempts: %s", session_key, last_error,
  1666. )
  1667. return False
  1668. finally:
  1669. for attr in ("_gateway_active_turn_session_key", "_gateway_active_turn_token"):
  1670. with suppress(AttributeError):
  1671. delattr(event, attr)
  1672. def _decide_image_input_mode(
  1673. self, *, source: Optional[SessionSource] = None, session_key: Optional[str] = None,
  1674. user_config: Optional[dict] = None, provider: Optional[str] = None,
  1675. model: Optional[str] = None,
  1676. ) -> str:
  1677. """Resolve image-input routing (``"native"`` / ``"text"``) for the effective model this turn
  1678. (see agent/image_routing.py). Sessions can carry /model overrides and this runs before AIAgent
  1679. sets the auxiliary_client runtime globals, so resolve the per-session runtime bundle the
  1680. upcoming turn will use, not just the persisted default."""
  1681. try:
  1682. from agent.image_routing import decide_image_input_mode
  1683. from agent.auxiliary_client import _read_main_model, _read_main_provider
  1684. from hermes_cli.config import load_config
  1685. cfg = user_config if isinstance(user_config, dict) else load_config()
  1686. resolved_provider = (provider or "").strip()
  1687. resolved_model = (model or "").strip()
  1688. resolved_requested_provider = ""
  1689. if (not resolved_provider or not resolved_model) and (source is not None or session_key):
  1690. try:
  1691. turn_model, runtime_kwargs = self._resolve_session_agent_runtime(
  1692. source=source, session_key=session_key, user_config=cfg,
  1693. )
  1694. rk = runtime_kwargs if isinstance(runtime_kwargs, dict) else {}
  1695. if not resolved_model and isinstance(turn_model, str):
  1696. resolved_model = turn_model.strip()
  1697. if not resolved_provider and isinstance(rk.get("provider"), str):
  1698. resolved_provider = rk["provider"].strip()
  1699. if isinstance(rk.get("requested_provider"), str):
  1700. resolved_requested_provider = rk["requested_provider"].strip()
  1701. except Exception as exc:
  1702. logger.debug(
  1703. "image_routing: session runtime resolution failed, falling back to config — %s",
  1704. exc,
  1705. )
  1706. return decide_image_input_mode(
  1707. resolved_provider or _read_main_provider(), resolved_model or _read_main_model(),
  1708. cfg, requested_provider=resolved_requested_provider,
  1709. )
  1710. except Exception as exc:
  1711. logger.debug("image_routing: decision failed, falling back to text — %s", exc)
  1712. return "text"
  1713. async def _enrich_message_with_vision(self, user_text: str, image_paths: list[str]) -> str:
  1714. """Auto-analyze user-attached images with the vision tool and prepend the descriptions.
  1715. Description *and* local cache path are injected so the model understands the image without
  1716. a tool call and can re-examine it with vision_analyze."""
  1717. from tools.vision_tools import vision_analyze_tool
  1718. from agent.memory_context import sanitize_context
  1719. analysis_prompt = (
  1720. "Concisely describe this image in 2-4 sentences "
  1721. "(~200 Chinese characters or ~150 English words). "
  1722. "Cover the main subject, key visible text/data/code, and overall context. "
  1723. "If it is a chart, diagram, or scientific figure, include the important "
  1724. "labels, legend, and key values. Skip decorative details."
  1725. )
  1726. enriched_parts = []
  1727. for path in image_paths:
  1728. try:
  1729. logger.debug("Auto-analyzing user image: %s", path)
  1730. result = json.loads(await vision_analyze_tool(image_url=path, user_prompt=analysis_prompt))
  1731. if result.get("success"):
  1732. description = sanitize_context(result.get("analysis", ""))
  1733. note = (
  1734. f"[The user sent an image~ Here's what I can see:\n{description}]\n"
  1735. f"[If you need a closer look, use vision_analyze with "
  1736. f"image_url: {path} ~]"
  1737. )
  1738. else:
  1739. note = (
  1740. "[The user sent an image but I couldn't quite see it "
  1741. "this time (>_<) You can try looking at it yourself "
  1742. f"with vision_analyze using image_url: {path}]"
  1743. )
  1744. except Exception as e:
  1745. logger.error("Vision auto-analysis error: %s", e)
  1746. note = (
  1747. f"[The user sent an image but something went wrong when I "
  1748. f"tried to look at it~ You can try examining it yourself "
  1749. f"with vision_analyze using image_url: {path}]"
  1750. )
  1751. enriched_parts.append(note)
  1752. if not enriched_parts:
  1753. return user_text
  1754. prefix = "\n\n".join(enriched_parts)
  1755. return f"{prefix}\n\n{user_text}" if user_text else prefix