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