ouyangbo/hermes-agent
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity
Files
cf60ebbdfd264c3fc067b9e3230df8752c50d2ec
hermes-agent/gateway/platforms/base.py
T

5349 lines
245 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Base platform adapter interface; every platform adapter inherits from BasePlatformAdapter."""
import asyncio
import inspect
import ipaddress
import logging
import os
import random
import re
import socket as _socket
import subprocess
import sys
import tempfile
import threading
import time
import uuid
import weakref
from abc import ABC, abstractmethod
from urllib.parse import urlsplit
from utils import normalize_proxy_url
logger = logging.getLogger(__name__)
def _consume_detached_handler_exception(task: "asyncio.Task") -> None:
"""Done-callback retrieving a detached fatal-error handler's exception, so handler
tasks left running after their carrier was cancelled (``_notify_fatal_error``)
never log "Task exception was never retrieved"."""
if task.cancelled():
return
exc = task.exception()
if exc is not None:
logger.error("Detached fatal-error handler task failed: %s", exc, exc_info=exc)
# Audio file extensions Hermes recognizes for native audio delivery.
# Keep Telegram's narrower attachment/voice sets below separate: formats such
# as MPEG-2 Layer II are audio to Hermes but unsupported by sendAudio/sendVoice.
_AUDIO_MIME_TYPES = {
".ogg": "audio/ogg", ".opus": "audio/opus", ".mp3": "audio/mpeg", ".m2a": "audio/mpeg",
".wav": "audio/wav", ".m4a": "audio/m4a", ".flac": "audio/flac",
}
_AUDIO_EXTS = frozenset(_AUDIO_MIME_TYPES)
# Outbound dispatch partition for MEDIA/local files (image batch vs send_video).
_VIDEO_EXTS = frozenset({".mp4", ".mov", ".avi", ".mkv", ".webm", ".3gp"})
_IMAGE_EXTS = frozenset({".jpg", ".jpeg", ".png", ".webp", ".gif"})
# Telegram sendAudio only accepts MP3 / M4A; other formats go through sendVoice
# (Opus/OGG) or are delivered as a regular document.
_TELEGRAM_AUDIO_ATTACHMENT_EXTS = frozenset({'.mp3', '.m4a'})
_TELEGRAM_VOICE_EXTS = frozenset({'.ogg', '.opus'})
def transcode_to_ogg_opus(path: str, *, bitrate: str = "32k") -> "str | None":
"""Best-effort ffmpeg transcode to Ogg/Opus (voip-tuned) for native voice bubbles.
Returns a NEW temp ``.ogg`` path (caller owns cleanup), or ``None`` when ffmpeg is
missing/fails so callers keep their document fallback. Blocking — use ``asyncio.to_thread``.
"""
import shutil as _shutil
import subprocess as _subprocess
import tempfile as _tempfile
ffmpeg = _shutil.which("ffmpeg")
if not ffmpeg:
return None
fd, ogg_path = _tempfile.mkstemp(prefix="voice_transcode_", suffix=".ogg")
os.close(fd)
try:
result = _subprocess.run(
[ffmpeg, "-v", "error", "-y", "-i", str(path),
"-acodec", "libopus", "-ac", "1", "-b:a", bitrate, "-vbr", "on",
"-application", "voip", "-compression_level", "10", ogg_path],
capture_output=True, timeout=60, stdin=_subprocess.DEVNULL,
)
if result.returncode == 0 and os.path.getsize(ogg_path) > 0:
return ogg_path
except Exception:
logger.debug("voice transcode to Ogg/Opus failed for %s", path, exc_info=True)
try:
os.unlink(ogg_path)
except OSError:
pass
return None
_POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS = 30.0
# Delivery-time history is best-effort dedup metadata, not canonical state.
# Keep this comfortably below the Discord heartbeat watchdog window and fail
# open rather than withholding a legitimate attachment.
_HISTORY_MEDIA_LOOKUP_TIMEOUT_SECONDS = 5.0
# Timed-out reads can't be cancelled mid-SQLite; isolate and cap them so wedged
# best-effort dedup work can't consume the shared executor or spawn unbounded threads.
_HISTORY_MEDIA_LOOKUP_MAX_WORKERS = 2
_HISTORY_MEDIA_LOOKUP_ADMISSION = threading.BoundedSemaphore(_HISTORY_MEDIA_LOOKUP_MAX_WORKERS)
def _platform_name(platform) -> str:
"""Normalize a Platform enum / raw string into a lowercase name."""
value = getattr(platform, "value", platform)
return str(value or "").lower()
def _float_env(name: str, default: float) -> float:
raw = os.environ.get(name, "").strip()
if not raw:
return default
try:
return float(raw)
except (TypeError, ValueError):
return default
def _thread_metadata_for_source(source, reply_to_message_id: str | None = None) -> dict | None:
"""Build platform-aware thread metadata for adapter sends.
Telegram DM topics route with ``message_thread_id`` + a reply anchor; synthetic/resumed
sends without an anchor fall back to ``direct_messages_topic_id`` when supported.
"""
thread_id = getattr(source, "thread_id", None)
metadata = {"thread_id": thread_id} if thread_id is not None else {}
# Slack workspace identity is durable routing state: carry it on every outbound path
# so a multi-workspace Socket Mode gateway never falls back to its primary WebClient.
if _platform_name(getattr(source, "platform", None)) == "slack":
scope_id = getattr(source, "scope_id", None)
if scope_id:
metadata["slack_team_id"] = str(scope_id)
if not metadata:
return None
if _platform_name(getattr(source, "platform", None)) == "telegram" and getattr(source, "chat_type", None) == "dm":
metadata["telegram_dm_topic_reply_fallback"] = True
tid = str(thread_id)
if tid and tid not in {"", "1"}:
metadata["direct_messages_topic_id"] = tid
anchor = reply_to_message_id or getattr(source, "message_id", None)
if anchor is not None:
metadata["telegram_reply_to_message_id"] = str(anchor)
# Routed profile for shared state.db namespaces (multiplex / profile_routes);
# outbound prune paths must not assume the adapter's static profile stamp.
profile = str(getattr(source, "profile", None) or "").strip()
if profile:
metadata["hermes_profile"] = profile
return metadata
def _mark_notify_metadata(metadata: dict | None) -> dict:
"""Clone metadata and mark a user-visible reply as notify-worthy."""
notify_metadata = dict(metadata) if metadata else {}
notify_metadata["notify"] = True
return notify_metadata
def _reply_anchor_for_event(event) -> str | None:
"""Return reply_to id for platforms that need reply semantics.
Telegram forum topics route by topic metadata (no reply); Hermes DM-topic lanes
reply to the triggering user message so the answer stays in the active lane.
"""
source = getattr(event, "source", None)
platform = _platform_name(getattr(source, "platform", None))
thread_id = getattr(source, "thread_id", None)
raw_message = getattr(event, "raw_message", None)
if (
platform == "slack"
and isinstance(raw_message, dict)
and raw_message.get("_hermes_no_thread_response")
):
# Slack reaction handoffs create a new top-level message in the target channel;
# returning message_id would make _resolve_thread_ts() reply in a nonexistent thread.
return None
if platform == "telegram" and thread_id and getattr(source, "chat_type", None) == "dm":
# Reply to the triggering user message. Replying to Telegram's earlier
# topic seed/anchor can render the bot response outside the active lane.
return getattr(event, "message_id", None) or getattr(event, "reply_to_message_id", None)
if platform == "telegram" and thread_id:
return None
if platform == "feishu" and thread_id and getattr(event, "reply_to_message_id", None):
return getattr(event, "reply_to_message_id", None)
return getattr(event, "message_id", None)
def _media_failure_text(kind: str, file_name: "str | None" = None) -> str:
"""User-facing "couldn't deliver" notice; ``file_name`` is the only name ever shown."""
suffix = f" ({file_name})" if file_name else ""
return f"⚠️ Couldn't deliver the {kind} attachment{suffix}."
def should_send_media_as_audio(platform, ext: str, is_voice: bool = False) -> bool:
"""Return True when a media file should use the platform's audio sender.
Telegram: sendAudio takes only MP3/M4A and sendVoice only Opus/OGG; Opus/OGG is
routed as audio only with ``is_voice=True`` (never turn a plain attachment into a
voice bubble), everything else returns False → document delivery. Other platforms:
any recognized audio extension.
"""
normalized_ext = (ext or "").lower()
if normalized_ext not in _AUDIO_EXTS:
return False
if _platform_name(platform) == "telegram":
if is_voice:
# Explicit [[audio_as_voice]] intent: ANY format routes to the voice sender;
# the adapter transcodes non-Opus input via transcode_to_ogg_opus.
return True
if normalized_ext in _TELEGRAM_VOICE_EXTS:
return is_voice
return normalized_ext in _TELEGRAM_AUDIO_ATTACHMENT_EXTS
return True
def build_auto_tts_output_path(platform) -> str:
"""Return a unique temp output path for gateway auto-TTS synthesis.
Platform-awareness lives HERE, not in the TTS tool's ``HERMES_SESSION_PLATFORM``
contextvar: ``_clear_session_env`` clears that before the post-handler auto-TTS block
runs, so relying on it always produced MP3. ``OPUS_VOICE_PLATFORMS`` (single source of
truth) get ``.ogg``; the tool's ``_repair_ogg_container`` then guarantees real Opus bytes.
"""
from tools.tts_tool import OPUS_VOICE_PLATFORMS
ext = "ogg" if _platform_name(platform) in OPUS_VOICE_PLATFORMS else "mp3"
audio_path = os.path.join(
tempfile.gettempdir(),
"hermes_voice",
f"tts_reply_{uuid.uuid4().hex[:12]}.{ext}",
)
os.makedirs(os.path.dirname(audio_path), exist_ok=True)
return audio_path
def utf16_len(s: str) -> int:
"""Count UTF-16 code units in *s*.
Telegram's 4 096 limit counts UTF-16 code units: astral characters (emoji, CJK Ext B)
are surrogate pairs and cost **two** units although Python's ``len()`` counts one.
"""
return len(s.encode("utf-16-le")) // 2
def _custom_unit_to_cp(s: str, budget: int, len_fn) -> int:
"""Largest codepoint offset *n* with ``len_fn(s[:n]) <= budget`` (binary search)."""
if len_fn(s) <= budget:
return len(s)
lo, hi = 0, len(s)
while lo < hi:
mid = (lo + hi + 1) // 2
if len_fn(s[:mid]) <= budget:
lo = mid
else:
hi = mid - 1
return lo
def _prefix_within_utf16_limit(s: str, limit: int) -> str:
"""Longest prefix of *s* with UTF-16 length ≤ *limit*; never splits a surrogate pair."""
return s[:_custom_unit_to_cp(s, limit, utf16_len)]
def is_network_accessible(host: str) -> bool:
"""Return True if *host* would expose the server beyond loopback.
Loopback (incl. IPv4-mapped ::ffff:127.0.0.1) is local-only; 0.0.0.0 / :: bind all
interfaces. Hostnames are resolved; DNS failure fails closed (True).
"""
try:
addr = ipaddress.ip_address(host)
if addr.is_loopback:
return False
# ::ffff:127.0.0.1 reports is_loopback=False; check the mapped IPv4 explicitly.
return not (getattr(addr, "ipv4_mapped", None) and addr.ipv4_mapped.is_loopback)
except ValueError:
pass # hostname — resolve below
try:
resolved = _socket.getaddrinfo(host, None, _socket.AF_UNSPEC, _socket.SOCK_STREAM)
# Network-accessible if any resolved address is non-loopback.
for _family, _type, _proto, _canonname, sockaddr in resolved:
addr = ipaddress.ip_address(sockaddr[0])
if not addr.is_loopback:
return True
return False
except (_socket.gaierror, OSError):
return True
def _detect_macos_system_proxy() -> str | None:
"""Read the macOS system HTTP(S) proxy via ``scutil --proxy``: ``http://host:port``
when an HTTP(S) proxy is enabled, else None (non-macOS or any subprocess error)."""
if sys.platform != "darwin":
return None
try:
out = subprocess.check_output(
["scutil", "--proxy"], timeout=3, text=True, encoding='utf-8', errors='replace', stderr=subprocess.DEVNULL,
)
except Exception:
return None
props: dict[str, str] = {}
for line in out.splitlines():
line = line.strip()
if " : " in line:
key, _, val = line.partition(" : ")
props[key.strip()] = val.strip()
# Prefer HTTPS, fall back to HTTP
for enable_key, host_key, port_key in (
("HTTPSEnable", "HTTPSProxy", "HTTPSPort"),
("HTTPEnable", "HTTPProxy", "HTTPPort"),
):
if props.get(enable_key) == "1":
host = props.get(host_key)
port = props.get(port_key)
if host and port:
return f"http://{host}:{port}"
return None
def _split_host_port(value: str) -> tuple[str, int | None]:
raw = str(value or "").strip()
if not raw:
return "", None
if "://" in raw:
parsed = urlsplit(raw)
return (parsed.hostname or "").lower().rstrip("."), parsed.port
if raw.startswith("[") and "]" in raw:
host, _, rest = raw[1:].partition("]")
port = None
if rest.startswith(":") and rest[1:].isdigit():
port = int(rest[1:])
return host.lower().rstrip("."), port
if raw.count(":") == 1:
host, _, maybe_port = raw.rpartition(":")
if maybe_port.isdigit():
return host.lower().rstrip("."), int(maybe_port)
return raw.lower().strip("[]").rstrip("."), None
def _no_proxy_entries() -> list[str]:
entries: list[str] = []
for key in ("NO_PROXY", "no_proxy"):
raw = os.environ.get(key, "")
entries.extend(part.strip() for part in raw.split(",") if part.strip())
return entries
def _no_proxy_entry_matches(entry: str, host: str, port: int | None = None) -> bool:
token = str(entry or "").strip().lower()
if not token:
return False
if token == "*":
return True
token_host, token_port = _split_host_port(token)
if token_port is not None and port is not None and token_port != port:
return False
if token_port is not None and port is None:
return False
if not token_host:
return False
try:
network = ipaddress.ip_network(token_host, strict=False)
try:
return ipaddress.ip_address(host) in network
except ValueError:
return False
except ValueError:
pass
try:
token_ip = ipaddress.ip_address(token_host)
try:
return ipaddress.ip_address(host) == token_ip
except ValueError:
return False
except ValueError:
pass
if token_host.startswith("*."):
suffix = token_host[1:]
return host.endswith(suffix)
if token_host.startswith("."):
return host == token_host[1:] or host.endswith(token_host)
return host == token_host or host.endswith(f".{token_host}")
def should_bypass_proxy(target_hosts: str | list[str] | tuple[str, ...] | set[str] | None) -> bool:
"""Return True when NO_PROXY/no_proxy matches at least one target host.
Supports exact hosts, domain suffixes, wildcard suffixes, IP literals,
CIDR ranges, optional host:port entries, and ``*``.
"""
entries = _no_proxy_entries()
if not entries or not target_hosts:
return False
candidates = [target_hosts] if isinstance(target_hosts, str) else list(target_hosts)
for candidate in candidates:
host, port = _split_host_port(str(candidate))
if not host:
continue
if any(_no_proxy_entry_matches(entry, host, port) for entry in entries):
return True
return False
def resolve_proxy_url(
platform_env_var: str | None = None,
*,
target_hosts: str | list[str] | tuple[str, ...] | set[str] | None = None,
) -> str | None:
"""Return a proxy URL: *platform_env_var* (e.g. ``DISCORD_PROXY``) first, then
HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (any case), then the macOS system proxy.
None when nothing is found or NO_PROXY matches a ``target_hosts`` entry. The generic
env and system steps are skipped when ``gateway.trust_env`` is false (:func:`gateway_trust_env`).
"""
if platform_env_var:
value = (os.environ.get(platform_env_var) or "").strip()
if value:
if should_bypass_proxy(target_hosts):
return None
return normalize_proxy_url(value)
if not gateway_trust_env():
# trust_env false: only the explicit per-platform var above is honored.
return None
for key in ("HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY", "https_proxy", "http_proxy", "all_proxy"):
value = (os.environ.get(key) or "").strip()
if value:
if should_bypass_proxy(target_hosts):
return None
return normalize_proxy_url(value)
detected = normalize_proxy_url(_detect_macos_system_proxy())
if detected and should_bypass_proxy(target_hosts):
return None
return detected
def _aiohttp_socks_connector(proxy_url: str):
"""``aiohttp_socks.ProxyConnector`` for ``proxy_url``, or None when aiohttp_socks is
missing (SOCKS then logs a warning; HTTP callers fall back to ``proxy=``).
``rdns=True`` forces remote DNS through the proxy — required by many SOCKS
implementations (Shadowrocket, Clash) and essential against GFW DNS pollution."""
try:
from aiohttp_socks import ProxyConnector
return ProxyConnector.from_url(proxy_url, rdns=True)
except ImportError:
if proxy_url.lower().startswith("socks"):
logger.warning(
"aiohttp_socks not installed — SOCKS proxy %s ignored. "
"Run: pip install aiohttp-socks",
proxy_url,
)
return None
def proxy_kwargs_for_bot(proxy_url: str | None) -> dict:
"""Kwargs for ``commands.Bot()`` / ``discord.Client()``: SOCKS → ``{"connector"}``,
HTTP → ``{"proxy": url}``, None → ``{}``."""
if not proxy_url:
return {}
if proxy_url.lower().startswith("socks"):
connector = _aiohttp_socks_connector(proxy_url)
return {"connector": connector} if connector is not None else {}
return {"proxy": proxy_url}
def _config_section(name: str) -> dict:
"""Read-only ``config.yaml`` section ``name``; ``{}`` when unreadable/missing/not a dict."""
try:
from hermes_cli.config import load_config_readonly as _load_config
cfg = _load_config() # read-only: .get() only, never mutated
except Exception:
return {}
section = cfg.get(name) if isinstance(cfg, dict) else None
return section if isinstance(section, dict) else {}
def gateway_trust_env() -> bool:
"""``gateway.trust_env`` from config.yaml (default True): whether gateway
``aiohttp.ClientSession``s honor HTTP(S)_PROXY / NO_PROXY / SSL_CERT_FILE. Set false
when the gateway inherits a proxy env it must not use. Fail-open to default."""
value = _config_section("gateway").get("trust_env", True)
if isinstance(value, str):
return value.strip().lower() not in {"0", "false", "no", "off"}
return bool(value) if value is not None else True
def proxy_kwargs_for_aiohttp(proxy_url: str | None) -> tuple[dict, dict]:
"""``(session_kwargs, request_kwargs)`` for a standalone ``aiohttp.ClientSession``.
With aiohttp-socks every scheme uses a connector (libraries like mautrix never forward
per-request ``proxy=``); without it HTTP falls back to ``({}, {"proxy": url})``, SOCKS is ignored."""
if not proxy_url:
return {}, {}
connector = _aiohttp_socks_connector(proxy_url)
if connector is not None:
return {"connector": connector}, {}
if proxy_url.lower().startswith("socks"):
return {}, {}
return {}, {"proxy": proxy_url}
def is_host_excluded_by_no_proxy(hostname: str, no_proxy_value: str | None = None) -> bool:
"""Return True when ``hostname`` matches a ``NO_PROXY`` entry (comma/whitespace
separated; leading-dot and ``*.`` entries match the apex domain and subdomains)."""
raw = no_proxy_value
if raw is None:
raw = os.environ.get("NO_PROXY") or os.environ.get("no_proxy") or ""
raw = raw.strip()
if not raw:
return False
lower_hostname = hostname.lower()
for entry in re.split(r"[\s,]+", raw):
normalized = entry.strip().lower()
if not normalized:
continue
if normalized == "*":
return True
if normalized.startswith("*."):
normalized = normalized[2:]
elif normalized.startswith("."):
normalized = normalized[1:]
if lower_hostname == normalized or lower_hostname.endswith(f".{normalized}"):
return True
return False
import dataclasses
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Dict, List, Optional, Any, Callable, Awaitable, Tuple, Union
from enum import Enum
from pathlib import Path as _Path
sys.path.insert(0, str(_Path(__file__).resolve().parents[2]))
from gateway.config import Platform, PlatformConfig
from gateway.platforms.helpers import fence_state_after
from gateway.session import SessionSource, build_session_key
from hermes_constants import get_default_hermes_root, get_hermes_dir, get_hermes_home
if TYPE_CHECKING:
from agent.display import ToolPreview
# --- Streaming TTS format descriptor and handle ---
@dataclass
class AudioFormat:
"""Declared PCM format for a streaming-TTS session: every ``write_streaming_tts``
chunk must be raw little-endian PCM at this rate / channels / sample width."""
sample_rate: int = 24000
channels: int = 1
sample_width: int = 2 # bytes per sample (int16 = 2)
@dataclass
class StreamingTTSHandle:
"""Opaque handle returned by ``begin_streaming_tts``; adapters may extend it with
platform state. The base fields are consumer bookkeeping / cancellation."""
chat_id: str = ""
audio_format: AudioFormat = field(default_factory=AudioFormat)
# True once the first PCM chunk is written: a later failure then ends cleanly
# instead of falling back to whole-file TTS (don't replay already-audible output).
audible: bool = False
# Set to True by abort_streaming_tts; late chunks are dropped.
aborted: bool = False
def streaming_tts_turn_key(session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> str | None:
"""Per-turn streaming-TTS suppression key — turn-scoped (not chat-scoped) so
overlapping turns in one chat can't suppress each other's fallback paths.
``turn_marker`` is normally the run generation, else the event's message/update id."""
if not session_key:
return None
if turn_marker is None and event is not None:
turn_marker = getattr(event, "message_id", None) or getattr(event, "platform_update_id", None)
if turn_marker is None:
return None
return f"{session_key}:{turn_marker}"
def streaming_tts_should_skip_whole_file(
completed_turns: set[str],
session_key: str | None,
turn_marker: Any = None,
*,
event: Any = None,
) -> bool:
"""Pure, turn-scoped auto-TTS suppression decision (testable without the adapter stack)."""
turn_key = streaming_tts_turn_key(session_key, turn_marker, event=event)
return bool(turn_key and turn_key in completed_turns)
GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE = (
"Secure secret entry is not supported over messaging. "
"Load this skill in the local CLI to be prompted, or add the key to ~/.hermes/.env manually."
)
def safe_url_for_log(url: str, max_len: int = 80) -> str:
"""Return a URL string safe for logs (no query/fragment/userinfo)."""
if max_len <= 0:
return ""
if url is None:
return ""
raw = str(url)
if not raw:
return ""
try:
parsed = urlsplit(raw)
except Exception:
return raw[:max_len]
if parsed.scheme and parsed.netloc:
# Strip potential embedded credentials (user:pass@host).
netloc = parsed.netloc.rsplit("@", 1)[-1]
base = f"{parsed.scheme}://{netloc}"
path = parsed.path or ""
if path and path != "/":
basename = path.rsplit("/", 1)[-1]
safe = f"{base}/.../{basename}" if basename else f"{base}/..."
else:
safe = base
else:
safe = raw
if len(safe) <= max_len:
return safe
if max_len <= 3:
return "." * max_len
return f"{safe[:max_len - 3]}..."
async def _ssrf_redirect_guard(response):
"""Re-validate each redirect target: a public URL that 302-redirects to
http://169.254.169.254/ would otherwise bypass the pre-flight is_safe_url() check.
Async because httpx.AsyncClient awaits response event hooks."""
from tools.url_safety import is_safe_url, redirect_target_from_response
redirect_url = redirect_target_from_response(response)
if redirect_url and not is_safe_url(redirect_url):
raise ValueError(f"Blocked redirect to private/internal address: {safe_url_for_log(redirect_url)}")
# Image cache utilities: inbound images are downloaded to a local cache so the
# vision tool can read them by path (platform URLs are ephemeral, e.g. Telegram ~1h).
# Import-time default. Tests monkeypatch this; the get_*_cache_dir() getters
# re-resolve per call so the active profile override is honored.
IMAGE_CACHE_DIR = get_hermes_dir("cache/images", "image_cache")
def _resolve_cache_dir(constant_name: str, new_subpath: str, old_name: str) -> Path:
"""Resolve fresh via get_hermes_dir (active profile) unless a test monkeypatched
the module constant away from its import-time default; create the directory."""
d = get_hermes_dir(new_subpath, old_name)
current = globals().get(constant_name)
default = _CACHE_DIR_IMPORT_DEFAULTS.get(constant_name)
if current is not None and default is not None and current != default:
d = Path(current)
d.mkdir(parents=True, exist_ok=True)
return d
# Inbound media size cap. Inbound payloads are buffered fully in memory before
# hitting the cache, so an uncapped upload (Discord Nitro: 500 MB) or a remote URL
# to a huge file can OOM-kill the gateway. Enforced in ``cache_*_from_bytes`` (the
# shared funnel) and the ``cache_*_from_url`` downloaders, independent of adapter.
# ``gateway.max_inbound_media_bytes`` configures it; ``0`` disables. Default 128 MiB.
DEFAULT_INBOUND_MEDIA_MAX_BYTES = 128 * 1024 * 1024
def get_inbound_media_max_bytes() -> int:
"""Max inbound media bytes held in memory (``gateway.max_inbound_media_bytes``);
``0`` / negative / unparseable disables the cap; unreadable config → default."""
gw = _config_section("gateway")
if "max_inbound_media_bytes" not in gw:
return DEFAULT_INBOUND_MEDIA_MAX_BYTES
try:
return int(gw["max_inbound_media_bytes"])
except (TypeError, ValueError):
return DEFAULT_INBOUND_MEDIA_MAX_BYTES
def validate_inbound_media_size(
size: int,
*,
media_type: str = "media",
max_bytes: Optional[int] = None,
) -> None:
"""Raise ``ValueError`` if an inbound payload exceeds the cap (``max_bytes`` of ``0``
disables it; pass it explicitly to resolve the limit once across an incremental read)."""
limit = get_inbound_media_max_bytes() if max_bytes is None else max_bytes
if limit and size > limit:
raise ValueError(f"Inbound {media_type} payload is too large ({size} bytes > {limit} bytes)")
async def _read_httpx_body_with_limit(response, *, media_type: str) -> bytes:
"""Read an httpx streaming body under the media cap: reject an oversized
``Content-Length`` early, then re-check the running total per chunk so a
lying/absent header can't smuggle an unbounded body past the cap."""
max_bytes = get_inbound_media_max_bytes()
content_length = response.headers.get("content-length")
if content_length:
try:
declared_size = int(content_length)
except ValueError:
logger.debug("Ignoring invalid Content-Length for inbound %s: %r", media_type, content_length)
else:
validate_inbound_media_size(declared_size, media_type=media_type, max_bytes=max_bytes)
chunks: list[bytes] = []
total = 0
async for chunk in response.aiter_bytes():
total += len(chunk)
validate_inbound_media_size(total, media_type=media_type, max_bytes=max_bytes)
chunks.append(chunk)
return b"".join(chunks)
def get_image_cache_dir() -> Path:
"""Return the image cache directory, creating it if it doesn't exist."""
return _resolve_cache_dir("IMAGE_CACHE_DIR", "cache/images", "image_cache")
def _looks_like_image(data: bytes) -> bool:
"""Return True if *data* starts with a known image magic-byte sequence."""
if len(data) < 4:
return False
return (
data[:8] == b"\x89PNG\r\n\x1a\n"
or data[:3] == b"\xff\xd8\xff"
or data[:6] in {b"GIF87a", b"GIF89a"}
or data[:2] == b"BM"
or (data[:4] == b"RIFF" and len(data) >= 12 and data[8:12] == b"WEBP")
)
def _write_cache_file(cache_dir: Path, prefix: str, ext: str, data: bytes) -> str:
"""Write ``data`` to ``<cache_dir>/<prefix>_<uuid12><ext>``; return the path string."""
filepath = cache_dir / f"{prefix}_{uuid.uuid4().hex[:12]}{ext}"
filepath.write_bytes(data)
return str(filepath)
def cache_image_from_bytes(data: bytes, ext: str = ".jpg") -> str:
"""Save raw image bytes to the cache and return the absolute path; raises
ValueError when *data* isn't an image (e.g. an upstream HTML error page)."""
validate_inbound_media_size(len(data), media_type="image")
if not _looks_like_image(data):
snippet = data[:80].decode("utf-8", errors="replace")
raise ValueError(f"Refusing to cache non-image data as {ext} (starts with: {snippet!r})")
return _write_cache_file(get_image_cache_dir(), "img", ext, data)
async def _cache_media_from_url(
url: str, ext: str, retries: int, *, media_type: str, accept: str, cache_fn, log_label: str,
) -> str:
"""Shared downloader behind ``cache_image_from_url`` / ``cache_audio_from_url``:
SSRF-checked (pre-flight + per-redirect; raises ValueError), size-capped, and
retried with linear backoff on timeouts / 429 / 5xx."""
from tools.url_safety import create_ssrf_safe_async_client, is_safe_url
if not is_safe_url(url):
raise ValueError(f"Blocked unsafe URL (SSRF protection): {safe_url_for_log(url)}")
import httpx
headers = {"User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)", "Accept": accept}
async with create_ssrf_safe_async_client(
timeout=30.0, follow_redirects=True, event_hooks={"response": [_ssrf_redirect_guard]},
) as client:
for attempt in range(retries + 1):
try:
async with client.stream("GET", url, headers=headers) as response:
response.raise_for_status()
content = await _read_httpx_body_with_limit(response, media_type=media_type)
return cache_fn(content, ext)
except (httpx.TimeoutException, httpx.HTTPStatusError) as exc:
if isinstance(exc, httpx.HTTPStatusError) and exc.response.status_code < 429:
raise
if attempt < retries:
wait = 1.5 * (attempt + 1)
logger.debug(
"%s cache retry %d/%d for %s (%.1fs): %s",
log_label, attempt + 1, retries, safe_url_for_log(url), wait, exc,
)
await asyncio.sleep(wait)
continue
raise
async def cache_image_from_url(url: str, ext: str = ".jpg", retries: int = 2) -> str:
"""Download an image URL into the image cache; return the absolute path."""
return await _cache_media_from_url(
url, ext, retries, media_type="image", accept="image/*,*/*;q=0.8",
cache_fn=cache_image_from_bytes, log_label="Media",
)
def _cleanup_cache_dir(cache_dir: Path, max_age_hours: int) -> int:
"""Delete files in *cache_dir* older than *max_age_hours*; return the count removed."""
cutoff = time.time() - (max_age_hours * 3600)
removed = 0
for f in cache_dir.iterdir():
if f.is_file() and f.stat().st_mtime < cutoff:
try:
f.unlink()
removed += 1
except OSError:
pass
return removed
def cleanup_image_cache(max_age_hours: int = 24) -> int:
"""Delete cached images older than *max_age_hours*; return the count removed."""
return _cleanup_cache_dir(get_image_cache_dir(), max_age_hours)
# Audio cache utilities (same pattern as images; feeds the STT tool).
AUDIO_CACHE_DIR = get_hermes_dir("cache/audio", "audio_cache")
def get_audio_cache_dir() -> Path:
"""Return the audio cache directory, creating it if it doesn't exist."""
return _resolve_cache_dir("AUDIO_CACHE_DIR", "cache/audio", "audio_cache")
def _sniff_audio_ext(data: bytes, fallback_ext: str) -> str:
"""Container-sniffed extension for audio bytes, via ``tools.audio_container`` — the
ONE owner of container detection for both outbound TTS repair and this inbound path."""
from tools.audio_container import sniff_audio_ext
return sniff_audio_ext(data, fallback_ext)
def cache_audio_from_bytes(data: bytes, ext: str = ".ogg") -> str:
"""Save raw audio bytes to the cache (container-sniffed ext); return the path."""
validate_inbound_media_size(len(data), media_type="audio")
cache_dir = get_audio_cache_dir()
return _write_cache_file(cache_dir, "audio", _sniff_audio_ext(data, ext), data)
async def cache_audio_from_url(url: str, ext: str = ".ogg", retries: int = 2) -> str:
"""Download an audio URL into the audio cache; return the absolute path."""
return await _cache_media_from_url(
url, ext, retries, media_type="audio", accept="audio/*,*/*;q=0.8",
cache_fn=cache_audio_from_bytes, log_label="Audio",
)
def cleanup_audio_cache(max_age_hours: int = 24) -> int:
"""Delete cached audio files older than *max_age_hours*; return the count removed."""
return _cleanup_cache_dir(get_audio_cache_dir(), max_age_hours)
# Video cache utilities (same pattern; referenced by local path).
VIDEO_CACHE_DIR = get_hermes_dir("cache/videos", "video_cache")
SUPPORTED_VIDEO_TYPES = {
".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm",
".mkv": "video/x-matroska", ".avi": "video/x-msvideo",
}
def get_video_cache_dir() -> Path:
"""Return the video cache directory, creating it if it doesn't exist."""
return _resolve_cache_dir("VIDEO_CACHE_DIR", "cache/videos", "video_cache")
def cache_video_from_bytes(data: bytes, ext: str = ".mp4") -> str:
"""Save raw video bytes to the cache and return the absolute file path."""
validate_inbound_media_size(len(data), media_type="video")
return _write_cache_file(get_video_cache_dir(), "video", ext, data)
def cleanup_video_cache(max_age_hours: int = 24) -> int:
"""Delete cached videos older than *max_age_hours*; return the count removed."""
return _cleanup_cache_dir(get_video_cache_dir(), max_age_hours)
# Document / screenshot cache utilities (same pattern; referenced by local path).
DOCUMENT_CACHE_DIR = get_hermes_dir("cache/documents", "document_cache")
SCREENSHOT_CACHE_DIR = get_hermes_dir("cache/screenshots", "browser_screenshots")
def get_screenshot_cache_dir() -> Path:
"""Return the browser screenshot cache directory, creating it if needed."""
return _resolve_cache_dir("SCREENSHOT_CACHE_DIR", "cache/screenshots", "browser_screenshots")
def cleanup_screenshot_cache(max_age_hours: int = 24) -> int:
"""Delete cached browser screenshots older than *max_age_hours*; return the count removed."""
return _cleanup_cache_dir(get_screenshot_cache_dir(), max_age_hours)
# Import-time defaults; _resolve_cache_dir compares against these to tell a
# test monkeypatch from an unmodified constant.
_CACHE_DIR_IMPORT_DEFAULTS = {
"IMAGE_CACHE_DIR": IMAGE_CACHE_DIR,
"AUDIO_CACHE_DIR": AUDIO_CACHE_DIR,
"VIDEO_CACHE_DIR": VIDEO_CACHE_DIR,
"DOCUMENT_CACHE_DIR": DOCUMENT_CACHE_DIR,
"SCREENSHOT_CACHE_DIR": SCREENSHOT_CACHE_DIR,
}
_HERMES_HOME = get_hermes_home()
_HERMES_ROOT = get_default_hermes_root()
MEDIA_DELIVERY_ALLOW_DIRS_ENV = "HERMES_MEDIA_ALLOW_DIRS"
MEDIA_DELIVERY_TRUST_RECENT_ENV = "HERMES_MEDIA_TRUST_RECENT_FILES"
MEDIA_DELIVERY_TRUST_RECENT_SECONDS_ENV = "HERMES_MEDIA_TRUST_RECENT_SECONDS"
# Strict mode = allowlist+recency validation. Off by default (symmetric with inbound,
# and the denylist still blocks credential / system paths); set true on public-facing
# gateways where prompt injection from one user could exfiltrate host secrets to them.
MEDIA_DELIVERY_STRICT_ENV = "HERMES_MEDIA_DELIVERY_STRICT"
MEDIA_DELIVERY_SAFE_ROOTS = (
IMAGE_CACHE_DIR,
AUDIO_CACHE_DIR,
VIDEO_CACHE_DIR,
DOCUMENT_CACHE_DIR,
SCREENSHOT_CACHE_DIR,
_HERMES_HOME / "image_cache",
_HERMES_HOME / "audio_cache",
_HERMES_HOME / "video_cache",
_HERMES_HOME / "document_cache",
_HERMES_HOME / "browser_screenshots",
# Canonical cache layout, alongside the legacy *_cache dirs (installs may have both).
_HERMES_HOME / "cache" / "images",
_HERMES_HOME / "cache" / "audio",
_HERMES_HOME / "cache" / "videos",
_HERMES_HOME / "cache" / "documents",
_HERMES_HOME / "cache" / "screenshots",
)
# Recency window (seconds) for trusting freshly-produced files: build artifacts land
# seconds before delivery, while pre-existing host files (/etc/passwd, ~/.ssh/id_rsa)
# have mtimes of days/months — so injected paths at old files are still rejected.
_MEDIA_DELIVERY_TRUST_RECENT_DEFAULT_SECONDS = 600
# Hard denylist applied even to "recent" files: credentials, system state, process
# introspection. The cache-dir allowlist still beats it (an operator may allow a root here).
_MEDIA_DELIVERY_DENIED_PREFIXES = (
"/etc", "/proc", "/sys", "/dev", "/root", "/boot", "/var/log", "/var/lib", "/var/run",
)
# Credential / config dirs denied under $HOME (Library/Keychains = macOS), resolved at check time.
_MEDIA_DELIVERY_DENIED_HOME_SUBPATHS = (
".ssh", ".aws", ".gnupg", ".kube", ".docker", ".config", ".azure", ".gcloud",
"Library/Keychains",
)
# Canonical cache subdirs holding deliverable artifacts; also used to enumerate
# per-profile cache roots at check time (_media_delivery_allowed_roots).
_MEDIA_DELIVERY_CACHE_SUBDIRS = ("images", "audio", "videos", "documents", "screenshots")
def _profile_cache_roots() -> List[Path]:
"""Per-profile cache roots ``<root>/profiles/<name>/cache/{images,audio,...}``.
The static safe roots cover only the active HERMES_HOME, so a root-level gateway
delivering a profile-scoped path would silently fail. Enumerated at check time so
profiles created after startup count, and so the profile path is allowlisted BEFORE
the ``/root`` denylist (which otherwise wins when HERMES_HOME is symlinked under it).
"""
roots: List[Path] = []
profiles_dir = _HERMES_ROOT / "profiles"
try:
profile_dirs = [p for p in profiles_dir.iterdir() if p.is_dir()]
except OSError:
return roots
for profile_dir in profile_dirs:
for subdir in _MEDIA_DELIVERY_CACHE_SUBDIRS:
roots.append(profile_dir / "cache" / subdir)
return roots
def _kanban_attachment_roots() -> List[Path]:
"""Return durable Kanban attachment roots without importing kanban_db."""
override = os.environ.get("HERMES_KANBAN_ATTACHMENTS_ROOT", "").strip()
if override:
return [Path(override).expanduser()]
home_override = os.environ.get("HERMES_KANBAN_HOME", "").strip()
root = Path(home_override).expanduser() if home_override else _HERMES_ROOT
roots = [root / "kanban" / "attachments"]
boards_root = root / "kanban" / "boards"
try:
board_dirs = [
path for path in boards_root.iterdir()
if path.is_dir() and not path.is_symlink()
and re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", path.name)
and (path / "kanban.db").is_file()
]
except OSError:
return roots
roots.extend(path / "attachments" for path in board_dirs)
return roots
def _media_delivery_allowed_roots() -> List[Path]:
"""Return roots from which model-emitted local media may be delivered."""
roots = [Path(root) for root in MEDIA_DELIVERY_SAFE_ROOTS]
roots.extend(_profile_cache_roots())
roots.extend(_kanban_attachment_roots())
extra_roots = os.environ.get(MEDIA_DELIVERY_ALLOW_DIRS_ENV, "")
for chunk in extra_roots.split(os.pathsep):
for raw_root in chunk.split(","):
raw_root = raw_root.strip()
if not raw_root:
continue
root = Path(os.path.expanduser(raw_root))
if root.is_absolute():
roots.append(root)
return roots
def _media_delivery_recency_seconds() -> float:
"""Recency window (seconds) for trusting fresh files; 0 = pure-allowlist mode."""
raw = os.environ.get(MEDIA_DELIVERY_TRUST_RECENT_ENV, "1").strip().lower()
if raw in ("0", "false", "no", "off", ""):
return 0.0
try:
custom = os.environ.get(MEDIA_DELIVERY_TRUST_RECENT_SECONDS_ENV, "").strip()
if custom:
seconds = float(custom)
return max(0.0, seconds)
except (TypeError, ValueError):
pass
return float(_MEDIA_DELIVERY_TRUST_RECENT_DEFAULT_SECONDS)
def _media_delivery_strict_mode() -> bool:
"""True when validation must require an allowlist/recency match (off by default).
Non-strict accepts any existing regular file outside the credential / system denylist
(single-user case); strict protects public-facing gateways from cross-user exfiltration.
"""
raw = os.environ.get(MEDIA_DELIVERY_STRICT_ENV, "0").strip().lower()
return raw in ("1", "true", "yes", "on")
def _media_delivery_denied_paths() -> List[Path]:
"""Return absolute denylist paths under which delivery is never allowed."""
denied = [Path(p) for p in _MEDIA_DELIVERY_DENIED_PREFIXES]
home = Path(os.path.expanduser("~"))
for sub in _MEDIA_DELIVERY_DENIED_HOME_SUBPATHS:
denied.append(home / sub)
# Per-file credential / secret stores at the HERMES_HOME root. Mirrors the read guard
# in agent/file_safety.py so the delivery (exfil) side never trails the write side.
# Per-file rather than the whole tree so skills/, logs/, and ad-hoc agent-written files
# under ~/.hermes stay deliverable (cache subdirs are allowlisted BEFORE this denylist).
_ROOT_CREDENTIAL_FILES = (
".env",
"auth.json",
"auth.lock",
"credentials",
"config.yaml",
# Anthropic PKCE / OAuth refresh credential store.
".anthropic_oauth.json",
# Google Workspace OAuth token (mtime bumps every turn, defeating the strict
# recency window) and the pending-exchange session/verifier file.
"google_token.json",
"google_oauth_pending.json",
os.path.join("auth", "google_oauth.json"),
# Webhook subscription HMAC secrets.
"webhook_subscriptions.json",
# Bitwarden Secrets Manager plaintext and encrypted disk caches.
os.path.join("cache", "bws_cache.json"),
os.path.join("cache", "bws_cache.enc.json"),
)
# Directory trees whose every child is credential material. mcp-tokens/ holds live
# MCP OAuth access tokens and dynamically-registered client credentials
# (tools/mcp_oauth.py); the write side already denies it, this pairs the exfil side.
_ROOT_CREDENTIAL_DIRS = ("pairing", "mcp-tokens")
for hermes_root in (_HERMES_HOME, _HERMES_ROOT):
for rel in _ROOT_CREDENTIAL_FILES:
denied.append(hermes_root / rel)
for rel in _ROOT_CREDENTIAL_DIRS:
denied.append(hermes_root / rel)
return denied
def _path_under_denied_prefix(resolved: Path) -> bool:
"""Return True if ``resolved`` lives under a deny-listed system path.
Exception: a denied prefix that IS the running user's own home is not denied —
``/root`` is listed so a non-root gateway can't deliver another user's home, but a
root-run gateway's own deliverables live under ``$HOME=/root``. Credential sub-dirs
(``~/.ssh``, ``~/.hermes/.env``, ...) are separate, more-specific entries and stay blocked.
"""
try:
home = Path(os.path.expanduser("~")).resolve(strict=False)
except (OSError, RuntimeError, ValueError):
home = None
for denied in _media_delivery_denied_paths():
try:
resolved_denied = denied.expanduser().resolve(strict=False)
except (OSError, RuntimeError, ValueError):
continue
if not (_path_is_within(resolved, resolved_denied) or resolved == resolved_denied):
continue
# Allow the running user's own home tree; its credential sub-dirs are
# caught by their own (more-specific) denylist entries above.
if home is not None and resolved_denied == home:
continue
return True
return False
def _file_is_recently_produced(resolved: Path, window_seconds: float) -> bool:
"""True if mtime is within ``window_seconds`` — a session-scoped trust signal: agents
produce artifacts seconds before sending; pre-existing host files are days/months old."""
if window_seconds <= 0:
return False
try:
mtime = resolved.stat().st_mtime
except OSError:
return False
return (time.time() - mtime) <= window_seconds
def _path_is_within(path: Path, root: Path) -> bool:
try:
path.relative_to(root)
return True
except ValueError:
return False
def _tenv(name: str, default: str = "") -> str:
"""Scope-aware TERMINAL_* read (tools.terminal_scope.terminal_env).
The gateway translates media paths for several profiles concurrently; the per-turn
scope carries the ACTIVE profile's settings, whereas os.getenv reads whatever a prior
turn pinned into the process env. Only ImportError falls back — a refusal scope must
raise rather than rebuild another profile's terminal policy from ambient env.
"""
try:
from tools.terminal_scope import terminal_env
except ImportError:
return os.getenv(name, default)
return terminal_env(name, default)
def _parse_docker_volume_mounts() -> List[Tuple[Path, Path]]:
"""Parse ``TERMINAL_DOCKER_VOLUMES`` (JSON list of ``host:container[:mode]``) into
``(host_path, container_path)``; named volumes / non-absolute hosts are skipped
because they can't be resolved on the gateway host."""
raw = _tenv("TERMINAL_DOCKER_VOLUMES", "").strip()
if not raw:
return []
try:
import json as _json
parsed = _json.loads(raw)
except Exception:
return []
if not isinstance(parsed, list):
return []
mounts: List[Tuple[Path, Path]] = []
for entry in parsed:
if not isinstance(entry, str):
continue
spec = entry.strip()
if not spec:
continue
# Prefer the first ':/' so absolute container paths are unambiguous.
sep = spec.find(":/")
if sep <= 0:
continue
host_raw = spec[:sep]
container_and_mode = spec[sep + 1 :] # starts with /
container_raw = container_and_mode.split(":", 1)[0]
if not container_raw.startswith("/"):
continue
# Skip named volumes (no absolute/drive host path).
host_expanded = os.path.expanduser(host_raw)
if not (host_expanded.startswith("/") or (len(host_expanded) > 1 and host_expanded[1] == ":")):
continue
try:
host_path = Path(host_expanded).resolve(strict=False)
container_path = Path(container_raw)
except (OSError, RuntimeError, ValueError):
continue
if not container_path.is_absolute():
continue
mounts.append((host_path, container_path))
return mounts
def _docker_sandbox_dir_candidates(session_key: str = "") -> List[str]:
"""Candidate host sandbox dir names for the delivering session, best first.
Mirrors ``_resolve_container_task_id`` (tools/terminal_tool.py): containers are
PROFILE-scoped — ``default`` for the default profile (shared with CLI), else
``sanitize_task_id_for_path("profile:<name>")``. Legacy per-session sandboxes
(``session:<key>``) stay as a fallback so files from that window still deliver.
The key is passed explicitly: delivery runs after the turn's session contextvars
were cleared, so an ambient lookup would silently collapse onto ``default``.
"""
candidates: List[str] = []
try:
from tools.environments.path_utils import sanitize_task_id_for_path
except Exception:
return ["default"]
# Explicit trusted-profiles opt-in: one shared container identity.
shared = _tenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", "").strip()
if shared:
candidates.append(sanitize_task_id_for_path(f"shared:{shared}"))
try:
from hermes_cli.profiles import get_active_profile_name
profile = get_active_profile_name() or "default"
except Exception:
profile = "default"
if profile != "default":
candidates.append(sanitize_task_id_for_path(f"profile:{profile}"))
candidates.append("default")
if session_key:
# Bug-window legacy layout: per-session sandboxes.
candidates.append(sanitize_task_id_for_path(f"session:{session_key}"))
return candidates
_TRUTHY = {"1", "true", "yes", "on"}
def _docker_env_active() -> bool:
return _tenv("TERMINAL_ENV", "").strip().lower() == "docker"
def _docker_persistent_active() -> bool:
"""Docker backend with persistent containers (the default) enabled."""
return _docker_env_active() and _tenv("TERMINAL_CONTAINER_PERSISTENT", "true").strip().lower() in _TRUTHY
def _docker_persistent_sandbox_roots(session_key: str, leaf: str) -> List[Path]:
"""Existing ``<sandbox>/docker/<candidate>/<leaf>`` host dirs in candidate order;
the translator tries each until the file resolves. Empty unless Docker + persistent."""
if not _docker_persistent_active():
return []
try:
from tools.environments.base import get_sandbox_dir
base = get_sandbox_dir() / "docker"
roots = []
for name in _docker_sandbox_dir_candidates(session_key):
cand = (base / name / leaf).resolve(strict=False)
if cand.is_dir():
roots.append(cand)
except Exception:
return []
return roots
def _default_docker_workspace_host_roots(session_key: str = "") -> List[Path]:
"""Existing host candidates for ``/workspace``: the explicit cwd mount
(``TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE``) if set, else the persistent sandbox layouts."""
if not _docker_persistent_active():
return []
if _tenv("TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE", "false").strip().lower() in _TRUTHY:
cwd = _tenv("TERMINAL_CWD") or os.getcwd()
try:
host = Path(os.path.expanduser(cwd)).resolve(strict=False)
except (OSError, RuntimeError, ValueError):
return []
return [host] if host.is_dir() else []
return _docker_persistent_sandbox_roots(session_key, "workspace")
def _docker_persistent_home_host_roots(session_key: str = "") -> List[Path]:
"""Existing host-path candidates for the persistent ``/root`` home mount
(``<sandbox>/docker/<task>/home`` per tools/environments/docker.py)."""
return _docker_persistent_sandbox_roots(session_key, "home")
def _cache_dir_container_mounts() -> List[Tuple[Path, Path]]:
"""(host, container) pairs for the auto-mounted Hermes cache dirs. The agent sees
artifacts at ``/root/.hermes/...`` and emits those paths in MEDIA tags; these are
longer prefixes than the ``/root`` home mount, so longest-prefix matching prefers them."""
if not _docker_env_active():
return []
try:
from tools.credential_files import get_cache_directory_mounts
return [(Path(m["host_path"]), Path(m["container_path"])) for m in get_cache_directory_mounts()]
except Exception:
return []
def _warn_unresolved_docker_media(candidate: Path, session_key: str, reason: str) -> None:
"""Name WHY a container-absolute MEDIA path failed translation; otherwise the only
signal is the generic "Skipping unsafe MEDIA directive path" line one level up.
Docker-only so host-path rejections stay quiet."""
if not _docker_env_active():
return
logger.warning(
"Docker MEDIA path %s did not resolve to a host sandbox file (%s%s); "
"the producing container's sandbox directory may not exist yet or "
"was pruned",
_log_safe_path(str(candidate)),
reason,
f", session_key={session_key}" if session_key else "",
)
def _translate_docker_container_media_path(candidate: Path, session_key: str = "") -> Optional[Path]:
"""Translate a container-absolute path to its host path via longest-prefix match
over ``docker_volumes``, the auto-mounted cache dirs (``/root/.hermes/...``), the
persistent ``/workspace`` host root, and the persistent ``/root`` home mount."""
if not candidate.is_absolute():
return None
# In-process gateways (Desktop, `hermes serve`) may not have bridged terminal.*
# config into TERMINAL_* env; run the idempotent bridge so mount parsing sees it.
try:
from tools.terminal_tool import _ensure_terminal_env_bridged
_ensure_terminal_env_bridged()
except Exception:
pass
mounts = list(_parse_docker_volume_mounts())
mounts.extend(_cache_dir_container_mounts())
mounted = {c.as_posix() for _, c in mounts}
# Synthetic /workspace mounts: profile-scoped layout first, then legacy per-session.
if "/workspace" not in mounted:
mounts.extend((root, Path("/workspace")) for root in _default_docker_workspace_host_roots(session_key))
# Synthetic /root home mounts. Cache mounts above are longer prefixes, so this
# only catches stray home writes like /root/out.png. /root/.hermes/* that missed
# a cache mount is the container's credential surface (.env, auth.json, ...);
# translating via the home mount would land OUTSIDE the host denylist — refuse.
if "/root" not in mounted and not candidate.as_posix().startswith("/root/.hermes"):
mounts.extend((root, Path("/root")) for root in _docker_persistent_home_host_roots(session_key))
if not mounts:
_warn_unresolved_docker_media(candidate, session_key, "no sandbox mounts resolved")
return None
# Longest container-prefix match; equal-length prefixes are tried in insertion order.
candidate_posix = candidate.as_posix()
matched: List[Tuple[Path, Path, int]] = []
for host_root, container_root in mounts:
container_posix = container_root.as_posix().rstrip("/") or "/"
if candidate_posix == container_posix or candidate_posix.startswith(container_posix + "/"):
matched.append((host_root, container_root, len(container_posix)))
if not matched:
_warn_unresolved_docker_media(candidate, session_key, "no mounted prefix matches")
return None
matched.sort(key=lambda m: -m[2])
for host_root, container_root, _score in matched:
try:
relative = candidate.relative_to(container_root)
translated = (host_root / relative).resolve(strict=True)
except (OSError, RuntimeError, ValueError):
continue
if translated != host_root and not _path_is_within(translated, host_root):
continue
return translated
_warn_unresolved_docker_media(candidate, session_key, "host file missing from sandbox")
return None
def validate_media_delivery_path(path: str, session_key: str = "") -> Optional[str]:
"""Return a safe absolute file path for native media delivery, else None.
Default mode: any existing regular file outside the credential / system denylist —
symmetric with inbound, where platforms hand the agent whatever the user uploads.
Strict mode (``HERMES_MEDIA_DELIVERY_STRICT=1``): the file MUST be under a Hermes
cache, an operator root (``HERMES_MEDIA_ALLOW_DIRS``), or freshly produced within
the recency window — for public bots where one user's prompt injection must not
exfiltrate host secrets. Symlinks are resolved before any containment/denylist check.
"""
if not path:
return None
candidate = str(path).strip()
if len(candidate) >= 2 and candidate[0] == candidate[-1] and candidate[0] in "`\"'":
candidate = candidate[1:-1].strip()
candidate = candidate.lstrip("`\"'").rstrip("`\"',.;:)}]")
if not candidate:
return None
try:
expanded = Path(os.path.expanduser(candidate))
except (OSError, RuntimeError, ValueError):
# expanduser raises ValueError("embedded null byte") for a ~\x00 path.
return None
if not expanded.is_absolute():
return None
# Docker agents emit MEDIA:/workspace/... — map container paths to host paths first.
translated = _translate_docker_container_media_path(expanded, session_key=session_key)
if translated is not None:
resolved = translated
else:
try:
resolved = expanded.resolve(strict=True)
except (OSError, RuntimeError, ValueError):
return None
if not resolved.is_file():
return None
# Cache / operator allowlist is trusted unconditionally, regardless of mode.
for root in _media_delivery_allowed_roots():
try:
resolved_root = root.expanduser().resolve(strict=False)
except (OSError, RuntimeError, ValueError):
continue
if _path_is_within(resolved, resolved_root):
return str(resolved)
# Non-strict (default): accept anything not denylisted. The denylist still blocks
# /etc, /proc, ~/.ssh, ~/.aws, and the Hermes-root secret stores, so the obvious
# injection targets (MEDIA:/etc/passwd, MEDIA:~/.hermes/google_token.json) stay rejected.
if not _media_delivery_strict_mode():
if _path_under_denied_prefix(resolved):
return None
return str(resolved)
# Strict: fall back to recency trust for freshly-produced files (pandoc -o /tmp/x.pdf);
# system / credential paths stay blocked even when "recent".
window = _media_delivery_recency_seconds()
if (
window > 0
and not _path_under_denied_prefix(resolved)
and _file_is_recently_produced(resolved, window)
):
return str(resolved)
return None
# Neutralise control chars and Unicode line separators (NEL, LS, PS) that splitlines()
# / log aggregators treat as breaks, so a model-emitted path can't forge a log line.
_LOG_UNSAFE_CHARS = re.compile(r"[\x00-\x1f\x7f\x85\u2028\u2029]")
def _log_safe_path(path: str) -> str:
"""Return a single-line, length-bounded path for log output."""
return _LOG_UNSAFE_CHARS.sub("?", str(path))[:200]
def _validated_delivery_path(raw_path, session_key: str, label: str) -> Optional[str]:
"""``validate_media_delivery_path`` plus the shared "Skipping unsafe ..." warning."""
raw = str(raw_path)
safe_path = validate_media_delivery_path(raw, session_key=session_key)
if not safe_path:
logger.warning("Skipping unsafe %s: %s", label, _log_safe_path(raw))
return safe_path
SUPPORTED_DOCUMENT_TYPES = {
".pdf": "application/pdf", ".md": "text/markdown", ".txt": "text/plain", ".csv": "text/csv",
".log": "text/plain", ".json": "application/json", ".xml": "application/xml",
".yaml": "application/yaml", ".yml": "application/yaml", ".toml": "application/toml",
".ini": "text/plain", ".cfg": "text/plain", ".zip": "application/zip",
".doc": "application/msword",
".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
".xls": "application/vnd.ms-excel",
".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
".ppt": "application/vnd.ms-powerpoint",
".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
".ts": "text/plain", ".py": "text/plain", ".sh": "text/plain",
}
# Text-injection extension allowlist: files safe to inline into the prompt when small.
# Deliberately an extension gate, NOT a blind UTF-8 decode — PDF/zip/docx can start
# with decodable ASCII headers. Non-members are still cached and surfaced by path.
_TEXT_INJECT_EXTENSIONS = {
".txt", ".md", ".markdown", ".csv", ".tsv", ".log",
".json", ".jsonl", ".ndjson", ".xml", ".yaml", ".yml", ".toml",
".ini", ".cfg", ".conf", ".env", ".properties",
".html", ".htm", ".css", ".scss", ".sass", ".less",
".py", ".pyi", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
".sh", ".bash", ".zsh", ".fish", ".ps1", ".bat",
".c", ".h", ".cpp", ".cc", ".hpp", ".cs", ".java", ".kt",
".go", ".rs", ".rb", ".php", ".pl", ".lua", ".r", ".jl",
".swift", ".m", ".scala", ".clj", ".ex", ".exs", ".erl",
".sql", ".graphql", ".proto", ".tf", ".hcl",
".dockerfile", ".makefile", ".cmake", ".gradle",
".rst", ".tex", ".srt", ".vtt", ".diff", ".patch",
}
# Image extensions platforms may deliver as "documents" (file-picker uploads,
# stickers/screenshots wrapped as files); routed through the image cache /
# vision path instead of being rejected as unsupported.
SUPPORTED_IMAGE_DOCUMENT_TYPES = {
".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp",
".gif": "image/gif",
}
# Media-delivery extension allowlist — SINGLE SOURCE OF TRUTH for both extractors
# (``extract_media`` MEDIA: tags, ``extract_local_files`` bare paths) and the cleanup
# regexes built from it, so a tag is only stripped when its extension is deliverable
# and an unknown-extension path survives in the body instead of silently vanishing.
# The dispatch partition (image vs video vs document) lives in ``gateway/run.py``.
MEDIA_DELIVERY_EXTS: Tuple[str, ...] = (
# Images (embed inline)
".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".svg",
# Video (embed inline where supported)
".mp4", ".mov", ".avi", ".mkv", ".webm", ".3gp",
# Audio (delivered as voice/audio where supported)
".mp3", ".m2a", ".wav", ".ogg", ".opus", ".m4a", ".flac",
# Documents (uploaded as file attachments)
".pdf", ".docx", ".doc", ".odt", ".rtf", ".txt", ".md", ".epub",
# Spreadsheets / data
".xlsx", ".xls", ".ods", ".csv", ".tsv", ".json", ".xml", ".yaml", ".yml",
# Geospatial / GIS (#24032)
".kmz", ".kml", ".geojson", ".gpx",
# Presentations
".pptx", ".ppt", ".odp", ".key",
# Archives
".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".apk", ".ipa",
# Web / rendered output
".html", ".htm",
)
# Regex alternation of bare extensions (no leading dot), sorted longest-first
# so a shorter ext never matches as a prefix of a longer one.
_MEDIA_EXT_ALTERNATION = "|".join(sorted((e.lstrip(".") for e in MEDIA_DELIVERY_EXTS), key=len, reverse=True))
# Anchored ``MEDIA:<path>`` cleanup pattern, shared by the non-streaming dispatch
# path and the streaming consumer. Strips only a tag whose path ends in a known
# deliverable extension (optionally quoted/backticked); an unknown-extension tag
# stays in the text for the bare-path detector (extract_local_files).
# Regex-shape rationale:
# * Path anchors: ``~/``, ``/``, ``X:\`` or ``X:/`` (Windows drive letter).
# * Emphasis tolerance: up to 3 quote/emphasis markers on each side, because
# models wrap tags as ``**MEDIA:/x.pdf**`` / ``_MEDIA:/x.pdf_``. Code,
# inline-code and blockquote contexts are neutralised earlier by
# ``_mask_protected_spans`` so example tags remain non-deliverable.
# * Non-greedy path forms, with ``MEDIA:`` accepted as a boundary, so glued
# tags (``MEDIA:/a.pngMEDIA:/b.png``) or trailing prose never merge into one
# invalid path.
# * Sentence-final ``.`` is a boundary only before whitespace/EOL
# (``\.(?=\s|$)``) so ``MEDIA:/x/data.csv.`` yields ``data.csv`` while
# ``archive.tar.gz`` still extends past ``.tar``.
# * CJK full-width punctuation terminates paths too: Chinese output writes
# ``MEDIA:D:\path\早报.pdf（782.6 KB）`` and would otherwise drop the file.
_MEDIA_CJK_TERMINATORS = "（）〈〉《》：，。；！？、\u201c\u201d\u2018\u2019【】"
MEDIA_TAG_CLEANUP_RE = re.compile(
r'''[`"'*_]{0,3}MEDIA:\s*'''
r'''(?P<path>`[^`\n]+?`|"[^"\n]+?"|'[^'\n]+?'|'''
r'''(?:~/|/|[A-Za-z]:[/\\])\S+?(?:[^\S\n]+\S+?)*?\.(?:''' + _MEDIA_EXT_ALTERNATION + r'''))'''
r'''(?=[\s`"'*_,;:)\]}\[''' + _MEDIA_CJK_TERMINATORS + r''']|MEDIA:|\.(?:\s|$)|$)[`"'*_]{0,3}\.?''',
re.IGNORECASE,
)
# Paths NOT covered by the extension alternation — extension-less (Caddyfile,
# Makefile) or unknown-extension (.py, .log, ...) — are delivered via this
# pattern, but only after ``validate_media_delivery_path`` accepts them (exists
# on disk, not under the credential/system denylist, strict-mode rules
# honored), so prompt-injection paths that don't validate stay visible.
#
# The bare path class is a tempered-greedy token (non-greedy + lookahead) and
# whitespace-bounded: a tag glued to the next ``MEDIA:`` or to prose must not
# absorb it. Spaced unknown-extension paths (``MEDIA:/data/map data.kmz``) are
# instead recovered by ``_match_extensionless_path``, which extends the
# candidate forward across single spaces — bounded at newline / next ``MEDIA:``
# — with on-disk validation as the oracle, so prose never rides along.
MEDIA_EXTENSIONLESS_TAG_RE = re.compile(
r'''[`"'*_]{0,3}MEDIA:\s*'''
r'''(?P<path>`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|'''
r'''(?:~/|/|[A-Za-z]:[/\\])[^\s\n`"']+?)'''
r'''(?=[`"'\s,;:)\]}''' + _MEDIA_CJK_TERMINATORS + r''']|MEDIA:|$)'''
r'''[`"'*_]{0,3}\s*''',
re.IGNORECASE,
)
def _match_extensionless_path(scan_text: str, match: "re.Match") -> Optional[Tuple[str, int]]:
"""Resolve an extensionless MEDIA tag match to a validated on-disk path.
Tries the captured path first; on validation failure extends it forward
across single spaces (max 8 tokens, never past a newline or the next
``MEDIA:``). Returns ``(safe_path, end_offset)`` or ``None``.
"""
raw = match.group("path")
path = _normalize_media_tag_path(raw)
if not path:
return None
safe = validate_media_delivery_path(path)
if safe:
return safe, match.end("path")
start = match.start("path")
nl = scan_text.find("\n", start)
limit = nl if nl != -1 else len(scan_text)
segment = scan_text[start:limit]
nxt = segment.find("MEDIA:", 1)
if nxt != -1:
segment = segment[:nxt]
pos = match.end("path") - start
for _ in range(8):
while pos < len(segment) and segment[pos] in " \t":
pos += 1
if pos >= len(segment):
break
tok_end = pos
while tok_end < len(segment) and segment[tok_end] not in " \t":
tok_end += 1
candidate = _normalize_media_tag_path(segment[:tok_end])
safe = validate_media_delivery_path(candidate)
if safe:
return safe, start + tok_end
pos = tok_end
return None
def _merge_spans(spans: list) -> list:
"""Merge overlapping/nested (start, end) spans so multi-pattern matches
over the same tag never double-delete adjacent text."""
merged: list = []
for s, e in sorted(spans):
if merged and s <= merged[-1][1]:
merged[-1] = (merged[-1][0], max(merged[-1][1], e))
else:
merged.append((s, e))
return merged
def _normalize_media_tag_path(raw: str) -> str:
path = str(raw or "").strip()
if len(path) >= 2 and path[0] == path[-1] and path[0] in "`\"'":
path = path[1:-1].strip()
return path.lstrip("`\"'").rstrip("`\"',.;:)}]")
def _path_lacks_deliverable_extension(path: str) -> bool:
"""True when ``path`` has no extension or one outside MEDIA_DELIVERY_EXTS.
Such paths take the validated delivery pass (``validate_media_delivery_path``)
instead of the unconditional one, so every file type is deliverable while
nonexistent / denylisted paths stay visible in the text.
"""
suffix = Path(path).suffix.lower()
return not suffix or suffix not in MEDIA_DELIVERY_EXTS
def _has_media_directives(text: str) -> bool:
return "MEDIA:" in text or "[[audio_as_voice]]" in text or "[[as_document]]" in text
def _mask_media_scan_text(text: str) -> str:
"""Offset-preserving mask of protected spans (code, quotes, JSON string values).
BasePlatformAdapter is defined later in this module; resolved at call time.
"""
masked = BasePlatformAdapter._mask_protected_spans(text)
return BasePlatformAdapter._mask_json_string_media(masked)
def _real_media_tag_spans(masked: str) -> list:
"""(start, end) spans of deliverable MEDIA tags located on a masked copy.
Known-extension tags match unconditionally; extension-less / unknown-extension
tags only when ``validate_media_delivery_path`` accepts the path.
"""
spans: list = [m.span() for m in MEDIA_TAG_CLEANUP_RE.finditer(masked)]
for match in MEDIA_EXTENSIONLESS_TAG_RE.finditer(masked):
path = _normalize_media_tag_path(match.group("path"))
if not path or not _path_lacks_deliverable_extension(path):
continue
resolved = _match_extensionless_path(masked, match)
if resolved is not None:
spans.append((match.start(), resolved[1]))
return spans
_FENCED_CODE_RE = re.compile(r'```[^\n]*\n.*?```', re.DOTALL)
_INLINE_CODE_RE = re.compile(r'`[^`\n]+`')
def _code_spans(content: str) -> list:
"""(start, end) spans of fenced code blocks and inline code in ``content``."""
return [m.span() for m in _FENCED_CODE_RE.finditer(content)] + [m.span() for m in _INLINE_CODE_RE.finditer(content)]
def _blank_spans(text: str, spans: list) -> str:
"""Replace every non-newline char inside ``spans`` with a space (offsets preserved)."""
chars = list(text)
for start, end in spans:
for i in range(start, end):
if chars[i] != '\n':
chars[i] = ' '
return ''.join(chars)
def _delete_spans(text: str, spans: list) -> str:
"""Delete merged ``spans`` from ``text`` (no-op when ``spans`` is empty)."""
if not spans:
return text
chars = list(text)
for start, end in reversed(_merge_spans(spans)):
del chars[start:end]
return "".join(chars)
def _strip_media_tag_directives(text: str) -> str:
"""Remove MEDIA: tags and [[audio_as_voice]] / [[as_document]] markers.
Protected spans are mask-located only — tags inside them are neither
stripped nor mangled, matching ``extract_media`` so display and delivery agree.
"""
if not _has_media_directives(text):
return text
cleaned = text.replace("[[audio_as_voice]]", "").replace("[[as_document]]", "")
return _delete_spans(cleaned, _real_media_tag_spans(_mask_media_scan_text(cleaned)))
def get_document_cache_dir() -> Path:
"""Return the document cache directory, creating it if it doesn't exist."""
return _resolve_cache_dir("DOCUMENT_CACHE_DIR", "cache/documents", "document_cache")
def cache_document_from_bytes(data: bytes, filename: str) -> str:
"""Save raw document bytes to the cache as ``doc_{uuid12}_{original_name}``
and return the absolute path.
Raises:
ValueError: If the sanitized path escapes the cache directory.
"""
cache_dir = get_document_cache_dir()
# Sanitize: strip directory components, null bytes, and control characters
safe_name = Path(filename).name if filename else "document"
safe_name = safe_name.replace("\x00", "").strip()
if not safe_name or safe_name in {".", ".."}:
safe_name = "document"
cached_name = f"doc_{uuid.uuid4().hex[:12]}_{safe_name}"
filepath = cache_dir / cached_name
# Final safety check: ensure path stays inside cache dir
if not filepath.resolve().is_relative_to(cache_dir.resolve()):
raise ValueError(f"Path traversal rejected: {filename!r}")
filepath.write_bytes(data)
return str(filepath)
def cleanup_document_cache(max_age_hours: int = 24) -> int:
"""Delete cached documents older than *max_age_hours*; return the count removed."""
return _cleanup_cache_dir(get_document_cache_dir(), max_age_hours)
# Unified media caching: classify raw attachment bytes by extension/MIME against
# the registries above and route to the right cache_*_from_bytes helper.
@dataclass
class CachedMedia:
"""Result of caching one attachment's bytes."""
path: str # absolute cache path, agent-visible (sandbox-translated)
media_type: str # MIME type recorded on the MessageEvent
kind: str # "image" | "video" | "audio" | "document"
display_name: str # human-readable name for transcript notes
def context_note(self) -> str:
"""One-line transcript annotation pointing the agent at the file."""
return f"[{self.kind} '{self.display_name}' saved at: {self.path}]"
def _resolve_media_ext(filename: str, mime_type: str) -> str:
"""Best-effort file extension from filename, then MIME fallback."""
if filename:
ext = os.path.splitext(filename)[1].lower()
if ext:
return ext
mime = (mime_type or "").lower()
if not mime:
return ""
for table in (SUPPORTED_IMAGE_DOCUMENT_TYPES, SUPPORTED_VIDEO_TYPES, SUPPORTED_DOCUMENT_TYPES):
for ext, m in table.items():
if m == mime:
return ext
return ""
def cache_media_bytes(
data: bytes,
*,
filename: str = "",
mime_type: str = "",
default_kind: Optional[str] = None,
) -> Optional[CachedMedia]:
"""Classify and cache raw attachment bytes; return a CachedMedia or None.
``default_kind`` biases classification when extension/MIME are ambiguous
(e.g. a Telegram native photo with no usable name). Anything that is not
image/video/audio is cached as a document; only images that fail validation
(``cache_image_from_bytes`` raises ValueError) return None.
"""
from tools.credential_files import to_agent_visible_cache_path
ext = _resolve_media_ext(filename, mime_type)
mime = (mime_type or "").lower()
display = re.sub(r"[^\w.\- ]", "_", filename) if filename else (ext.lstrip(".") or "file")
is_image = mime.startswith("image/") or ext in SUPPORTED_IMAGE_DOCUMENT_TYPES or default_kind == "image"
is_video = mime.startswith("video/") or ext in SUPPORTED_VIDEO_TYPES or default_kind == "video"
is_audio = mime.startswith("audio/") or ext in _AUDIO_EXTS or default_kind == "audio"
if is_image:
img_ext = ext if ext in SUPPORTED_IMAGE_DOCUMENT_TYPES else ".jpg"
try:
path = cache_image_from_bytes(data, ext=img_ext)
except ValueError:
return None
out_mime = mime if mime.startswith("image/") else SUPPORTED_IMAGE_DOCUMENT_TYPES.get(img_ext, "image/jpeg")
return CachedMedia(to_agent_visible_cache_path(path), out_mime, "image", display)
if is_video:
vid_ext = ext if ext in SUPPORTED_VIDEO_TYPES else ".mp4"
path = cache_video_from_bytes(data, ext=vid_ext)
return CachedMedia(to_agent_visible_cache_path(path), SUPPORTED_VIDEO_TYPES.get(vid_ext, "video/mp4"), "video", display)
if is_audio:
aud_ext = ext if ext in _AUDIO_EXTS else ".ogg"
path = cache_audio_from_bytes(data, ext=aud_ext)
out_mime = mime if mime.startswith("audio/") else _AUDIO_MIME_TYPES[aud_ext]
return CachedMedia(to_agent_visible_cache_path(path), out_mime, "audio", display)
# Any other file type is cached and surfaced as a local path: once a user is
# authorized to message the agent, the extension allowlist must not silently
# drop their uploads. Unknown types get application/octet-stream (or the
# caller's MIME) so the agent knows to reach for terminal tools.
fallback_name = filename or (f"document{ext}" if ext else "document.bin")
path = cache_document_from_bytes(data, fallback_name)
if ext in SUPPORTED_DOCUMENT_TYPES:
out_mime = SUPPORTED_DOCUMENT_TYPES[ext]
else:
out_mime = mime if mime else "application/octet-stream"
return CachedMedia(to_agent_visible_cache_path(path), out_mime, "document", display or fallback_name)
class MessageType(Enum):
"""Types of incoming messages."""
TEXT = "text"
LOCATION = "location"
PHOTO = "photo"
VIDEO = "video"
AUDIO = "audio"
VOICE = "voice"
DOCUMENT = "document"
STICKER = "sticker"
COMMAND = "command" # /command style
class ProcessingOutcome(Enum):
"""Result classification for message-processing lifecycle hooks."""
SUCCESS = "success"
FAILURE = "failure"
CANCELLED = "cancelled"
@dataclass
class MessageEvent:
"""Incoming message from a platform — the normalized shape all adapters produce."""
# Message content
text: str
message_type: MessageType = MessageType.TEXT
# Author of this inbound message; mirrored from ``source`` so per-message
# prompt builders need not dig into it. May be None for non-IM sources.
user_id: Optional[str] = None
user_name: Optional[str] = None
# Source information
source: SessionSource = None
# Original platform data
raw_message: Any = None
message_id: Optional[str] = None
# Platform-specific update id (Telegram ``update_id``). ``/restart`` records
# it so the new gateway can advance the Telegram offset past it and not
# re-process the same ``/restart`` if PTB's graceful-shutdown ACK times out.
platform_update_id: Optional[int] = None
# Media attachments: local file paths (for vision tool access)
media_urls: List[str] = field(default_factory=list)
media_types: List[str] = field(default_factory=list)
# Per-attachment text-inlining contract; None = legacy "text/* already inlined into ``text``".
media_text_inlined: List[Optional[bool]] = field(default_factory=list)
# Reply context
reply_to_message_id: Optional[str] = None
reply_to_text: Optional[str] = None # Text of the replied-to message (for context injection)
reply_to_author_id: Optional[str] = None
reply_to_author_name: Optional[str] = None
reply_to_is_own_message: bool = False # True when the user replied to this bot/assistant's message
# Structured interactive-prompt reply (relay Phase 3): {prompt_id, option_id,
# label?, prompt_message_id?}. RelayAdapter routes it to the approval /
# slash-confirm / clarify resolvers BEFORE normal dispatch; native adapters
# never set it (their button callbacks resolve in-process).
prompt_response: Optional[Dict[str, Any]] = None
# Auto-loaded skill(s) for topic/channel bindings; a single name or ordered list.
auto_skill: Optional[str | list[str]] = None
# Per-channel ephemeral system prompt; applied at API call time, never persisted to transcript.
channel_prompt: Optional[str] = None
# Channel context recovered by history backfill (e.g. messages missed under
# require_mention). Kept separate from ``text`` so run.py's sender-prefix
# logic sees only the trigger message, then prepends this context.
channel_context: Optional[str] = None
# Set for synthetic events (e.g. background-process notifications) that must bypass user authorization.
internal: bool = False
# Free-form per-event metadata (e.g. WhatsApp sets ``whatsapp_from_owner=True``).
# Plugins read via ``event.metadata.get(...)`` and must not assume any key exists.
metadata: Dict[str, Any] = field(default_factory=dict)
# Timestamps
timestamp: datetime = field(default_factory=datetime.now)
# Whether this event may resolve gateway commands / pending control prompts.
# Kept last for positional-construction compat. Proactive plugin events set
# False so untrusted payload text stays conversational input.
allow_gateway_control: bool = True
def is_command(self) -> bool:
"""Check if this is a command message (e.g., /new, /reset)."""
return self.allow_gateway_control and (self.text or "").lstrip().startswith("/")
def get_command(self) -> Optional[str]:
"""Extract command name if this is a command message."""
if not self.is_command():
return None
command_text = (self.text or "").lstrip()
parts = command_text.split(maxsplit=1)
raw = parts[0][1:].lower() if parts else None
if raw and "@" in raw:
raw = raw.split("@", 1)[0]
# Reject file paths: valid command names never contain /
if raw and "/" in raw:
return None
return raw
def get_command_args(self) -> str:
"""Get the arguments after a command."""
if not self.is_command():
return self.text
command_text = (self.text or "").lstrip()
parts = command_text.split(maxsplit=1)
args = parts[1] if len(parts) > 1 else ""
# iOS auto-corrects -- to — (em dash) and - to – (en dash)
args = args.replace("\u2014\u2014", "--").replace("\u2014", "--").replace("\u2013", "-")
return args
@dataclass
class TextDebounceState:
event: MessageEvent
task: asyncio.Task | None
first_ts: float
last_ts: float
def cancel_timer(self, *, unless: "asyncio.Task | None" = None) -> None:
"""Cancel the pending flush timer (if live and not ``unless``)."""
if self.task is not None and self.task is not unless and not self.task.done():
self.task.cancel()
def _append_text(existing: Optional[str], new: Optional[str]) -> str:
"""``existing\\nnew`` when both non-empty; the non-empty one otherwise."""
return f"{existing}\n{new}" if existing else new
@dataclass
class _ExtractedResponse:
"""Deliverable parts of a handler response (see ``_extract_response_content``)."""
text_content: str
images: list
media_files: list
local_files: list
force_document_attachments: bool
pre_extract: str
_PLAINTEXT_GATEWAY_RESTART_PATTERNS: tuple[re.Pattern[str], ...] = (
re.compile(r"^(?:please\s+)?restart\s+(?:the\s+)?gateway[.!?\s]*$", re.IGNORECASE),
re.compile(r"^(?:please\s+)?restart\s+(?:the\s+)?hermes\s+gateway[.!?\s]*$", re.IGNORECASE),
re.compile(r"^(?:please\s+)?restart\s+hermes[.!?\s]*$", re.IGNORECASE),
)
def coerce_plaintext_gateway_command(event: "MessageEvent") -> None:
"""Rewrite a tiny set of DM plaintext admin phrases into slash commands.
Keeps ``restart gateway`` out of the LLM/tool path, where a self-restart from
inside the running agent leaves the gateway stuck in ``draining`` waiting for
that same agent. Narrow on purpose: DM text, exact restart phrases only.
"""
try:
if event is None or event.message_type != MessageType.TEXT:
return
text = (event.text or "").strip()
if not text or text.startswith("/"):
return
source = getattr(event, "source", None)
if getattr(source, "chat_type", None) != "dm":
return
for pattern in _PLAINTEXT_GATEWAY_RESTART_PATTERNS:
if pattern.match(text):
event.text = "/restart"
return
except Exception:
return
@dataclass
class SendResult:
"""Result of sending a message."""
success: bool
message_id: Optional[str] = None
error: Optional[str] = None
raw_response: Any = None
# Adapter-specific metadata. Known cross-layer contract: Telegram edit-overflow
# partials set raw_response["partial_overflow"] (delivered_chunks, total_chunks,
# last_message_id, delivered_prefix, continuation_message_ids) so the stream
# consumer sends the missing tail instead of marking a clipped response complete.
retryable: bool = False # transient connection error — base retries automatically
retry_after: Optional[float] = None # server-requested delay (Telegram FloodWait) beats our backoff
# When an oversized payload was split across platform messages, ``message_id``
# is the LAST visible id (so later edits target the newest chunk) and these
# are the additional ids in send order. Empty for the single-message case.
continuation_message_ids: tuple = ()
# Machine-readable failure category (only when ``success`` is False): one of
# SEND_ERROR_KINDS or None. Lets consumers branch without substring-matching
# ``error``. Producers set it via :func:`classify_send_error`.
error_kind: Optional[str] = None
# Platform-neutral send-failure categories for ``SendResult.error_kind``, so the
# gateway decides once, in one place, whether a failure is worth surfacing.
# too_long exceeded the per-message size cap (adapter usually splits; informational)
# bad_format markup/entities rejected (parse error); plain-text retry is the fix
# forbidden blocked/kicked/no permission — the bot CANNOT reach the user
# not_found target chat/thread/message no longer exists
# rate_limited flood control
# transient connection-level failure, safe to retry
# unknown no known shape matched
SEND_ERROR_KINDS = frozenset(
{"too_long", "bad_format", "forbidden", "not_found", "rate_limited", "transient", "unknown"}
)
# ``not_found`` substrings split by blast radius: chat-level means the whole
# target is dead; thread/topic/message-level leaves the parent chat reachable
# and must NOT mark it dead. ``classify_send_error`` collapses both into
# "not_found"; ``is_chat_level_not_found`` recovers the split (gateway.dead_targets).
_CHAT_LEVEL_NOT_FOUND_SUBSTRINGS = ("chat not found",)
_SUBCHAT_NOT_FOUND_SUBSTRINGS = (
"message to edit not found", "message to reply not found", "thread not found", "topic_deleted",
"message_id_invalid",
)
def _error_blob(exc: Optional[BaseException] = None, error_text: str = "") -> str:
"""Lowercased blob (error_text + str(exc) + exception class name) that both
send-error classifiers match against — one builder so they can never drift."""
parts = []
if error_text:
parts.append(error_text)
if exc is not None:
exc_str = str(exc)
if exc_str:
parts.append(exc_str)
parts.append(exc.__class__.__name__)
return " ".join(parts).lower()
def _any_in(blob: str, *needles: str) -> bool:
return any(n in blob for n in needles)
# Ordered (kind, predicate) table for classify_send_error — first match wins.
_SEND_ERROR_CLASSIFIERS: Tuple[Tuple[str, Callable[[str], bool]], ...] = (
("too_long", lambda b: _any_in(b, "message_too_long", "too long", "message is too long")),
("bad_format", lambda b: (
_any_in(b, "can't parse entities", "cant parse entities", "can't find end", "unsupported start tag")
or ("entity" in b and "parse" in b)
or ("bad request" in b and "entit" in b)
)),
("forbidden", lambda b: _any_in(
b, "forbidden", "bot was blocked", "blocked by the user", "user is deactivated",
"not enough rights", "have no rights", "not a member",
)),
("not_found", lambda b: _any_in(b, *_CHAT_LEVEL_NOT_FOUND_SUBSTRINGS, *_SUBCHAT_NOT_FOUND_SUBSTRINGS)),
("rate_limited", lambda b: _any_in(b, "flood", "too many requests", "retry after", "rate limit")),
("transient", lambda b: _any_in(b, *_RETRYABLE_ERROR_PATTERNS, "connecttimeout")),
)
def classify_send_error(exc: Optional[BaseException], error_text: str = "") -> str:
"""Map a send exception / error string to a :data:`SEND_ERROR_KINDS` value.
Conservative substring matching: anything unrecognized is ``"unknown"`` so an
unclassified failure is never mistaken for a benign one.
"""
blob = _error_blob(exc, error_text)
if not blob.strip():
return "unknown"
for kind, matches in _SEND_ERROR_CLASSIFIERS:
if matches(blob):
return kind
return "unknown"
def is_chat_level_not_found(exc: Optional[BaseException] = None, error_text: str = "") -> bool:
"""Whether a ``not_found`` failure means the *whole chat* is gone.
Only chat-level not_found should mark a delivery target dead; a deleted forum
topic or edited-away message leaves the parent chat reachable. When both
markers are present the sub-chat reading wins (never kill a reachable chat).
"""
blob = _error_blob(exc, error_text)
if any(s in blob for s in _SUBCHAT_NOT_FOUND_SUBSTRINGS):
return False
return any(s in blob for s in _CHAT_LEVEL_NOT_FOUND_SUBSTRINGS)
class EphemeralReply(str):
"""System-notice reply that auto-deletes after a TTL.
Slash-command handlers return this instead of a plain str to request deletion
after ``ttl_seconds`` on platforms that implement ``delete_message``; others
leave the message in place. ``None`` ttl uses ``display.ephemeral_system_ttl``
(``0`` disables globally). Subclassing ``str`` keeps it transparent to
everything that treats handler results as text; ``isinstance`` still
distinguishes it so the send path can schedule deletion.
"""
ttl_seconds: Optional[int]
def __new__(cls, text: str, ttl_seconds: Optional[int] = None):
instance = super().__new__(cls, text)
instance.ttl_seconds = ttl_seconds
return instance
@property
def text(self) -> str:
"""The underlying text (explicit form of ``str(reply)``)."""
return str.__str__(self)
def _invalidate_pending_stt_cache(event: MessageEvent) -> None:
"""Drop cached STT transcript attrs after media is merged into an event.
The gateway caches transcripts on the event via setattr; once the event gains
new media the stale transcript must go. Only the *derived* cache is dropped —
the echo ledger (``_gateway_pending_stt_echoed``) must survive, or the re-run
transcription would echo earlier notes a second time.
"""
for attr in ("_gateway_pending_stt_text", "_gateway_pending_stt_transcripts"):
if hasattr(event, attr):
delattr(event, attr)
def merge_pending_message_event(
pending_messages: Dict[str, MessageEvent],
session_key: str,
event: MessageEvent,
*,
merge_text: bool = False,
) -> None:
"""Store or merge a pending event for a session.
Photo bursts/albums arrive as several near-simultaneous PHOTO events; merge
them into the queued event so the next turn sees the whole burst. With
``merge_text``, rapid follow-up TEXT events are appended instead of replacing
the pending turn (Telegram bursty follow-ups are not truncated).
"""
existing = pending_messages.get(session_key)
if existing:
existing_is_photo = getattr(existing, "message_type", None) == MessageType.PHOTO
incoming_is_photo = event.message_type == MessageType.PHOTO
existing_has_media = bool(existing.media_urls)
incoming_has_media = bool(event.media_urls)
def _padded_inline_flags(msg: MessageEvent) -> List[Optional[bool]]:
flags = list(getattr(msg, "media_text_inlined", []) or [])
flags.extend([None] * max(0, len(msg.media_urls) - len(flags)))
return flags
incoming_inline_flags: List[Optional[bool]] = []
if incoming_has_media:
existing.media_text_inlined = _padded_inline_flags(existing)
incoming_inline_flags = _padded_inline_flags(event)
def _absorb_media() -> None:
existing.media_urls.extend(event.media_urls)
existing.media_types.extend(event.media_types)
existing.media_text_inlined.extend(incoming_inline_flags)
if event.text:
existing.text = BasePlatformAdapter._merge_caption(existing.text, event.text)
if existing_is_photo and incoming_is_photo:
_absorb_media()
_invalidate_pending_stt_cache(existing)
return
if existing_has_media or incoming_has_media:
if incoming_has_media:
_absorb_media()
elif event.text:
existing.text = BasePlatformAdapter._merge_caption(existing.text, event.text)
if existing_is_photo or incoming_is_photo:
existing.message_type = MessageType.PHOTO
elif (
getattr(existing, "message_type", None) == MessageType.TEXT
and event.message_type != MessageType.TEXT
):
existing.message_type = event.message_type
_invalidate_pending_stt_cache(existing)
return
if (
merge_text
and getattr(existing, "message_type", None) == MessageType.TEXT
and event.message_type == MessageType.TEXT
):
if event.text:
existing.text = _append_text(existing.text, event.text)
return
pending_messages[session_key] = event
# Substrings marking a transient *connection* failure worth retrying. Plain
# "timeout"/"timed out"/"readtimeout"/"writetimeout" are excluded on purpose: a
# read/write timeout on a non-idempotent send may have reached the server, so a
# retry risks duplicate delivery. "connecttimeout" is safe (never connected).
# Platforms that know a timeout is safe set SendResult.retryable explicitly.
_RETRYABLE_ERROR_PATTERNS = (
"connecterror", "connectionerror", "connectionreset", "connectionrefused", "connecttimeout",
"network", "broken pipe", "remotedisconnected", "eoferror",
)
# Type for message handlers. Handlers may return a plain string (normal
# reply), an ``EphemeralReply`` to opt the reply into auto-deletion, or
# ``None`` when the response was already delivered (e.g. via streaming).
MessageHandler = Callable[[MessageEvent], Awaitable[Optional[Union[str, "EphemeralReply"]]]]
def resolve_channel_prompt(config_extra: dict, channel_id: str, parent_id: str | None = None) -> str | None:
"""Resolve a per-channel ephemeral prompt from ``config.extra["channel_prompts"]``.
Exact *channel_id* match first, then *parent_id* (forum threads / child
channels inherit the parent prompt). Blank prompts count as absent.
"""
prompts = config_extra.get("channel_prompts") or {}
if not isinstance(prompts, dict):
return None
for key in (channel_id, parent_id):
if not key:
continue
prompt = prompts.get(key)
if prompt is None:
continue
prompt = str(prompt).strip()
if prompt:
return prompt
return None
def resolve_channel_skills(
config_extra: dict,
channel_id: str,
parent_id: str | None = None,
) -> list[str] | None:
"""Resolve auto-loaded skill(s) for a channel/thread from ``channel_skill_bindings``.
Config format::
channel_skill_bindings:
- id: "C0123" # Slack channel ID or Discord channel/forum ID
skills: ["skill-a", "skill-b"]
- id: "D0ABCDE"
skill: "solo-skill" # single string also accepted
Exact *channel_id* match first, then *parent_id* (threads inherit the parent
channel's binding). Returns a deduplicated, order-preserving list or None.
"""
bindings = config_extra.get("channel_skill_bindings") or []
if not isinstance(bindings, list) or not bindings:
return None
ids_to_check: set[str] = set()
if channel_id:
ids_to_check.add(str(channel_id))
if parent_id:
ids_to_check.add(str(parent_id))
if not ids_to_check:
return None
for entry in bindings:
if not isinstance(entry, dict):
continue
entry_id = str(entry.get("id", ""))
if entry_id in ids_to_check:
skills = entry.get("skills") or entry.get("skill")
if isinstance(skills, str):
s = skills.strip()
return [s] if s else None
if isinstance(skills, list) and skills:
seen: list[str] = []
for name in skills:
if not isinstance(name, str):
continue
nm = name.strip()
if nm and nm not in seen:
seen.append(nm)
return seen or None
return None
def _split_post_delivery_entry(entry: Any) -> Tuple[Optional[int], Any]:
"""``(generation, callback)`` from a post-delivery slot; legacy bare callbacks have no generation."""
if isinstance(entry, tuple) and len(entry) == 2:
return entry
return None, entry
def _lazy_attr(obj: Any, name: str, factory: Callable[[], Any]) -> Any:
"""``getattr(obj, name)`` or create it via ``factory`` — the getattr-guard for
tests that build adapters via ``object.__new__`` and never run ``__init__``."""
value = getattr(obj, name, None)
if value is None:
value = factory()
setattr(obj, name, value)
return value
def _strip_media_directives(text: str) -> str:
"""Backstop strip of delivery directives ([[audio_as_voice]], [[as_document]],
MEDIA:<path>) so they never render as text; run ``extract_media`` first.
Uses ``MEDIA_TAG_CLEANUP_RE`` (known-extension tags) plus validated
extension-less tags; unknown-extension tags are left for the bare-path detector.
"""
if not text:
return text
return _strip_media_tag_directives(text)
class BasePlatformAdapter(ABC):
"""Base class for platform adapters: connect/auth, receive, send, handle media."""
# Whether ``format_message`` renders triple-backtick fences as real code
# blocks. Tool-progress uses it to render a terminal command as a bare fenced
# block (no language tag — Slack mrkdwn would print it literally); plain-text
# platforms fall back to the short truncated preview (gateway/run.py).
supports_code_blocks: bool = False
# Whether the typing indicator renders TEXT (a status line by the bot name)
# rather than a native textless bubble. When True the gateway feeds per-tool
# phrases via set_status_text(); textless platforms keep the default False.
supports_status_text: bool = False
def set_status_text(self, chat_id: str, text: Optional[str]) -> None:
"""Set or clear (``None``) the live working-state phrase for a chat.
Cheap, in-memory only: the next typing refresh renders the new text.
No-op storage on adapters that never read ``_status_text``.
"""
store = _lazy_attr(self, "_status_text", dict)
if text:
store[str(chat_id)] = text
else:
store.pop(str(chat_id), None)
# Whether this adapter can wake a fresh turn AFTER a turn ends (background
# process / detached-subagent completions). False for stateless request/
# response adapters (API server) whose channel closes with the turn; the
# gateway propagates it to ``HERMES_SESSION_ASYNC_DELIVERY`` so tools never
# promise a delivery they can't keep.
supports_async_delivery: bool = True
# Whether ``send()`` chunks long content natively via ``truncate_message()``.
# When True the delivery router skips gateway-level truncation so full
# output survives. Default False (conservative); set True only when verified.
splits_long_messages: bool = False
# Prefix users can always TYPE to reach Hermes commands. Platforms whose
# client intercepts a leading "/" (Slack in threads, Matrix) ship a "!"
# alias rewrite and set "!" so instruction text names the form that works.
typed_command_prefix: str = "/"
# Whether the ``in_channel`` continuable-cron surface works here: the job is
# delivered FLAT into a channel and plain replies continue it via the
# whole-channel session bucket ``(platform, chat_id, None)`` — needs a
# flat-reply outbound gate too (today Slack, ``reply_in_thread: false``).
# Default False fails SAFE: ``in_channel`` degrades to ``thread``, never dropped.
supports_inchannel_continuable: bool = False
# Whether a human is present to answer a "session restored — what next?"
# prompt. Non-interactive event platforms (webhook) set False so the
# auto-resume turn finishes the interrupted work instead of asking nobody.
interactive_resume: bool = True
# Back-reference to the running ``GatewayRunner`` (injected by gateway/run.py).
# Declared on the base so EVERY adapter gets it: ``build_source`` resolves the
# inbound profile via ``runner._profile_name_for_source`` platform-generically.
gateway_runner = None # type: ignore[assignment] # set by gateway/run.py
def __init__(self, config: PlatformConfig, platform: Platform):
self.config = config
self.platform = platform
self._message_handler: Optional[MessageHandler] = None
# Gateway fan-out for platform-native reaction events (set_reaction_handler).
self._reaction_handler: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None
# Runner-owned boundary for normalized events (+ internal SessionSource):
# authorization/profile state never lives in an SDK adapter.
self._platform_event_handler: Optional[Callable[[Dict[str, Any], Any], Awaitable[None]]] = None
# Rewrites ``event.source.thread_id`` before session keying (Telegram DM topics).
self._topic_recovery_fn: Optional[Callable[[Any], Optional[str]]] = None
self._running = False
self._fatal_error_code: Optional[str] = None
self._fatal_error_message: Optional[str] = None
self._fatal_error_retryable = True
self._fatal_error_handler: Optional[Callable[["BasePlatformAdapter"], Awaitable[None] | None]] = None
# Strong refs to shielded fatal-error handler tasks: asyncio keeps only
# weak refs, so without this the loop can GC a detached handler mid-flight.
self._detached_fatal_tasks: set = set()
# Cross-HERMES_HOME lock takeover, armed by GatewayRunner only for the
# initial connect of an explicit ``gateway run --replace``; reconnects fail safe.
self._platform_lock_takeover_allowed = False
self._platform_lock_takeover_attempted = False
# Per-session interrupt Event + owner Task so /stop, /new, /reset cancel the
# right task; without the owner map an old task's finally could drop a newer guard.
self._active_sessions: Dict[str, asyncio.Event] = {}
self._pending_messages: Dict[str, MessageEvent] = {}
self._session_tasks: Dict[str, asyncio.Task] = {}
# Legacy env knob; the runner syncs the busy_input_mode-derived value after
# construction. Default "interrupt" so a pre-sync read never silently queues.
self._busy_text_mode: str = (
os.environ.get("HERMES_GATEWAY_BUSY_TEXT_MODE", "interrupt").strip().lower() or "interrupt"
)
self._busy_text_debounce_seconds: float = _float_env("HERMES_GATEWAY_BUSY_TEXT_DEBOUNCE_SECONDS", 0.35)
self._busy_text_hard_cap_seconds: float = _float_env("HERMES_GATEWAY_BUSY_TEXT_HARD_CAP_SECONDS", 1.0)
self._text_debounce: dict[str, TextDebounceState] = {}
# handle_message() tasks; shutdown cancels them so a replaced gateway stops working.
self._background_tasks: set[asyncio.Task] = set()
# Post-delivery one-shots keyed by session_key: bare callback (legacy) or
# ``(generation, callback)`` so a stale run can't clear a fresher run's callback.
self._post_delivery_callbacks: Dict[str, Any] = {}
self._expected_cancelled_tasks: set[asyncio.Task] = set()
self._busy_session_handler: Optional[Callable[[MessageEvent, str], Awaitable[bool]]] = None
# Owning multiplex profile (None on primary/single-profile). Needed because
# ``source.profile`` is stamped only after adapter ingress — see _session_key_profile.
self._owner_profile: Optional[str] = None
# Registered by GatewayRunner; adapters that fetch external context (Slack
# thread history) mark non-allowlisted senders unverified (prompt-injection mitigation).
self._authorization_check: Optional[Callable[[str, Optional[str], Optional[str]], bool]] = None
# Auto-TTS on voice input: global default (``voice.auto_tts``) plus per-chat
# opt-in (``/voice on|tts``, fires even if default False) / opt-out (``/voice off``).
self._auto_tts_default: bool = False
self._auto_tts_enabled_chats: set = set()
self._auto_tts_disabled_chats: set = set()
# Turn keys where streaming TTS already delivered audio; whole-file auto-TTS skips them.
self._streaming_tts_completed_turns: set[str] = set()
# Chats whose typing indicator is paused (approval waits); _keep_typing skips them.
self._typing_paused: set = set()
# Per-chat working-state phrase read by text-rendering typing indicators (Slack);
# the regular _keep_typing refresh picks it up, so updates cost no extra API calls.
self._status_text: Dict[str, str] = {}
@property
def message_len_fn(self) -> Callable[[str], int]:
"""Return the length function for measuring message size on this platform.
Override in adapters whose platform counts characters differently from
Python ``len`` (e.g. Telegram counts UTF-16 code units).
"""
return len
def max_message_length_for_chat(self, chat_id: str) -> int:
"""Per-chat max message length, in ``message_len_fn_for_chat`` units.
Default: the adapter-scalar ``MAX_MESSAGE_LENGTH`` (4096 when absent) —
for a native adapter every chat lives on the same platform so the
scalar is already correct. The relay adapter overrides this: one relay
adapter fronts N platforms with different caps (Discord 2000 vs
Telegram 4096 vs Slack 39000), and the right cap depends on which
platform the chat's inbound arrived from.
"""
try:
return int(getattr(self, "MAX_MESSAGE_LENGTH", 4096) or 4096)
except (TypeError, ValueError):
return 4096
def message_len_fn_for_chat(self, chat_id: str) -> Callable[[str], int]:
"""Per-chat length function (companion to max_message_length_for_chat).
Default: the adapter-wide ``message_len_fn``. The relay adapter
overrides it so a Telegram-fronted chat measures UTF-16 units while a
Discord-fronted chat on the same adapter measures codepoints.
"""
return self.message_len_fn
@property
def enforces_own_access_policy(self) -> bool:
"""Whether this adapter enforces its own config-driven access policy at intake
(``dm_policy``/``group_policy``/``allow_from``: WeCom, Weixin, QQBot, WhatsApp…).
The gateway env allowlist runs *after* the adapter; with no env allowlist it
trusts this flag ONLY when the effective policy is a real ``"allowlist"`` —
never ``"open"`` (the default), which forwards every sender and would be a
network-exposed fail-open (SECURITY.md §2.6). Open access still requires
``{PLATFORM}_ALLOW_ALL_USERS`` / ``GATEWAY_ALLOW_ALL_USERS``.
"""
return False
@property
def authorization_is_upstream(self) -> bool:
"""Whether inbound was already authorized by a TRUSTED UPSTREAM (relay only).
Unlike ``enforces_own_access_policy`` there is no local policy to mirror and
the env allowlist doesn't apply: the Team Gateway connector authenticates the
WebSocket and resolves owner-only author binding BEFORE delivery, so the
no-allowlist default-deny would be wrong. This is authorization DELEGATED,
not ABSENT — every network-exposed direct adapter leaves it ``False``.
"""
return False
def supports_draft_streaming(
self,
chat_type: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
chat_id: Optional[str] = None,
) -> bool:
"""Whether this adapter supports native streaming-draft updates.
Adapters implementing ``send_draft`` (Telegram ``sendMessageDraft``, DMs
only) return True for the chat types the platform supports; ``chat_id``
lets the relay adapter answer per the chat's negotiated capabilities.
Consumers fall back to ``send`` + ``edit_message`` when this is False or
``send_draft`` raises.
"""
return False
def prefers_fresh_final_streaming(self, content: str, metadata: Optional[Dict[str, Any]] = None) -> bool:
"""Whether the stream consumer should finalize by sending a *fresh* final
message (best-effort deleting the preview) instead of final-editing it.
Telegram overrides: final replies use ``sendRichMessage`` but the preview
edit path is still MarkdownV2, so re-delivering keeps the rich rendering.
"""
return False
def streaming_overflow_limit(self) -> Optional[int]:
"""Max single-message length (``message_len_fn`` units) the stream consumer
may accumulate before splitting, for adapters whose rich send/draft path
exceeds the legacy per-message cap (Telegram Rich Messages: 32,768 vs 4,096).
The live edit preview stays bound by the edit limit; the final reply is whole.
Return ``None`` (default) to use ``MAX_MESSAGE_LENGTH``.
"""
return None
async def send_draft(
self,
chat_id: str,
draft_id: int,
content: str,
metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
"""Send or update an animated streaming-draft preview.
Reuse one non-zero ``draft_id`` across calls of a single response so the
platform animates instead of re-creating; different responses in the same
chat must use different ids. Drafts have no message_id and cannot be
edited/replied/deleted — the final answer goes out as a regular ``send``.
Must be overridden by adapters returning True from :meth:`supports_draft_streaming`.
"""
raise NotImplementedError(f"{type(self).__name__} does not implement send_draft")
# ── Structured stream-event rendering ────────────────────────────────
# Adapters decide *how* to present each structured streaming event
# (gateway/stream_events.py); the defaults reproduce historical behaviour.
# Presentation-only contract: nothing rendered here is persisted, so what
# an adapter "eats" never changes the bytes the agent stored in history.
def render_message_event(self, event: Any, sink: Any) -> None:
"""Render a MessageChunk / MessageStop / Commentary onto the sink.
Default: map onto the stream consumer's existing primitives, preserving
today's behavior 1:1. ``sink`` is a GatewayStreamConsumer.
"""
from gateway.stream_events import MessageChunk, MessageStop, Commentary
if isinstance(event, MessageChunk):
if event.text:
sink.on_delta(event.text)
elif isinstance(event, MessageStop):
# Intermediate stop (text → tool → text) = segment break; the
# terminal stop is signalled by the gateway via finish(), not here.
if not event.final:
sink.on_segment_break()
elif isinstance(event, Commentary) and event.text:
sink.on_commentary(event.text)
def format_tool_event(self, event: Any, *, mode: str = "all", preview_max_len: int = 40) -> Optional[str]:
"""Return the rendered chrome for a ToolCallChunk, or None to eat it.
Adapters that cannot render tool chrome (no editing, plain text) override
to return None so the event is dropped rather than spamming bubbles.
``mode`` is the tool-progress mode ("all"/"new"/"verbose"); ``preview_max_len``
mirrors ``tool_preview_length`` (0 = no cap in verbose mode).
"""
from gateway.stream_events import ToolCallChunk
if not isinstance(event, ToolCallChunk):
return None
from agent.display import get_tool_emoji
emoji = get_tool_emoji(event.tool_name, default="⚙️")
if mode == "verbose":
if event.args:
import json
args_str = json.dumps(event.args, ensure_ascii=False, default=str)
if preview_max_len > 0 and len(args_str) > preview_max_len:
args_str = args_str[:preview_max_len - 3] + "..."
return f"{emoji} {event.tool_name}({list(event.args.keys())})\n{args_str}"
if event.preview:
return f"{emoji} {event.tool_name}: \"{event.preview}\""
return f"{emoji} {event.tool_name}..."
# "all" / "new": short preview, capped (default 40 to keep gateway
# progress bubbles compact — they persist as permanent messages).
preview = event.preview
if preview:
from agent.display import prepare_tool_preview
cap = preview_max_len if preview_max_len > 0 else 40
prepared = prepare_tool_preview(event.tool_name, event.args, fallback=preview, max_len=cap)
rendered = self.format_tool_preview(prepared)
return f"{emoji} {event.tool_name}: \"{rendered}\""
return f"{emoji} {event.tool_name}..."
def format_tool_preview(self, preview: "ToolPreview") -> str:
"""Apply platform-native formatting to a compact tool preview.
Most adapters only need the compact text. Rich-text adapters can use
the preview's explicit metadata to preserve details such as a URL that
was shortened for display.
"""
return preview.text
@property
def has_fatal_error(self) -> bool:
return self._fatal_error_message is not None
@property
def fatal_error_message(self) -> Optional[str]:
return self._fatal_error_message
@property
def fatal_error_code(self) -> Optional[str]:
return self._fatal_error_code
@property
def fatal_error_retryable(self) -> bool:
return self._fatal_error_retryable
def _should_auto_tts_for_chat(self, chat_id: str) -> bool:
"""Whether auto-TTS fires for ``chat_id``: explicit ``/voice on|tts`` wins,
then explicit ``/voice off``, then the global ``voice.auto_tts`` default."""
if chat_id in self._auto_tts_enabled_chats:
return True
if chat_id in self._auto_tts_disabled_chats:
return False
return bool(self._auto_tts_default)
def set_fatal_error_handler(self, handler: Callable[["BasePlatformAdapter"], Awaitable[None] | None]) -> None:
self._fatal_error_handler = handler
def _mark_connected(self) -> None:
self._running = True
self._fatal_error_code = None
self._fatal_error_message = None
self._fatal_error_retryable = True
self._write_runtime_status_safe("connected", platform_state="connected", error_code=None, error_message=None)
def _mark_disconnected(self) -> None:
self._running = False
if self.has_fatal_error:
return
self._write_runtime_status_safe("disconnected", platform_state="disconnected", error_code=None, error_message=None)
def _set_fatal_error(self, code: str, message: str, *, retryable: bool) -> None:
self._running = False
self._fatal_error_code = code
self._fatal_error_message = message
self._fatal_error_retryable = retryable
self._write_runtime_status_safe("fatal", platform_state="fatal", error_code=code, error_message=message)
def _write_runtime_status_safe(self, context: str, **kwargs) -> None:
"""Write runtime status; log first failure per context at warning, rest at debug.
Failures (permissions, ENOSPC, missing dir) must neither be silent nor
spam the log on reconnect loops.
"""
try:
from gateway.status import write_runtime_status
# Multiplexed secondary adapters share the runtime status file; their
# runner stamps a ``<profile>:<platform>`` key so profiles don't clobber.
platform_key = getattr(self, "_runtime_status_platform_key", None) or self.platform.value
write_runtime_status(platform=platform_key, **kwargs)
except Exception as exc:
# getattr-guard: tests build adapters via object.__new__ (no __init__).
logged = getattr(self, "_status_write_logged", None)
if logged is None:
logged = set()
try:
self._status_write_logged = logged
except Exception:
pass
key = (self.platform.value, context)
first = key not in logged
logged.add(key)
(logger.warning if first else logger.debug)(
"Failed to write runtime status (%s) for %s: %s" + (" (further failures at debug level)" if first else ""),
context, self.platform.value, exc,
)
async def _notify_fatal_error(self) -> None:
handler = self._fatal_error_handler
if not handler:
return
result = handler(self)
if asyncio.iscoroutine(result):
# Detached + shielded: this is often awaited from an adapter-owned task
# that the handler's ``disconnect()`` cancels. Unshielded, the handler
# died mid-flight — adapter popped but never queued for reconnect.
task = asyncio.ensure_future(result)
# Strong ref so the loop's weak-ref task table can't GC the handler.
_tasks = _lazy_attr(self, "_detached_fatal_tasks", set)
_tasks.add(task)
task.add_done_callback(_tasks.discard)
try:
await asyncio.shield(task)
except asyncio.CancelledError:
# Carrier cancelled (typically by our own teardown inside the
# handler): let it finish detached so reconnect/shutdown decisions
# complete, and consume its exception to avoid "never retrieved" noise.
if not task.done():
task.add_done_callback(_consume_detached_handler_exception)
raise
def _acquire_platform_lock(self, scope: str, identity: str, resource_desc: str) -> bool:
"""Acquire a scoped lock for this adapter. Returns True on success.
A live cross-HERMES_HOME holder may be replaced only when the runner
explicitly arms this adapter for its initial ``--replace`` connect.
The status module validates PID/start-time/home ownership, places the
marker in the target's home, and performs the bounded termination.
"""
from gateway.status import (
acquire_scoped_lock,
scoped_lock_owner_label,
take_over_scoped_lock_holder,
)
self._platform_lock_scope = scope
self._platform_lock_identity = identity
lock_meta = {"platform": self.platform.value}
acquired, existing = acquire_scoped_lock(scope, identity, metadata=lock_meta)
if acquired:
return True
takeover_allowed = bool(getattr(self, "_platform_lock_takeover_allowed", False))
takeover_attempted = bool(getattr(self, "_platform_lock_takeover_attempted", False))
if takeover_allowed and not takeover_attempted and isinstance(existing, dict):
# Consume the authority before doing any I/O: one adapter connect
# gets at most one termination attempt, even if lock re-acquire or
# later initialization fails.
self._platform_lock_takeover_allowed = False
self._platform_lock_takeover_attempted = True
owner_pid = take_over_scoped_lock_holder(existing)
if owner_pid is not None:
logger.warning(
"[%s] %s was held by gateway PID %d — explicit --replace handoff completed",
self.name, resource_desc, owner_pid,
)
acquired, existing = acquire_scoped_lock(scope, identity, metadata=lock_meta)
if acquired:
logger.info("[%s] Acquired %s after taking over PID %d", self.name, resource_desc, owner_pid)
return True
owner_pid = existing.get('pid') if isinstance(existing, dict) else None
# Scoped locks are machine-global: name the owning profile when known so
# the operator can tell WHICH gateway holds the credential.
owner_profile = scoped_lock_owner_label(existing)
pid_part = f" (PID {owner_pid})" if owner_pid else ""
if owner_profile:
holder = f" by the '{owner_profile}' profile gateway{pid_part}"
remedy = f" Stop that gateway first (hermes --profile {owner_profile} gateway stop)."
else:
holder = pid_part
remedy = " Stop the other gateway first."
message = f"{resource_desc} already in use{holder}.{remedy}"
logger.error('[%s] %s', self.name, message)
self._set_fatal_error(f'{scope}_lock', message, retryable=True)
return False
def _release_platform_lock(self) -> None:
"""Release the scoped lock acquired by _acquire_platform_lock."""
identity = getattr(self, '_platform_lock_identity', None)
if not identity:
return
from gateway.status import release_scoped_lock
release_scoped_lock(self._platform_lock_scope, identity)
self._platform_lock_identity = None
def _wire_plugin_handlers(self, native: Any = None) -> None:
"""Invoke plugin-registered native handler factories for this platform.
Plugins register via ``ctx.register_platform_handler(<platform>, factory)``;
adapters call this from ``connect()`` once the native client exists (before
their own handlers when dispatch order matters). Each factory receives
``(native, adapter)`` — ``native`` may be ``None`` — and is isolated so a
misbehaving plugin can't prevent the platform from connecting.
"""
platform_name = getattr(self.platform, "value", str(self.platform))
try:
from hermes_cli.plugins import get_plugin_manager
factories = get_plugin_manager().get_platform_handler_factories(platform_name)
except Exception as e: # pragma: no cover - defensive
logger.warning("[%s] Could not load plugin handler factories: %s", self.name, e)
return
for factory, plugin_name in factories:
try:
factory(native, self)
logger.info("[%s] Wired native handlers from plugin '%s'", self.name, plugin_name)
except Exception as exc:
logger.error(
"[%s] Plugin '%s' handler factory raised: %s",
self.name, plugin_name, exc, exc_info=True,
)
@property
def name(self) -> str:
"""Human-readable name for this adapter."""
return self.platform.value.title()
@property
def is_connected(self) -> bool:
"""Check if adapter is currently connected."""
return self._running
def set_message_handler(self, handler: MessageHandler) -> None:
"""Set the incoming-message handler (MessageEvent -> optional response str)."""
self._message_handler = handler
def set_platform_event_handler(
self,
handler: Optional[Callable[[Dict[str, Any], Any], Awaitable[None]]],
) -> None:
"""Install the gateway-owned normalized platform-event boundary.
Adapters pass only stable dicts plus an internal ``SessionSource``; the
runner owns authorization and plugin dispatch, so no callback = fail closed.
"""
self._platform_event_handler = handler
def set_topic_recovery_fn(self, fn: Optional[Callable[[Any], Optional[str]]]) -> None:
"""Install a thread_id-recovery hook (Telegram DM topic mode): called with
``event.source`` before session keying; a non-None return replaces
``source.thread_id``. ``None`` clears the hook."""
# getattr-guard: tests build adapters via object.__new__ (no __init__).
self._topic_recovery_fn = fn # type: ignore[attr-defined]
def _apply_topic_recovery(self, event: MessageEvent) -> None:
"""Rewrite ``event.source.thread_id`` in place if the hook returns one."""
recover = getattr(self, "_topic_recovery_fn", None)
if recover is None:
return
source = getattr(event, "source", None)
if source is None:
return
try:
recovered = recover(source)
except Exception:
logger.debug("topic recovery hook failed", exc_info=True)
return
if recovered is None or str(recovered) == str(source.thread_id or ""):
return
try:
event.source = dataclasses.replace(source, thread_id=str(recovered))
except Exception:
logger.debug("topic recovery rewrite failed", exc_info=True)
def set_busy_session_handler(self, handler: Optional[Callable[[MessageEvent, str], Awaitable[bool]]]) -> None:
"""Set an optional handler for messages arriving during active sessions."""
self._busy_session_handler = handler
def set_reaction_handler(self, handler: Optional[Callable[[Dict[str, Any]], Awaitable[None]]]) -> None:
"""Set the handler for platform-native emoji-reaction events.
The handler takes a normalised dict — ``platform``, ``event_name``
("reaction:added"/"reaction:removed"), ``reaction``, ``user_id``,
``item_user_id``, ``channel_id``, ``message_ts``, ``event_ts``,
``raw_event`` — and fans out via ``HookRegistry.emit``. Adapters
without reaction support never call it.
"""
# getattr-guard: tests build adapters via object.__new__ (no __init__).
self._reaction_handler = handler # type: ignore[attr-defined]
def set_authorization_check(
self,
callback: Optional[Callable[[str, Optional[str], Optional[str]], bool]],
) -> None:
"""Register ``(user_id, chat_type, chat_id) -> bool``; adapters that pull
external context (Slack thread replies) use it to flag non-allowlisted
senders as unverified background rather than authoritative input."""
self._authorization_check = callback
def _is_sender_authorized(
self,
user_id: Optional[str],
chat_type: Optional[str] = None,
chat_id: Optional[str] = None,
*,
is_bot: bool = False,
thread_id: Optional[str] = None,
) -> Optional[bool]:
"""True/False from the registered check, or ``None`` when no check exists
("trust unknown", legacy behaviour).
``is_bot``/``thread_id`` are forwarded as keywords only when set so legacy
three-positional callbacks keep working. Only literal booleans propagate:
a truthy non-boolean (status string, sentinel) is "unknown", never coerced
into an authorization that gates a credentialed side effect.
"""
if not user_id or self._authorization_check is None:
return None
extra: Dict[str, Any] = {}
if is_bot:
extra["is_bot"] = True
if thread_id is not None:
extra["thread_id"] = thread_id
try:
result = self._authorization_check(user_id, chat_type, chat_id, **extra)
if result is True or result is False:
return result
logger.warning(
"[%s] Authorization check returned %s for user %s; treating as unknown",
self.name, type(result).__name__, user_id,
)
return None
except Exception:
logger.warning(
"[%s] Authorization check raised for user %s; treating as unknown",
self.name, user_id, exc_info=True,
)
return None
def set_session_store(self, session_store: Any) -> None:
"""Set the session store (e.g. Slack checks for an active thread session
before handling un-mentioned replies)."""
self._session_store = session_store
def set_owner_profile(self, profile_name: Optional[str]) -> None:
"""Declare the owning multiplex profile (secondary profiles only); read by
:meth:`_session_key_profile` so adapter-level keys leave ``agent:main:``."""
name = (profile_name or "").strip() or None
self._owner_profile = None if name == "default" else name
def _session_key_profile(self, source: Optional[Any] = None) -> Optional[str]:
"""Resolve the profile namespace for an adapter-derived session key.
Ingress runs BEFORE the runner stamps ``source.profile``, so without this
every bot in a multiplexed gateway shares one ``agent:main:`` lane (every
Telegram DM has the same chat id). Order: ``source.profile`` → ``_owner_profile``
→ session-store resolver. getattr-guard throughout (object.__new__ in tests);
candidates are type-checked so a MagicMock never lands in the key.
"""
for candidate in (
getattr(source, "profile", None) if source is not None else None,
getattr(self, "_owner_profile", None),
):
if isinstance(candidate, str) and candidate.strip():
return candidate
store = getattr(self, "_session_store", None)
resolver = getattr(store, "_resolve_profile_for_key", None) if store else None
if callable(resolver):
try:
resolved = resolver(source)
except Exception:
return None
if isinstance(resolved, str) and resolved.strip():
return resolved
return None
# ------------------------------------------------------------------
# Inbound text batching (shared by adapters that merge split messages).
# Subclasses supply ``_pending_text_batches`` / ``_pending_text_batch_tasks``
# dicts and ``_flush_text_batch(key)``; they may override either hook.
# ------------------------------------------------------------------
def _event_session_key(self, event: "MessageEvent") -> str:
"""Adapter-level session key for ``event``, profile-namespaced like the agent run."""
return build_session_key(
event.source,
group_sessions_per_user=self.config.extra.get("group_sessions_per_user", True),
thread_sessions_per_user=self.config.extra.get("thread_sessions_per_user", False),
profile=self._session_key_profile(event.source),
)
def _text_batch_key(self, event: "MessageEvent") -> str:
"""Session-scoped key for text batching (subclasses may override)."""
return self._event_session_key(event)
def _enqueue_text_event(self, event: "MessageEvent") -> None:
"""Buffer a text event (merging into a pending one) and restart the flush timer."""
key = self._text_batch_key(event)
existing = self._pending_text_batches.get(key)
chunk_len = len(event.text or "")
if existing is None:
event._last_chunk_len = chunk_len # type: ignore[attr-defined]
self._pending_text_batches[key] = event
else:
if event.text:
existing.text = _append_text(existing.text, event.text)
existing._last_chunk_len = chunk_len # type: ignore[attr-defined]
if event.media_urls:
existing.media_urls.extend(event.media_urls)
existing.media_types.extend(event.media_types)
prior_task = self._pending_text_batch_tasks.get(key)
if prior_task and not prior_task.done():
prior_task.cancel()
self._pending_text_batch_tasks[key] = asyncio.create_task(self._flush_text_batch(key))
def _history_media_paths_for_session(self, session_key: str) -> Optional[set]:
"""Return media paths already delivered in prior turns of this session
(MEDIA: tags / image_generate payloads), so an echoed old tag isn't re-sent."""
store = getattr(self, "_session_store", None)
if not store:
return None
try:
# Transcripts are keyed by session_id, not gateway session_key; map via
# the routing index, falling back to the raw key for stores that accept either.
session_id = None
peek = getattr(store, "peek_session_id", None)
if callable(peek):
session_id = peek(session_key)
transcript = store.load_transcript(session_id or session_key)
except Exception:
return None
if not transcript:
return None
# Exclude the CURRENT TURN entirely (from the last user message onward):
# rows are persisted as produced, so this turn's tool results are already
# there and a text_to_speech media_tag would dedup away its own attachment.
history = list(transcript)
last_user_idx = None
for i in range(len(history) - 1, -1, -1):
if history[i].get("role") == "user":
last_user_idx = i
break
if last_user_idx is not None:
history = history[:last_user_idx]
else:
# No user row (unusual store shape): at least drop the trailing reply.
for msg in reversed(history):
if msg.get("role") == "assistant":
history.remove(msg)
break
if not history:
return None
# Avoid circular import: gateway.run already imports this module.
from gateway.run import _collect_history_media_paths
return _collect_history_media_paths(history)
async def _bounded_history_media_paths_for_session(self, session_key: str) -> Optional[set]:
"""Run best-effort history lookup in a bounded isolated daemon thread."""
def _fail_open(reason: str, *, exc_info: bool = False) -> None:
logger.warning(
"[%s] " + reason + " %s; delivering bare local file path(s) without history dedup",
self.name, session_key, exc_info=exc_info,
)
admission = _HISTORY_MEDIA_LOOKUP_ADMISSION
if not admission.acquire(blocking=False):
_fail_open("Media-delivery history lookup capacity exhausted for")
return None
loop = asyncio.get_running_loop()
result_future = loop.create_future()
def _publish_result(result=None, error=None):
if result_future.done():
return
if error is not None:
result_future.set_exception(error)
else:
result_future.set_result(result)
def _worker():
result, error = None, None
try:
result = self._history_media_paths_for_session(session_key)
except BaseException as exc:
error = exc
try:
loop.call_soon_threadsafe(_publish_result, result, error)
except RuntimeError:
pass # Event loop already closed during gateway shutdown.
finally:
admission.release()
try:
threading.Thread(target=_worker, name="media-history-lookup", daemon=True).start()
except Exception:
# start() failed (thread exhaustion): the worker never ran, so release
# the permit here or it leaks; fail open like every other path. Plain
# Exception on purpose — don't eat KeyboardInterrupt/SystemExit.
admission.release()
_fail_open("Could not start media-delivery history lookup worker for", exc_info=True)
return None
try:
return await asyncio.wait_for(result_future, timeout=_HISTORY_MEDIA_LOOKUP_TIMEOUT_SECONDS)
except asyncio.TimeoutError:
_fail_open("Timed out loading media-delivery history for")
return None
except Exception:
# Best-effort/fail-open: never let a lookup failure kill media delivery.
_fail_open("Media-delivery history lookup failed for", exc_info=True)
return None
@abstractmethod
async def connect(self, *, is_reconnect: bool = False) -> bool:
"""Connect to the platform and start receiving messages; True on success.
``is_reconnect`` is True when the reconnect watcher re-establishes a
dropped platform: adapters with a server-side update queue (Telegram)
must preserve it so outage-time messages aren't silently discarded.
"""
pass
@abstractmethod
async def disconnect(self) -> None:
"""Disconnect from the platform."""
pass
@abstractmethod
async def send(
self,
chat_id: str,
content: str,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None
) -> SendResult:
"""Send ``content`` (may be markdown) to a chat; returns SendResult with message id."""
pass
# True for surfaces that need an explicit finalize edit to close the message
# lifecycle (DingTalk AI Cards), so the stream consumer never skips it.
REQUIRES_EDIT_FINALIZE: bool = False
async def create_handoff_thread(self, parent_chat_id: str, name: str) -> Optional[str]:
"""Create a fresh thread under ``parent_chat_id`` for a CLI→platform session
handoff (clean per-handoff scrollback).
Return the thread/topic id as a string, or ``None`` when threading is
unsupported or failed — the watcher then uses ``parent_chat_id`` directly.
Thread-capable adapters (Telegram topics, Discord threads, Slack) override.
"""
return None
async def edit_message(
self,
chat_id: str,
message_id: str,
content: str,
*,
finalize: bool = False,
) -> SendResult:
"""Edit a sent message. Optional: return success=False and callers send anew.
``finalize`` marks the last edit of a streamed response. Most platforms
ignore it; surfaces with a distinct "in progress" state (DingTalk AI Cards)
use it to close the message and should also set ``REQUIRES_EDIT_FINALIZE``
so the final edit is routed even when content is unchanged.
"""
return SendResult(success=False, error="Not supported")
async def delete_message(self, chat_id: str, message_id: str) -> bool:
"""Delete a sent message; ``True`` on success. Optional: platforms without a
deletion API return ``False`` and callers leave the message in place.
Used by the stream consumer's fresh-final cleanup to remove stale previews.
"""
return False
def _get_ephemeral_system_ttl_default(self) -> int:
"""Default :class:`EphemeralReply` TTL from ``display.ephemeral_system_ttl``
(``0`` = no auto-delete); non-fatal if config is unreadable."""
try:
return int(_config_section("display").get("ephemeral_system_ttl", 0))
except (TypeError, ValueError):
return 0
def _schedule_ephemeral_delete(self, chat_id: str, message_id: str, ttl_seconds: int) -> None:
"""Spawn a detached task that deletes ``message_id`` after ``ttl_seconds``.
Best-effort — failures (gateway restart, permission denied, message
too old for Telegram's 48h window) are swallowed at debug level.
Does not block the caller.
"""
async def _run_delete() -> None:
try:
await asyncio.sleep(max(1, int(ttl_seconds)))
await self.delete_message(chat_id=chat_id, message_id=message_id)
except asyncio.CancelledError:
raise
except Exception as e:
logger.debug("[%s] Ephemeral delete failed for %s/%s: %s", self.name, chat_id, message_id, e)
coro = _run_delete()
try:
asyncio.create_task(coro)
except RuntimeError:
# No running loop (unit tests): close the coroutine to avoid a
# never-awaited warning, then drop silently.
coro.close()
# ── Shared interactive-prompt formatting cores ─────────────────────────
# ``_format_exec_approval`` templates; adapters override to keep their
# historical wording byte-identical while sharing the assembly logic.
_EA_HEADER: str = "⚠️ Command Approval Required\n\n"
_EA_CODE_OPEN: str = "```\n"
_EA_CODE_CLOSE: str = "\n```\n"
_EA_REASON_LABEL: str = "Reason: "
_EA_SMART_DENY_LINE: str = "\n\nSmart DENY: owner override applies to this one operation only."
_EA_CMD_BUDGET: int = 3000
@staticmethod
def _truncate_preview(text: str, budget: int, suffix: str = "...") -> str:
"""Truncate ``text`` to ``budget`` chars, appending ``suffix`` when cut."""
text = str(text or "")
return text[:budget] + suffix if len(text) > budget else text
def _ea_escape(self, text: str) -> str:
"""Escape hook for command preview/reason; HTML-mode platforms (Telegram) override."""
return text
def _format_exec_approval(
self,
command: str,
description: str = "dangerous command",
smart_denied: bool = False,
) -> str:
"""Shared exec-approval prompt text: header + fenced (truncated) command +
reason, plus the smart-deny line. Buttons and trailing instructions
(reaction legends) stay platform-local, appended to this core."""
cmd_preview = self._truncate_preview(str(command or ""), self._EA_CMD_BUDGET)
text = (
f"{self._EA_HEADER}"
f"{self._EA_CODE_OPEN}{self._ea_escape(cmd_preview)}{self._EA_CODE_CLOSE}"
f"{self._EA_REASON_LABEL}{self._ea_escape(description)}"
)
if smart_denied:
text += self._EA_SMART_DENY_LINE
return text
@staticmethod
def _format_choice_page(options: list, page: int, per_page: int) -> "tuple[list, Dict[str, Any]]":
"""Shared picker pagination: clamp ``page``, slice ``options``, return
``(page_options, meta)`` with ``page``/``total_pages``/``start``/``end``/
``total``/``page_info`` (the `` (N–M of T)`` suffix, empty for one page)."""
total = len(options)
total_pages = max(1, (total + per_page - 1) // per_page)
page = max(0, min(page, total_pages - 1))
start = page * per_page
end = min(start + per_page, total)
page_info = f" ({start + 1}–{end} of {total})" if total_pages > 1 else ""
meta: Dict[str, Any] = {
"page": page,
"total_pages": total_pages,
"start": start,
"end": end,
"total": total,
"page_info": page_info,
}
return options[start:end], meta
async def send_slash_confirm(
self,
chat_id: str,
title: str,
message: str,
session_key: str,
confirm_id: str,
metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
"""Send a three-option slash-command confirmation (e.g. ``/reload-mcp``).
Button-capable adapters override to render Approve Once / Always Approve /
Cancel and MUST resolve via ``GatewayRunner._resolve_slash_confirm(confirm_id,
choice)`` with ``"once"``/``"always"``/``"cancel"``. The default (not supported)
falls through to the gateway text fallback (``/approve``/``/always``/``/cancel``).
"""
return SendResult(success=False, error="Not supported")
async def send_clarify(
self,
chat_id: str,
question: str,
choices: Optional[list],
clarify_id: str,
session_key: str,
metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
"""Send a clarify prompt; button-capable adapters SHOULD override.
Multiple choice (``choices`` non-empty): render one button per choice plus
"Other"; callbacks MUST resolve via
``tools.clarify_gateway.resolve_gateway_clarify(clarify_id, response)``,
and "Other" calls ``mark_awaiting_text(clarify_id)``. Open-ended: send the
question as text; the gateway text-intercept resolves the next message.
Default: numbered text list + ``mark_awaiting_text`` so replies aren't lost.
"""
if choices:
# Multi-select flag lives on the pending entry; look it up by id so
# the signature stays adapter-compatible.
_is_multi = False
try:
from tools import clarify_gateway as _cg
with _cg._lock:
_entry = _cg._entries.get(clarify_id)
_is_multi = bool(_entry and getattr(_entry, "multi_select", False))
except Exception:
_is_multi = False
hint = (
"Multiple selections allowed — reply with the numbers separated by commas or "
"spaces (e.g. \"1, 3\"), the option text, or your own answer."
if _is_multi else "Reply with the number, the option text, or your own answer."
)
numbered = [f" {i}. {choice}" for i, choice in enumerate(choices, start=1)]
text = "\n".join([f"❓ {question}", "", *numbered, "", hint])
# Text fallback: let the gateway intercept capture the typed reply.
from tools.clarify_gateway import mark_awaiting_text
mark_awaiting_text(clarify_id)
else:
text = f"❓ {question}"
return await self.send(chat_id=chat_id, content=text, metadata=metadata)
async def send_private_notice(
self,
chat_id: str,
user_id: Optional[str],
content: str,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
"""Send a notice privately when the platform supports it; default is a normal send."""
return await self.send(chat_id=chat_id, content=content, reply_to=reply_to, metadata=metadata)
async def send_typing(self, chat_id: str, metadata=None) -> None:
"""Send a typing indicator; ``metadata`` carries platform context (Slack thread_id)."""
pass
async def stop_typing(self, chat_id: str) -> None:
"""Stop a persistent typing indicator; override where typing runs as a loop."""
pass
async def _stop_typing_with_metadata(self, chat_id: str, metadata=None) -> None:
"""Stop typing, forwarding ``metadata`` only if ``stop_typing`` accepts it.
Slack AI status is per thread, so dropping metadata could clear a sibling
thread; introspecting here keeps legacy ``stop_typing(chat_id)`` adapters working.
"""
if metadata:
try:
params = inspect.signature(self.stop_typing).parameters
accepts_metadata = "metadata" in params or any(
param.kind is inspect.Parameter.VAR_KEYWORD
for param in params.values()
)
except (TypeError, ValueError):
accepts_metadata = False
if accepts_metadata:
stop_typing = getattr(self, "stop_typing")
await stop_typing(chat_id, metadata=metadata)
return
await self.stop_typing(chat_id)
async def send_multiple_images(
self,
chat_id: str,
images: List[Tuple[str, str]],
metadata: Optional[Dict[str, Any]] = None,
human_delay: float = 0.0,
) -> None:
"""Send a batch of ``(url, alt)`` images (``http(s)://`` or ``file://``).
Default sends each individually (GIFs via ``send_animation``, local files
via ``send_image_file``); override to bundle into one native call (Signal).
"""
from urllib.parse import unquote as _unquote
for image_url, alt_text in images:
if human_delay > 0:
await asyncio.sleep(human_delay)
try:
logger.info(
"[%s] Sending image: %s (alt=%s)",
self.name, safe_url_for_log(image_url), alt_text[:30] if alt_text else "",
)
caption = alt_text if alt_text else None
if image_url.startswith("file://"):
img_result = await self.send_image_file(
chat_id=chat_id, image_path=_unquote(image_url[7:]), caption=caption, metadata=metadata,
)
elif self._is_animation_url(image_url):
img_result = await self.send_animation(
chat_id=chat_id, animation_url=image_url, caption=caption, metadata=metadata,
)
else:
img_result = await self.send_image(
chat_id=chat_id, image_url=image_url, caption=caption, metadata=metadata,
)
if not img_result.success:
logger.error("[%s] Failed to send image: %s", self.name, img_result.error)
except Exception as img_err:
logger.error("[%s] Error sending image: %s", self.name, img_err, exc_info=True)
async def send_image(
self,
chat_id: str,
image_url: str,
caption: Optional[str] = None,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
"""Send an image natively; default falls back to sending the URL as text."""
text = f"{caption}\n{image_url}" if caption else image_url
return await self.send(chat_id=chat_id, content=text, reply_to=reply_to, metadata=metadata)
async def send_animation(
self,
chat_id: str,
animation_url: str,
caption: Optional[str] = None,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
"""Send a GIF as a native animation (auto-plays inline); default falls back to send_image."""
return await self.send_image(chat_id=chat_id, image_url=animation_url, caption=caption, reply_to=reply_to, metadata=metadata)
@staticmethod
def _is_animation_url(url: str) -> bool:
"""Check if a URL points to an animated GIF (vs a static image)."""
lower = url.lower().split('?')[0] # Strip query params
return lower.endswith('.gif')
@staticmethod
def extract_images(content: str) -> Tuple[List[Tuple[str, str]], str]:
"""Extract ``![alt](url)`` and ``<img src=...>`` image URLs from a response.
Returns ``([(url, alt_text), ...], content with those tags removed)``.
"""
images = []
cleaned = content
# Match markdown images: ![alt](url)
md_pattern = r'!\[([^\]]*)\]\((https?://[^\s\)]+)\)'
for match in re.finditer(md_pattern, content):
alt_text = match.group(1)
url = match.group(2)
# Only extract URLs that look like actual images
if any(url.lower().endswith(ext) or ext in url.lower() for ext in
['.png', '.jpg', '.jpeg', '.gif', '.webp', 'fal.media', 'fal-cdn', 'replicate.delivery']):
images.append((url, alt_text))
# Match HTML img tags: <img src="url"> or <img src="url"></img> or <img src="url"/>
html_pattern = r'<img\s+src=["\']?(https?://[^\s"\'<>]+)["\']?\s*/?>\s*(?:</img>)?'
for match in re.finditer(html_pattern, content):
url = match.group(1)
images.append((url, ""))
# Remove only the tags we extracted, not every markdown image.
if images:
extracted_urls = {url for url, _ in images}
def _remove_if_extracted(match):
url = match.group(2) if match.lastindex >= 2 else match.group(1)
return '' if url in extracted_urls else match.group(0)
cleaned = re.sub(md_pattern, _remove_if_extracted, cleaned)
cleaned = re.sub(html_pattern, _remove_if_extracted, cleaned)
# Clean up leftover blank lines
cleaned = re.sub(r'\n{3,}', '\n\n', cleaned).strip()
return images, cleaned
async def send_voice(
self,
chat_id: str,
audio_path: str,
caption: Optional[str] = None,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs,
) -> SendResult:
"""Send audio as a native voice message (Telegram bubble / Discord attachment).
Default: friendly failure notice."""
return await self._send_media_fallback_notice(
"send_voice", "audio", audio_path, chat_id, caption, reply_to, metadata,
)
async def _send_media_fallback_notice(
self, method: str, kind: str, path: str, chat_id: str, caption: Optional[str],
reply_to: Optional[str], metadata: Optional[Dict[str, Any]], *, file_name: Optional[str] = None,
) -> SendResult:
"""Shared default for send_voice/send_video/send_document/send_image_file.
The local path is logged but NEVER echoed into chat (it would leak the host
layout); only the caller-supplied ``file_name`` is shown.
"""
logger.warning("[%s] %s fallback: native %s send unavailable for %s", self.name, method, kind, path)
text = _media_failure_text(kind, file_name)
if caption:
text = f"{caption}\n{text}"
return await self.send(chat_id=chat_id, content=text, reply_to=reply_to, metadata=metadata)
def prepare_tts_text(self, text: str) -> str:
"""Turn chat Markdown into a transcript-like spoken script: reasoning blocks
removed, headings/bullets flattened, units expanded (``°C`` → degrees Celsius).
Chunking and delivery limits are the TTS tool's job."""
try:
from tools.tts_text_normalize import prepare_spoken_text
return prepare_spoken_text(text, max_chars=None)
except Exception:
# Keep auto-TTS best-effort if the normalizer ever fails.
text = re.sub(r'<think[\s>].*?</think>', ' ', text, flags=re.DOTALL)
return re.sub(r'[*_`#\[\]()]', '', text).strip()
async def play_tts(self, chat_id: str, audio_path: str, **kwargs) -> SendResult:
"""Play auto-TTS audio; override for invisible playback (Web UI). Default: send_voice."""
return await self.send_voice(chat_id=chat_id, audio_path=audio_path, **kwargs)
# ------------------------------------------------------------------
# Streaming TTS adapter contract: voice-capable adapters (LiveKit, Discord
# voice) accept PCM chunks while the LLM generates. Defaults report
# "unsupported" so existing adapters keep the whole-file auto-TTS fallback.
# ------------------------------------------------------------------
def supports_streaming_tts(self, chat_id: str, audio_format: AudioFormat) -> bool:
"""Return True when this adapter can accept streaming PCM for *chat_id*."""
return False
async def begin_streaming_tts(
self,
chat_id: str,
audio_format: AudioFormat,
metadata: Optional[Dict[str, Any]] = None,
) -> Optional[StreamingTTSHandle]:
"""Open a streaming-audio session; returns an opaque handle for the
write/finish/abort calls, or ``None`` to decline (whole-file fallback)."""
return None
async def write_streaming_tts(self, handle: StreamingTTSHandle, chunk: bytes) -> None:
"""Write one PCM chunk to the adapter's outbound audio track."""
pass
async def finish_streaming_tts(self, handle: StreamingTTSHandle, *, interrupted: bool = False) -> None:
"""Signal normal end of the audio stream."""
pass
async def abort_streaming_tts(self, handle: StreamingTTSHandle, error: Optional[str] = None) -> None:
"""Abort the stream due to an error or cancellation.
Must be idempotent: late producer chunks after abort must be silently
dropped, not raise. Restores adapter state to "not streaming".
"""
pass
def _streaming_tts_turn_key(self, session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> str | None:
return streaming_tts_turn_key(session_key, turn_marker, event=event)
def _mark_streaming_tts_completed_turn(self, session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> None:
turn_key = self._streaming_tts_turn_key(session_key, turn_marker, event=event)
if turn_key is not None:
_lazy_attr(self, "_streaming_tts_completed_turns", set).add(turn_key)
def _streaming_tts_turn_completed(self, session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> bool:
return streaming_tts_should_skip_whole_file(
getattr(self, "_streaming_tts_completed_turns", set()), session_key, turn_marker, event=event,
)
async def send_video(
self,
chat_id: str,
video_path: str,
caption: Optional[str] = None,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs,
) -> SendResult:
"""Send a video natively (inline playable). Default: friendly failure notice."""
return await self._send_media_fallback_notice(
"send_video", "video", video_path, chat_id, caption, reply_to, metadata,
)
async def send_document(
self,
chat_id: str,
file_path: str,
caption: Optional[str] = None,
file_name: Optional[str] = None,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs,
) -> SendResult:
"""Send a document/file natively. Default: friendly failure notice."""
return await self._send_media_fallback_notice(
"send_document", "file", file_path, chat_id, caption, reply_to, metadata, file_name=file_name,
)
async def _notify_media_delivery_failure(
self,
chat_id: str,
media_path: str,
*,
is_voice: bool = False,
metadata: Optional[Dict[str, Any]] = None,
) -> None:
"""User-visible notice when a MEDIA attachment upload failed: the tag was
already stripped from the text, so silence would be a silent drop."""
ext = Path(media_path).suffix.lower()
if is_voice or should_send_media_as_audio(self.platform, ext, is_voice=is_voice):
text = _media_failure_text("audio")
elif ext in _VIDEO_EXTS:
text = _media_failure_text("video")
else:
text = _media_failure_text("file", os.path.basename(media_path))
try:
notice = await self.send(chat_id=chat_id, content=text, metadata=metadata)
failed, problem = not notice.success, notice.error
except Exception as notify_err:
failed, problem = True, notify_err
if failed:
logger.debug("[%s] Could not send media-delivery-failure notice: %s", self.name, problem)
async def send_image_file(
self,
chat_id: str,
image_path: str,
caption: Optional[str] = None,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs,
) -> SendResult:
"""Send a local image file natively (send_image takes a URL). Default: friendly notice."""
return await self._send_media_fallback_notice(
"send_image_file", "image", image_path, chat_id, caption, reply_to, metadata,
)
@staticmethod
def validate_media_delivery_path(path: str, session_key: str = "") -> Optional[str]:
"""Return a resolved path if it is safe for native attachment upload."""
return validate_media_delivery_path(path, session_key=session_key)
@staticmethod
def filter_media_delivery_paths(media_files, session_key: str = "") -> List[Tuple[str, bool]]:
"""Drop unsafe MEDIA paths and normalize accepted paths."""
safe_media: List[Tuple[str, bool]] = []
for media_path, is_voice in media_files or []:
safe_path = _validated_delivery_path(media_path, session_key, "MEDIA directive path")
if safe_path:
safe_media.append((safe_path, bool(is_voice)))
return safe_media
@staticmethod
def filter_local_delivery_paths(file_paths, session_key: str = "") -> List[str]:
"""Drop unsafe bare local file paths and normalize accepted paths."""
safe_paths = (_validated_delivery_path(p, session_key, "local file path") for p in file_paths or [])
return [p for p in safe_paths if p]
@staticmethod
def _mask_protected_spans(content: str) -> str:
"""Blank fenced code, inline code and blockquotes (length-preserving, so
regex offsets stay valid) to prevent MEDIA: false positives; backtick-quoted
paths inside MEDIA: tags are left scannable."""
spans: list = [m.span() for m in _FENCED_CODE_RE.finditer(content)]
for m in _INLINE_CODE_RE.finditer(content):
start = m.start()
prefix = content[max(0, start - 20):start]
if re.search(r'MEDIA:\s*$', prefix):
continue # This is a MEDIA path quote, not inline code
# A whole tag in inline code (`MEDIA:/path.csv`) is a real directive —
# models format paths as code — so deliver it IF the path validates;
# prose examples with non-existent paths stay masked, fenced blocks always.
inner = m.group(0)[1:-1].strip()
if inner.upper().startswith("MEDIA:"):
candidate = _normalize_media_tag_path(inner[6:])
if candidate and validate_media_delivery_path(candidate):
continue # Real deliverable tag in inline code — keep it scannable
spans.append((start, m.end()))
for m in re.finditer(r'^>.*$', content, re.MULTILINE):
spans.append((m.start(), m.end()))
return _blank_spans(content, spans)
@staticmethod
def _mask_json_string_media(content: str) -> str:
"""Blank ``MEDIA:<bare-path>`` tags inside JSON string *values* (stored
tool-result text like ``{"result": "MEDIA:/x/stale.png"}``) so they are
never re-delivered. Only spans opened by a value-context quote (``:,{[``
before the ``"``) count, and only bare paths (``/``, ``~/``, ``X:\\``) —
``MEDIA:"..."`` quoted tags and line-start/prose tags are untouched.
Offsets are preserved (blanked with spaces) so match positions stay valid.
"""
if '"' not in content or "MEDIA:" not in content:
return content
# JSON value-context string: a quote preceded by : , { or [ (optional ws),
# capturing the (escape-aware) string body up to the closing quote.
spans = [
m.span(1) for m in re.finditer(r'(?<=[:,{\[])\s*"((?:[^"\\\n]|\\.)*)"', content)
if re.search(r'MEDIA:\s*(?:~/|/|[A-Za-z]:[/\\])', m.group(1))
]
return _blank_spans(content, spans)
@staticmethod
def extract_media(content: str) -> Tuple[List[Tuple[str, bool]], str]:
"""Extract ``MEDIA:<path>`` tags and strip the ``[[audio_as_voice]]`` /
``[[as_document]]`` directives; returns ``([(path, is_voice), ...], cleaned)``.
``[[as_document]]`` (unmodified sendDocument delivery for large images) is
detected by dispatch sites on the original response and only stripped here.
Both directives are message-global: one tag applies to every file.
"""
media = []
# [[audio_as_voice]] is message-global; [[as_document]] is inspected by
# callers on the original ``content`` — both are only stripped here.
has_voice_tag = "[[audio_as_voice]]" in content
cleaned = content.replace("[[audio_as_voice]]", "").replace("[[as_document]]", "")
# Scan a masked copy so example/stored MEDIA paths (code blocks, quotes,
# JSON string values) are never delivered; dedupe on the expanded path
# so a file referenced twice is uploaded once.
scan_content = _mask_media_scan_text(content)
seen_paths: set = set()
def _add(path: str) -> None:
# is_voice only for audio files: flagging an image is_voice would
# push it out of the photo batch into send_document.
if path not in seen_paths:
seen_paths.add(path)
media.append((path, has_voice_tag and os.path.splitext(path)[1].lower() in _AUDIO_EXTS))
for match in MEDIA_TAG_CLEANUP_RE.finditer(scan_content):
path = _normalize_media_tag_path(match.group("path"))
if path:
try:
_add(os.path.expanduser(path))
except (OSError, RuntimeError, ValueError):
continue # crafted ~\x00 path: skip it, keep the rest
for match in MEDIA_EXTENSIONLESS_TAG_RE.finditer(scan_content):
path = _normalize_media_tag_path(match.group("path"))
if not path or not _path_lacks_deliverable_extension(path):
continue
resolved = _match_extensionless_path(scan_content, match)
if resolved is not None:
_add(resolved[0])
# Locate real tag spans on a masked copy of ``cleaned``, then delete exactly
# those spans from the unmasked text so protected spans survive verbatim.
if media:
spans = _real_media_tag_spans(_mask_media_scan_text(cleaned))
if spans:
cleaned = _delete_spans(cleaned, spans)
cleaned = re.sub(r'\n{3,}', '\n\n', cleaned).strip()
return media, cleaned
@staticmethod
def strip_media_directives_for_display(text: str) -> str:
"""Strip MEDIA: directives from streamed/display text.
Known-extension tags are removed unconditionally (same as
``MEDIA_TAG_CLEANUP_RE``). Extension-less tags are removed only when
``validate_media_delivery_path`` accepts the path so undeliverable
paths stay visible for debugging.
"""
if not _has_media_directives(text):
return text
cleaned = re.sub(r'\n{3,}', '\n\n', _strip_media_tag_directives(text))
return cleaned.rstrip()
@staticmethod
def extract_local_files(content: str) -> Tuple[List[str], str]:
"""Detect bare local file paths (absolute, ``~/`` or drive-letter) with
deliverable extensions and return ``(expanded_paths, cleaned_text)``.
Candidates must exist on disk (``os.path.isfile``) so URLs and hallucinated
paths are ignored; paths inside fenced or inline code are skipped so code
samples are never mutilated. Dispatch by type lives in ``gateway/run.py``.
"""
_LOCAL_MEDIA_EXTS = MEDIA_DELIVERY_EXTS
ext_part = '|'.join(e.lstrip('.') for e in _LOCAL_MEDIA_EXTS)
# Lookbehind rejects URL/relative-path matches (https://…/img.png, ./foo.png);
# the alternation anchors Unix absolute, ``~/`` and Windows drive paths.
path_re = re.compile(
r'(?<![/:\w.])(?:~/|/|[A-Za-z]:[/\\])(?:[\w.\-]+[/\\])*[\w.\-]+\.(?:' + ext_part + r')\b',
re.IGNORECASE,
)
code_spans = _code_spans(content)
found: list = [] # (raw_match_text, expanded_path)
for match in path_re.finditer(content):
if any(s <= match.start() < e for s, e in code_spans):
continue
raw = match.group(0)
expanded = os.path.expanduser(raw)
if os.path.isfile(expanded):
found.append((raw, expanded))
else:
# Most common reason a promised file never arrives — log the gap.
logger.info("Skipping bare file path in reply (no file on disk): %s", _log_safe_path(raw))
# Deduplicate by expanded path, preserving discovery order
seen: set = set()
unique: list = []
for raw, expanded in found:
if expanded not in seen:
seen.add(expanded)
unique.append((raw, expanded))
paths = [expanded for _, expanded in unique]
cleaned = content
if unique:
for raw, _exp in unique:
cleaned = cleaned.replace(raw, '')
cleaned = re.sub(r'\n{3,}', '\n\n', cleaned).strip()
return paths, cleaned
async def _keep_typing(
self,
chat_id: str,
interval: float = 2.0,
metadata=None,
stop_event: asyncio.Event | None = None,
) -> None:
"""Refresh the typing indicator every ``interval`` seconds until cancelled.
Platform typing state expires after ~5s. Chats in ``_typing_paused`` are
skipped (approval waits — Slack's setStatus disables the compose box).
Each ``send_typing`` is bounded by a sub-interval timeout so one slow
round-trip cannot let the bubble lapse; the next tick simply fires fresh.
"""
# Must stay below ``interval`` so a slow call is abandoned before the next tick.
_send_typing_timeout = max(0.25, min(1.5, interval - 0.25))
try:
while True:
if stop_event is not None and stop_event.is_set():
return
if chat_id not in self._typing_paused:
try:
await asyncio.wait_for(
self.send_typing(chat_id, metadata=metadata),
timeout=_send_typing_timeout,
)
except asyncio.TimeoutError:
# Slow network — abandon this tick, stay on schedule.
pass
except asyncio.CancelledError:
raise
except Exception as typing_err:
logger.debug("[%s] send_typing error (non-fatal): %s", self.name, typing_err)
if stop_event is None:
await asyncio.sleep(interval)
continue
loop = asyncio.get_running_loop()
deadline = loop.time() + interval
while not stop_event.is_set():
remaining = deadline - loop.time()
if remaining <= 0:
break
# Poll rather than wait_for(stop_event.wait()): cancelling that can
# wedge shutdown on Python 3.11/pytest-asyncio; sleep cancels immediately.
await asyncio.sleep(min(0.25, remaining))
if stop_event.is_set():
return
except asyncio.CancelledError:
pass # Normal cancellation when handler completes
finally:
# A send_typing after an outer stop_typing() may have recreated the
# platform typing loop; cancelling this task alone won't clean it up.
if hasattr(self, "stop_typing"):
try:
await self._stop_typing_with_metadata(chat_id, metadata)
except Exception:
pass
self._typing_paused.discard(chat_id)
# getattr-guard: tests build adapters via object.__new__ without _status_text.
getattr(self, "_status_text", {}).pop(str(chat_id), None)
async def _stop_typing_refresh(
self,
chat_id: str,
typing_task: asyncio.Task | None = None,
*,
metadata=None,
timeout: float = 0.5,
stop_attempts: int = 2,
) -> None:
"""Stop the refresh task and platform typing state as one operation."""
self._typing_paused.add(chat_id)
try:
if typing_task is not None and not typing_task.done():
typing_task.cancel()
try:
await asyncio.wait_for(asyncio.shield(typing_task), timeout=timeout)
except (asyncio.CancelledError, asyncio.TimeoutError):
# Task is cancelled; don't let slow adapter cleanup block delivery/shutdown.
pass
if not hasattr(self, "stop_typing"):
return
attempts = max(1, stop_attempts)
for attempt in range(attempts):
try:
await self._stop_typing_with_metadata(chat_id, metadata)
except Exception:
pass
if attempt < attempts - 1:
await asyncio.sleep(0)
finally:
self._typing_paused.discard(chat_id)
def pause_typing_for_chat(self, chat_id: str) -> None:
"""Pause typing for a chat (approval waits). Thread-safe under the GIL:
callable from the sync agent thread while ``_keep_typing`` runs."""
self._typing_paused.add(chat_id)
def resume_typing_for_chat(self, chat_id: str) -> None:
"""Resume typing indicator for a chat after approval resolves."""
self._typing_paused.discard(chat_id)
async def interrupt_session_activity(self, session_key: str, chat_id: str, metadata=None) -> None:
"""Signal the active session loop to stop and clear typing immediately."""
if session_key:
interrupt_event = self._active_sessions.get(session_key)
if interrupt_event is not None:
interrupt_event.set()
try:
await self._stop_typing_with_metadata(chat_id, metadata)
except Exception:
pass
def register_post_delivery_callback(
self,
session_key: str,
callback: Callable,
*,
generation: int | None = None,
) -> None:
"""Register a deferred callback to fire after the main response.
Same-key registrations are chained (both fire, in order, with per-callback
exception isolation) so independent features coexist. ``generation`` ties
the callback to a gateway run; stale generations never overwrite a fresher slot.
"""
if not session_key or not callable(callback):
return
existing = self._post_delivery_callbacks.get(session_key)
if existing is not None:
existing_gen, existing_cb = _split_post_delivery_entry(existing)
# Stale-generation registrations never overwrite a fresher slot.
if existing_gen is not None and generation is not None and int(generation) < int(existing_gen):
return
# Same-or-newer generation: chain so both fire in registration order.
if callable(existing_cb) and (
existing_gen is None or generation is None or int(existing_gen) == int(generation)
):
_prev = existing_cb
_new = callback
async def _chained() -> None:
# Must be async: the invoker awaits awaitable callbacks, and a sync
# wrapper would silently drop coroutines returned by async hooks.
for _cb in (_prev, _new):
try:
_result = _cb()
if inspect.isawaitable(_result):
await _result
except Exception:
logger.debug("Post-delivery callback failed", exc_info=True)
callback = _chained
if generation is None:
self._post_delivery_callbacks[session_key] = callback
else:
self._post_delivery_callbacks[session_key] = (int(generation), callback)
def pop_post_delivery_callback(
self,
session_key: str,
*,
generation: int | None = None,
) -> Callable | None:
"""Pop a deferred callback, optionally requiring generation ownership."""
if not session_key:
return None
entry = self._post_delivery_callbacks.get(session_key)
if entry is None:
return None
entry_generation, callback = _split_post_delivery_entry(entry)
if generation is not None and (entry_generation is None or int(entry_generation) != int(generation)):
return None
self._post_delivery_callbacks.pop(session_key, None)
return callback if callable(callback) else None
# ── Processing lifecycle hooks ──────────────────────────────────────────
# Subclasses override these to react to processing events (e.g. Discord
# 👀/✅/❌ reactions). Adapters exposing ``_add_reaction(chat_id, message_id,
# emoji)`` / ``_remove_reaction(chat_id, message_id)`` can instead set the
# emoji attributes below; left ``None`` the hook stays a no-op.
_ACK_EMOJI: Optional[str] = None
_OK_EMOJI: Optional[str] = None
_FAIL_EMOJI: Optional[str] = None
async def on_processing_start(self, event: MessageEvent) -> None:
"""Hook called when background processing begins."""
async def on_processing_complete(self, event: MessageEvent, outcome: ProcessingOutcome) -> None:
"""Hook called when background processing completes.
Default: opt-in reaction ack — when ``_OK_EMOJI``/``_FAIL_EMOJI`` are set
and ``_add_reaction``/``_remove_reaction`` exist, swap the in-progress
reaction for the outcome one. Remove-then-add is deterministic whether the
platform replaces or stacks a sender's reactions. CANCELLED leaves it unreacted.
"""
if self._OK_EMOJI is None and self._FAIL_EMOJI is None:
return
add: Any = getattr(self, "_add_reaction", None)
remove: Any = getattr(self, "_remove_reaction", None)
if not callable(add) or not callable(remove):
return
enabled = getattr(self, "_reactions_enabled", None)
if callable(enabled) and not enabled():
return
chat_id = getattr(event.source, "chat_id", None)
message_id = getattr(event, "message_id", None)
if not chat_id or not message_id:
return
await remove(chat_id, message_id)
if outcome == ProcessingOutcome.SUCCESS:
if self._OK_EMOJI:
await add(chat_id, message_id, self._OK_EMOJI)
elif outcome == ProcessingOutcome.FAILURE and self._FAIL_EMOJI:
await add(chat_id, message_id, self._FAIL_EMOJI)
# CANCELLED: leave the message unreacted.
async def _run_processing_hook(self, hook_name: str, *args: Any, **kwargs: Any) -> None:
"""Run a lifecycle hook without letting failures break message flow."""
hook = getattr(self, hook_name, None)
if not callable(hook):
return
try:
await hook(*args, **kwargs)
except Exception as e:
logger.warning("[%s] %s hook failed: %s", self.name, hook_name, e)
@staticmethod
def _is_retryable_error(error: Optional[str]) -> bool:
"""Return True if the error string looks like a transient network failure."""
if not error:
return False
lowered = error.lower()
return any(pat in lowered for pat in _RETRYABLE_ERROR_PATTERNS)
@staticmethod
def _is_timeout_error(error: Optional[str]) -> bool:
"""Return True for read/write timeouts — NOT retryable and NOT a plain-text
fallback trigger, because the request may already have been delivered."""
if not error:
return False
lowered = error.lower()
return "timed out" in lowered or "readtimeout" in lowered or "writetimeout" in lowered
def _unwrap_ephemeral(self, response: Any) -> Tuple[Optional[str], int]:
"""Unwrap a str/None/:class:`EphemeralReply` response into ``(text, ttl)``.
``ttl > 0`` means the caller should schedule ``_schedule_ephemeral_delete``
after a successful send; it is forced to 0 when the adapter doesn't override
``delete_message`` so non-supporting platforms degrade to normal sends.
"""
if isinstance(response, EphemeralReply):
ttl = response.ttl_seconds
if ttl is None:
try:
ttl = int(self._get_ephemeral_system_ttl_default())
except Exception:
ttl = 0
if ttl and ttl > 0 and type(self).delete_message is BasePlatformAdapter.delete_message:
ttl = 0
return response.text, int(ttl or 0)
return response, 0
async def _dispatch_inline_reply(self, event: MessageEvent, *, log_cmd: Optional[str] = None) -> None:
"""Call the handler and send its reply inline, with retry, threading and
ephemeral deletion — no session lifecycle (active-session bypass paths)."""
thread_meta = _thread_metadata_for_source(event.source, _reply_anchor_for_event(event))
response = await self._message_handler(event)
text, eph_ttl = self._unwrap_ephemeral(response)
if not text:
return
if log_cmd is not None:
logger.info(
"[%s] Sending command '/%s' response (%d chars) to %s",
self.name, log_cmd, len(text), event.source.chat_id,
)
result = await self._send_with_retry(
chat_id=event.source.chat_id,
content=text,
reply_to=_reply_anchor_for_event(event),
metadata=_mark_notify_metadata(thread_meta),
)
if eph_ttl > 0 and result.success and result.message_id:
self._schedule_ephemeral_delete(
chat_id=event.source.chat_id, message_id=result.message_id, ttl_seconds=eph_ttl,
)
def _final_delivery_adapter(self, source: Optional[SessionSource]) -> "BasePlatformAdapter":
"""Return the runner's current adapter for a new final-response send.
A reconnect can swap the registry adapter while this task is in flight; an
unsent final response belongs on the replacement transport, but message IDs,
edits and deletes stay owned by the old one (nothing is migrated).
"""
runner = getattr(self, "gateway_runner", None)
resolve = getattr(runner, "_adapter_for_source", None)
if not callable(resolve):
return self
try:
live_adapter = resolve(source)
except Exception:
logger.debug("[%s] Failed to resolve live adapter for final delivery", self.name)
return self
if not isinstance(live_adapter, BasePlatformAdapter) or live_adapter.platform != self.platform:
return self
return live_adapter
async def _send_with_retry(
self,
chat_id: str,
content: str,
reply_to: Optional[str] = None,
metadata: Any = None,
max_retries: int = 2,
base_delay: float = 2.0,
) -> "SendResult":
"""Send with exponential-backoff retry on transient network errors.
Permanent failures (formatting/permission) fall back to a plain-text send;
exhausted network retries send the user a brief delivery-failure notice.
"""
async def _send(text: str) -> "SendResult":
return await self.send(chat_id=chat_id, content=text, reply_to=reply_to, metadata=metadata)
result = await _send(content)
if result.success:
return result
error_str = result.error or ""
is_network = result.retryable or self._is_retryable_error(error_str)
# Timeouts: not safe to retry (may have delivered) and not a formatting error.
if not is_network and self._is_timeout_error(error_str):
return result
if is_network:
# Exponential backoff; a server-requested retry_after (e.g. Telegram
# FloodWait) is authoritative over our schedule.
server_retry_after = result.retry_after
for attempt in range(1, max_retries + 1):
if server_retry_after is not None:
delay = server_retry_after + random.uniform(0, 1)
server_retry_after = None # only honor once per send
else:
delay = base_delay * (2 ** (attempt - 1)) + random.uniform(0, 1)
logger.warning(
"[%s] Send failed (attempt %d/%d, retrying in %.1fs): %s",
self.name, attempt, max_retries, delay, error_str,
)
await asyncio.sleep(delay)
result = await _send(content)
if result.success:
logger.info("[%s] Send succeeded on retry %d", self.name, attempt)
return result
error_str = result.error or ""
if result.retry_after is not None:
server_retry_after = result.retry_after
if not (result.retryable or self._is_retryable_error(error_str)):
break # error switched to non-transient — fall through to plain-text fallback
else:
# All retries exhausted (loop completed without break) — notify user
logger.error("[%s] Failed to deliver response after %d retries: %s", self.name, max_retries, error_str)
notice = (
"\u26a0\ufe0f Message delivery failed after multiple attempts. "
"Please try again \u2014 your request was processed but the response could not be sent."
)
try:
await _send(notice)
except Exception as notify_err:
logger.debug("[%s] Could not send delivery-failure notice: %s", self.name, notify_err)
return result
# Non-network / post-retry formatting failure: try plain text as fallback
logger.warning("[%s] Send failed: %s — trying plain-text fallback", self.name, error_str)
fallback_result = await _send(f"(Response formatting failed, plain text:)\n\n{content[:3500]}")
if not fallback_result.success:
logger.error("[%s] Fallback send also failed: %s", self.name, fallback_result.error)
return fallback_result
@staticmethod
def _merge_caption(existing_text: Optional[str], new_text: str) -> str:
"""Merge a new caption into existing text unless an identical (whitespace-
normalised) caption already exists — exact match per caption, not
substring, so "Meeting" is not swallowed by "Meeting agenda"."""
if not existing_text:
return new_text
existing_captions = [c.strip() for c in existing_text.split("\n\n")]
if new_text.strip() not in existing_captions:
return f"{existing_text}\n\n{new_text}".strip()
return existing_text
def _text_debounce_store(self) -> dict[str, TextDebounceState]:
return _lazy_attr(self, "_text_debounce", dict)
def _is_queue_text_debounce_candidate(self, event: MessageEvent) -> bool:
"""Return True for normal text eligible for queue-mode debounce."""
result = (
getattr(self, "_busy_text_mode", "interrupt") == "queue"
and event.message_type == MessageType.TEXT
and not getattr(event, "internal", False)
and not event.is_command()
and bool((event.text or "").strip())
)
if result:
logger.debug(
"[%s] Queue-text debounce candidate accepted: session=%s text_len=%d",
self.name,
getattr(event, "session_key", "?"),
len(event.text or ""),
)
return result
def _can_merge_text_debounce_events(self, existing: MessageEvent, event: MessageEvent) -> bool:
"""Return True when two text debounce events came from the same sender."""
def _identity(candidate: MessageEvent) -> tuple[str, ...] | None:
source = getattr(candidate, "source", None)
if source is None:
return None
platform = _platform_name(getattr(source, "platform", None))
sender = getattr(source, "user_id_alt", None) or getattr(source, "user_id", None)
if sender:
return (platform, str(sender))
if getattr(source, "chat_type", None) in {"dm", "private"} and getattr(source, "chat_id", None):
return (platform, "dm", str(source.chat_id))
return None
existing_sender = _identity(existing)
incoming_sender = _identity(event)
return existing_sender is not None and existing_sender == incoming_sender
def _text_debounce_delay(self, session_key: str) -> float:
"""Return bounded busy-text debounce delay for ``session_key``."""
state = self._text_debounce_store().get(session_key)
if state is None:
return 0.0
now = time.monotonic()
window_deadline = state.last_ts + self._busy_text_debounce_seconds
hard_cap_deadline = state.first_ts + self._busy_text_hard_cap_seconds
return max(0.0, min(window_deadline, hard_cap_deadline) - now)
async def _queue_text_debounce(self, session_key: str, event: MessageEvent) -> None:
"""Buffer normal queue-mode busy text and schedule a bounded flush."""
store = self._text_debounce_store()
state = store.get(session_key)
if state is not None and not self._can_merge_text_debounce_events(state.event, event):
# Preserve sender attribution in shared sessions: flush the current
# buffer as the next pending turn; the new sender starts a fresh burst.
await self._flush_text_debounce_now(session_key)
state = store.get(session_key)
if state is not None and not self._can_merge_text_debounce_events(state.event, event):
existing_pending = self._pending_messages.get(session_key)
if existing_pending is not None and self._can_merge_text_debounce_events(existing_pending, event):
merge_pending_message_event(self._pending_messages, session_key, event, merge_text=True)
return
now = time.monotonic()
if state is None:
state = TextDebounceState(event=event, task=None, first_ts=now, last_ts=now)
store[session_key] = state
else:
if event.text:
state.event.text = _append_text(state.event.text, event.text)
latest_message_id = getattr(event, "message_id", None)
latest_anchor = latest_message_id or getattr(event, "reply_to_message_id", None)
if latest_message_id is not None:
state.event.message_id = str(latest_message_id)
if latest_anchor is not None and hasattr(state.event, "reply_to_message_id"):
state.event.reply_to_message_id = str(latest_anchor)
state.last_ts = now
state.cancel_timer()
delay = self._text_debounce_delay(session_key)
state.task = asyncio.create_task(self._flush_text_debounce(session_key, delay))
async def _flush_text_debounce(self, session_key: str, delay: float) -> None:
"""Timer task that flushes the debounced text buffer."""
try:
await asyncio.sleep(delay)
await self._flush_text_debounce_now(session_key)
except asyncio.CancelledError:
return
finally:
current = asyncio.current_task()
state = self._text_debounce_store().get(session_key)
if state is not None and state.task is current:
state.task = None
async def _flush_text_debounce_now(self, session_key: str) -> bool:
"""Force-flush one debounced busy-text burst into the pending slot."""
store = self._text_debounce_store()
state = store.get(session_key)
if state is None:
return False
state.cancel_timer(unless=asyncio.current_task())
state.task = None
existing_pending = self._pending_messages.get(session_key)
if (
existing_pending is not None
and not self._can_merge_text_debounce_events(existing_pending, state.event)
):
return False
state = store.pop(session_key, None)
if state is None:
return False
merge_pending_message_event(self._pending_messages, session_key, state.event, merge_text=True)
return True
def _discard_text_debounce(self, session_key: str) -> None:
"""Cancel and drop pending text debounce state for control commands."""
state = self._text_debounce_store().pop(session_key, None)
if state is not None:
state.cancel_timer()
# ------------------------------------------------------------------
# Session task + guard ownership helpers
# ------------------------------------------------------------------
# Paired with the _session_tasks owner map so lifecycle reconciliation is
# deterministic across normal completion, /stop /new /reset bypass
# commands, and stale-lock self-heal on the next inbound message.
def _release_session_guard(self, session_key: str, *, guard: Optional[asyncio.Event] = None) -> None:
"""Release the session guard; with ``guard`` given, only if the entry is
still that exact Event (so an old task's unwind can't clear the temporary
guard a reset-like command swapped in)."""
current_guard = self._active_sessions.get(session_key)
if current_guard is None:
return
if guard is not None and current_guard is not guard:
return
del self._active_sessions[session_key]
def _session_task_is_stale(self, session_key: str) -> bool:
"""Return True if the recorded owner task for ``session_key`` has exited.
No owner task at all is NOT stale: guards installed outside handle_message
(tests do this) must not be healed. Only the production split-brain — owner
recorded, then exited without clearing its guard — counts.
"""
task = self._session_tasks.get(session_key)
if task is None:
return False
done = getattr(task, "done", None)
return bool(done and done())
def _heal_stale_session_lock(self, session_key: str) -> bool:
"""Clear a stale session lock; True if healed, False if no lock or the
owner task is still alive (normal busy case).
On-entry safety net: without it a split-brain (adapter thinks the session
is active, nothing is processing) traps the chat in "Interrupting current
task..." until the gateway restarts.
"""
if session_key not in self._active_sessions:
return False
if not self._session_task_is_stale(session_key):
return False
logger.warning(
"[%s] Healing stale session lock for %s (owner task is done/absent)",
self.name,
session_key,
)
self._active_sessions.pop(session_key, None)
self._pending_messages.pop(session_key, None)
self._session_tasks.pop(session_key, None)
self._discard_text_debounce(session_key)
return True
def _start_session_processing(
self,
event: MessageEvent,
session_key: str,
*,
interrupt_event: Optional[asyncio.Event] = None,
) -> bool:
"""Spawn a background processing task under the session guard; True on
success. If ``create_task`` is stubbed with a non-Task sentinel (tests),
the guard is rolled back and False returned — no half-installed lock."""
guard = interrupt_event or asyncio.Event()
self._active_sessions[session_key] = guard
task = asyncio.create_task(self._process_message_background(event, session_key))
self._session_tasks[session_key] = task
try:
self._background_tasks.add(task)
except TypeError:
# Tests stub create_task() with unhashable sentinels lacking lifecycle callbacks.
self._session_tasks.pop(session_key, None)
self._release_session_guard(session_key, guard=guard)
return False
if hasattr(task, "add_done_callback"):
task.add_done_callback(self._background_tasks.discard)
task.add_done_callback(self._expected_cancelled_tasks.discard)
return True
async def cancel_session_processing(
self,
session_key: str,
*,
release_guard: bool = True,
discard_pending: bool = True,
) -> None:
"""Cancel in-flight processing for a single session.
``release_guard=False`` keeps the guard installed so reset-like commands
finish atomically before follow-ups can start a fresh task. The await is
bounded (5s) so a wedged finally block (typing cleanup, completion hook)
can't stall the calling dispatch coroutine.
"""
task = self._session_tasks.pop(session_key, None)
if task is not None and not task.done():
logger.debug("[%s] Cancelling active processing for session %s", self.name, session_key)
self._expected_cancelled_tasks.add(task)
task.cancel()
try:
await asyncio.wait_for(asyncio.shield(task), timeout=5.0)
except asyncio.CancelledError:
pass
except asyncio.TimeoutError:
logger.warning(
"[%s] Cancelled task for %s did not exit within 5s; "
"unblocking dispatch and letting the task unwind in the background",
self.name, session_key,
)
except Exception:
logger.debug(
"[%s] Session cancellation raised while unwinding %s",
self.name,
session_key,
exc_info=True,
)
if discard_pending:
self._pending_messages.pop(session_key, None)
self._discard_text_debounce(session_key)
if release_guard:
self._release_session_guard(session_key)
async def _drain_pending_after_session_command(
self,
session_key: str,
command_guard: asyncio.Event,
) -> None:
"""Tail of /stop, /new, /reset: release the command-scoped guard, then
spawn a fresh processing task for any follow-up queued meanwhile."""
await self._flush_text_debounce_now(session_key)
pending_event = self._pending_messages.pop(session_key, None)
self._release_session_guard(session_key, guard=command_guard)
if pending_event is None:
return
self._start_session_processing(pending_event, session_key)
async def _dispatch_active_session_command(self, event: MessageEvent, session_key: str, cmd: str) -> None:
"""Dispatch a reset-like bypass command (/stop, /new, /reset) in order:
keep the guard installed while the runner handles it (racing follow-ups
stay queued), cancel the old task only AFTER the runner's response is
sent, then release the command guard and drain the queued follow-up once.
"""
logger.debug("[%s] Command '/%s' bypassing active-session guard for %s", self.name, cmd, session_key)
current_guard = self._active_sessions.get(session_key)
command_guard = asyncio.Event()
self._active_sessions[session_key] = command_guard
try:
# Send BEFORE cancelling the old task so cancellation side effects
# can't drop the "/new" confirmation.
await self._dispatch_inline_reply(event, log_cmd=cmd)
# Cancel the old adapter task AFTER the response is sent — deterministic ordering.
await self.cancel_session_processing(session_key, release_guard=False, discard_pending=False)
except Exception:
# On failure restore the original guard so the session isn't left half-reset.
if self._active_sessions.get(session_key) is command_guard:
if session_key in self._session_tasks and current_guard is not None:
self._active_sessions[session_key] = current_guard
else:
self._release_session_guard(session_key, guard=command_guard)
raise
await self._drain_pending_after_session_command(session_key, command_guard)
async def handle_message(self, event: MessageEvent) -> None:
"""Process an incoming message; returns quickly by spawning a background
task so new messages (and interrupts) can arrive while an agent runs."""
if not self._message_handler:
return
if event.allow_gateway_control:
coerce_plaintext_gateway_command(event)
# Telegram topic recovery is DM-only; skipping the executor hop for
# group/forum traffic keeps a busy default pool from delaying dispatch.
needs_topic_recovery = (
getattr(self, "_topic_recovery_fn", None) is not None
and event.source.platform == Platform.TELEGRAM
and event.source.chat_type == "dm"
)
if needs_topic_recovery:
await asyncio.to_thread(self._apply_topic_recovery, event)
session_key = self._event_session_key(event)
expected_session_key = str((event.metadata or {}).get("gateway_session_key") or "").strip()
if expected_session_key and session_key != expected_session_key:
logger.warning(
"Dropping internally routed event: expected session=%s derived=%s",
expected_session_key,
session_key,
)
return
# On-entry self-heal: an _active_sessions entry whose owner task already
# exited is stale — clear it so the user isn't trapped behind a dead guard.
if session_key in self._active_sessions:
self._heal_stale_session_lock(session_key)
if session_key in self._active_sessions:
await self._handle_message_while_active(event, session_key)
return
# Install the guard synchronously BEFORE spawning the task (grammY
# sequentialize pattern) so a second message can't race in and spawn a
# duplicate; _start_session_processing also records the owner task atomically.
self._start_session_processing(event, session_key)
async def _handle_message_while_active(self, event: MessageEvent, session_key: str) -> None:
"""Route a message that arrived while ``session_key`` is busy: bypass
commands / clarify replies dispatch inline, everything else is queued."""
# Some commands must bypass the guard: queued they would leak into the
# conversation as user text (/stop, /new) or deadlock (/approve, /deny).
# Dispatch inline — _process_message_background's cleanup races the running task.
cmd = event.get_command()
from hermes_cli.commands import (is_interrupt_then_dispatch, should_bypass_active_session)
if should_bypass_active_session(cmd):
try:
# /stop, /new, /reset (busy_policy == "interrupt_then_dispatch") take the
# handoff path that serializes cancel + runner response + pending drain.
if cmd and is_interrupt_then_dispatch(cmd):
self._discard_text_debounce(session_key)
await self._dispatch_active_session_command(event, session_key, cmd)
else:
# Other bypass commands (/approve, /deny, /status, /bg, /restart)
# dispatch directly without cancelling the running task.
logger.debug(
"[%s] Command '/%s' bypassing active-session guard for %s",
self.name, cmd, session_key,
)
await self._dispatch_inline_reply(event)
except Exception as e:
logger.error("[%s] Command '/%s' dispatch failed: %s", self.name, cmd, e, exc_info=True)
return
# Clarify bypass: while the agent is blocked on clarify_tool, the next
# non-command message must reach the runner's text-intercept, not the queue.
if not cmd and event.allow_gateway_control:
try:
from tools import clarify_gateway as _clarify_mod
_has_text_clarify = (
_clarify_mod.get_pending_for_session(session_key, include_choice_prompts=True) is not None
)
except Exception:
_has_text_clarify = False
if _has_text_clarify:
logger.debug("[%s] Routing message to clarify text-intercept for %s", self.name, session_key)
try:
await self._dispatch_inline_reply(event)
except Exception as e:
logger.error("[%s] Clarify text-intercept dispatch failed: %s", self.name, e, exc_info=True)
return
if self._busy_session_handler is not None:
try:
if await self._busy_session_handler(event, session_key):
return
except Exception as e:
logger.error("[%s] Busy-session handler failed: %s", self.name, e, exc_info=True)
# Photo bursts/albums arrive as near-simultaneous messages: queue them
# without interrupting; they run right after the current task.
if event.message_type == MessageType.PHOTO:
logger.debug("[%s] Queuing photo follow-up for session %s without interrupt", self.name, session_key)
merge_pending_message_event(self._pending_messages, session_key, event)
return
if self._is_queue_text_debounce_candidate(event):
logger.debug(
"[%s] New text message while session %s is active — "
"debouncing follow-up (busy_text_mode=queue, window=%.2fs)",
self.name,
session_key,
self._busy_text_debounce_seconds,
)
await self._queue_text_debounce(session_key, event)
else:
logger.debug(
"[%s] New message while session %s is active — queuing follow-up "
"(no interrupt, will cascade after current turn)",
self.name,
session_key,
)
merge_pending_message_event(
self._pending_messages,
session_key,
event,
merge_text=event.message_type == MessageType.TEXT,
)
@staticmethod
def _get_human_delay() -> float:
"""Random human-like pacing delay in seconds, from HERMES_HUMAN_DELAY_MODE
("off" default | "natural" 800-2500ms | "custom" via
HERMES_HUMAN_DELAY_MIN_MS / HERMES_HUMAN_DELAY_MAX_MS)."""
mode = os.getenv("HERMES_HUMAN_DELAY_MODE", "off").lower()
if mode == "off":
return 0.0
if mode == "natural":
min_ms, max_ms = 800, 2500
return random.uniform(min_ms / 1000.0, max_ms / 1000.0)
# custom mode — tolerate malformed env vars instead of crashing.
def _ms(name: str, default: int) -> int:
try:
return int(os.getenv(name, str(default)))
except (TypeError, ValueError):
return default
min_ms = _ms("HERMES_HUMAN_DELAY_MIN_MS", 800)
max_ms = _ms("HERMES_HUMAN_DELAY_MAX_MS", 2500)
return random.uniform(min_ms / 1000.0, max_ms / 1000.0)
async def _synthesize_auto_tts(self, text_content: str) -> Tuple[List[str], Optional[str]]:
"""Synthesize auto-TTS audio; returns ``(existing_paths, requested_path)``,
empty/None on failure (logged, never raised). The output path is built
platform-aware here because HERMES_SESSION_PLATFORM is already cleared
by the time this post-handler code runs."""
paths: List[str] = []
requested_path = None
try:
from tools.tts_tool import text_to_speech_tool, check_tts_requirements
if check_tts_requirements():
import json as _json
speech_text = self.prepare_tts_text(text_content)
if not speech_text:
raise ValueError("Empty text after markdown cleanup")
requested_path = build_auto_tts_output_path(self.platform)
tts_result_str = await asyncio.to_thread(
text_to_speech_tool, text=speech_text, output_path=requested_path,
)
tts_data = _json.loads(tts_result_str)
if tts_data.get("success", True):
raw_tts_paths = tts_data.get("file_paths") or [tts_data.get("file_path")]
paths = [str(path) for path in raw_tts_paths if path and Path(path).exists()]
except Exception as tts_err:
logger.warning("[%s] Auto-TTS failed: %s", self.name, tts_err)
return paths, requested_path
async def _record_delivery_obligation(
self, event: MessageEvent, session_key: str, text_content: str,
delivery_adapter: "BasePlatformAdapter", is_ephemeral_response: bool,
) -> Optional[str]:
"""Durably record the final response BEFORE the send so a crash between
finalize and platform ACK redelivers on next boot. Best-effort (ledger
trouble never blocks the send); slash-command and ephemeral replies are
not recorded. Returns the obligation id or None."""
if is_ephemeral_response or str(event.text or "").lstrip().startswith(
("/", self.typed_command_prefix or "!")
):
return None
try:
from gateway.delivery_ledger import (
compute_obligation_id,
ledger_enabled,
mark_attempting,
record_obligation,
)
if not await asyncio.to_thread(ledger_enabled):
return None
obligation_id = compute_obligation_id(
session_key, str(getattr(event, "message_id", "") or ""), text_content,
)
await asyncio.to_thread(
record_obligation,
obligation_id=obligation_id,
session_key=session_key,
platform=str(getattr(event.source.platform, "value", event.source.platform)),
chat_id=event.source.chat_id,
thread_id=getattr(event.source, "thread_id", None),
content=text_content,
adapter_profile=getattr(delivery_adapter, "_owner_profile", None),
)
await asyncio.to_thread(mark_attempting, obligation_id)
return obligation_id
except Exception:
logger.debug("delivery ledger record failed", exc_info=True)
return None
async def _finalize_delivery_obligation(
self, obligation_id: str, result: Any, event: MessageEvent,
delivery_adapter: "BasePlatformAdapter",
) -> None:
"""Mark the ledger row delivered/failed (best-effort). On
``send_path_degraded`` with a replacement adapter already live, signal a
second redelivery sweep — the watcher's sweep may have run before this
failure was recorded; atomic claiming keeps concurrent signals idempotent."""
try:
from gateway.delivery_ledger import mark_delivered, mark_failed
if getattr(result, "success", False):
await asyncio.to_thread(mark_delivered, obligation_id)
return
_delivery_error = str(getattr(result, "error", "") or "")
await asyncio.to_thread(mark_failed, obligation_id, _delivery_error)
if _delivery_error == "send_path_degraded":
_live_adapter = self._final_delivery_adapter(event.source)
_runtime_redeliver = getattr(
getattr(self, "gateway_runner", None),
"_redeliver_failed_obligations_for_platform",
None,
)
if _live_adapter is not delivery_adapter and callable(_runtime_redeliver):
await _runtime_redeliver(
event.source.platform,
profile=getattr(delivery_adapter, "_owner_profile", None),
)
except Exception:
logger.debug("delivery ledger update failed", exc_info=True)
async def _deliver_media_attachments(
self, event: MessageEvent, media_files: list, local_files: list, *,
force_document_attachments: bool, human_delay: float, metadata: Dict[str, Any],
) -> None:
"""Deliver MEDIA-tag files and auto-detected local files by type.
Images are batched via ``send_multiple_images`` unless ``[[as_document]]``
forced document delivery; other MEDIA files route audio → send_voice,
video → send_video, else send_document (local files never go to
send_voice). Every failure is reported to the user.
"""
from urllib.parse import quote as _quote
_image_paths: list = []
_non_image_media: list = []
for media_path, is_voice in media_files:
_ext = Path(media_path).suffix.lower()
if _ext in _IMAGE_EXTS and not is_voice and not force_document_attachments:
_image_paths.append(media_path)
else:
_non_image_media.append((media_path, is_voice))
_non_image_local: list = []
for file_path in local_files:
if Path(file_path).suffix.lower() in _IMAGE_EXTS and not force_document_attachments:
_image_paths.append(file_path)
else:
_non_image_local.append(file_path)
if _image_paths:
try:
_batch = [(f"file://{_quote(p)}", "") for p in _image_paths]
await self.send_multiple_images(
chat_id=event.source.chat_id, images=_batch, metadata=metadata, human_delay=human_delay,
)
except Exception as batch_err:
logger.warning("[%s] Error batching images: %s", self.name, batch_err, exc_info=True)
chat_id = event.source.chat_id
async def _send_one(path: str, *, is_voice: bool, media_tag: bool) -> None:
"""MEDIA-tag files (``media_tag``) may route to send_voice; bare local files never do."""
ext = Path(path).suffix.lower()
if media_tag and should_send_media_as_audio(self.platform, ext, is_voice=is_voice):
result = await self.send_voice(chat_id=chat_id, audio_path=path, metadata=metadata, is_voice=is_voice)
elif ext in _VIDEO_EXTS:
if media_tag:
logger.info("[%s] Sending video attachment (%s) to %s", self.name, ext, chat_id)
result = await self.send_video(chat_id=chat_id, video_path=path, metadata=metadata)
else:
result = await self.send_document(chat_id=chat_id, file_path=path, metadata=metadata)
if not result.success:
label = "media" if media_tag else "local file"
logger.warning("[%s] Failed to send %s (%s): %s", self.name, label, ext, result.error)
await self._notify_media_delivery_failure(chat_id, path, is_voice=is_voice, metadata=metadata)
if _non_image_media:
logger.info("[%s] Delivering %d non-image MEDIA attachment(s)", self.name, len(_non_image_media))
for media_path, is_voice in _non_image_media:
if human_delay > 0:
await asyncio.sleep(human_delay)
try:
await _send_one(media_path, is_voice=is_voice, media_tag=True)
except Exception as media_err:
logger.warning("[%s] Error sending media: %s", self.name, media_err)
for file_path in _non_image_local:
if human_delay > 0:
await asyncio.sleep(human_delay)
try:
await _send_one(file_path, is_voice=False, media_tag=False)
except Exception as file_err:
logger.error("[%s] Error sending local file %s: %s", self.name, file_path, file_err)
async def _send_final_text(
self, event: MessageEvent, session_key: str, text_content: str, metadata: Dict[str, Any],
is_ephemeral_response: bool, ephemeral_ttl: int, record_delivery: Callable,
) -> None:
"""Send the final text reply on the CURRENT transport (a reconnect may have
replaced this adapter mid-handler), bracketed by the delivery ledger; the
adapter that owns the new message id also owns its ephemeral auto-delete."""
delivery_adapter = self._final_delivery_adapter(event.source)
logger.info(
"[%s] Sending response (%d chars) to %s",
delivery_adapter.name,
len(text_content),
event.source.chat_id,
)
_reply_anchor = _reply_anchor_for_event(event)
_obligation_id = await self._record_delivery_obligation(
event, session_key, text_content, delivery_adapter, is_ephemeral_response,
)
result = await delivery_adapter._send_with_retry(
chat_id=event.source.chat_id,
content=text_content,
reply_to=_reply_anchor,
metadata=metadata,
)
record_delivery(result)
if _obligation_id is not None:
await self._finalize_delivery_obligation(_obligation_id, result, event, delivery_adapter)
if ephemeral_ttl and ephemeral_ttl > 0 and result.success and result.message_id:
delivery_adapter._schedule_ephemeral_delete(
chat_id=event.source.chat_id,
message_id=result.message_id,
ttl_seconds=ephemeral_ttl,
)
async def _notify_turn_error(self, event: MessageEvent, e: BaseException) -> Optional[dict]:
"""Tell the user a turn failed rather than leaving radio silence (last resort:
a failing notice is logged, never raised). Returns the thread metadata used."""
_thread_metadata = None
try:
error_type = type(e).__name__
error_detail = str(e)[:300] if str(e) else "no details available"
_thread_metadata = _thread_metadata_for_source(event.source, _reply_anchor_for_event(event))
await self.send(
chat_id=event.source.chat_id,
content=(
f"Sorry, I encountered an error ({error_type}).\n"
f"{error_detail}\n"
"Try again or use /reset to start a fresh session."
),
metadata=_thread_metadata,
)
except Exception as notify_err:
logger.error(
"[%s] Failed to send error notification to user: %s",
self.name, notify_err, exc_info=True,
)
return _thread_metadata
async def _deliver_attachments(
self, event: MessageEvent, extracted: "_ExtractedResponse", metadata: Dict[str, Any], *,
anything_sent: bool,
) -> None:
"""Send extracted image URLs, MEDIA files and bare local files (human-paced),
then fail loudly if a non-empty response produced nothing deliverable."""
human_delay = self._get_human_delay()
images, media_files, local_files = extracted.images, extracted.media_files, extracted.local_files
if images:
logger.info("[%s] Extracted %d image(s) to send as attachments", self.name, len(images))
try:
await self.send_multiple_images(
chat_id=event.source.chat_id, images=images, metadata=metadata, human_delay=human_delay,
)
except Exception as batch_err:
logger.warning("[%s] Error batching images: %s", self.name, batch_err, exc_info=True)
await self._deliver_media_attachments(
event, media_files, local_files,
force_document_attachments=extracted.force_document_attachments,
human_delay=human_delay, metadata=metadata,
)
if not (anything_sent or images or local_files or media_files) and extracted.pre_extract.strip():
logger.error(
"[%s] response_delivery_dropped: non-empty response "
"(%d chars) produced no delivered message or attachment "
"for %s (empty after extract, recovery yielded nothing).",
self.name, len(extracted.pre_extract), event.source.chat_id,
)
def _start_typing_refresh(
self, event: MessageEvent, interrupt_event: asyncio.Event, metadata: Optional[dict],
) -> Optional[asyncio.Task]:
"""Spawn the typing-refresh task, or None when ``typing_indicator=False``.
``stop_event`` is passed only when the (possibly overridden) ``_keep_typing`` accepts it."""
if not getattr(self.config, "typing_indicator", True):
return None
kwargs: Dict[str, Any] = {"metadata": metadata}
try:
sig = inspect.signature(self._keep_typing)
except (TypeError, ValueError):
sig = None
if sig is None or "stop_event" in sig.parameters:
kwargs["stop_event"] = interrupt_event
return asyncio.create_task(self._keep_typing(event.source.chat_id, **kwargs))
async def _extract_response_content(
self, response: str, event: MessageEvent, session_key: str, *, is_ephemeral_response: bool,
) -> "_ExtractedResponse":
"""Split a handler response into deliverable text + attachments.
Order matters: MEDIA tags → image URLs → residual directives → bare local
paths (skipped for ephemeral/system notices so config paths stay text;
unknown-extension MEDIA tags survive the strip so the bare-path detector
sees them). History dedup is bare-path only, off-loop and fail-open. If
extraction empties a non-empty response, the post-extract text is recovered.
"""
# Captured before extract_media strips it: routes image files through
# send_document (original bytes, no sendPhoto recompression).
force_document = "[[as_document]]" in response
pre_extract = response
media_files, response = self.extract_media(response)
media_files = self.filter_media_delivery_paths(media_files, session_key=session_key)
images, text_content = self.extract_images(response)
text_content = _strip_media_directives(text_content).strip()
if images:
logger.info("[%s] extract_images found %d image(s) in response (%d chars)", self.name, len(images), len(response))
local_files = []
if not is_ephemeral_response:
local_files, text_content = self.extract_local_files(text_content)
local_files = self.filter_local_delivery_paths(local_files, session_key=session_key)
_history_media_paths = None
if local_files:
_history_media_paths = await self._bounded_history_media_paths_for_session(session_key)
if _history_media_paths:
_suppressed = [p for p in local_files if p in _history_media_paths]
if _suppressed:
logger.info(
"[%s] Suppressing %d bare local file path(s) already "
"delivered in this session: %s",
self.name, len(_suppressed), _suppressed,
)
local_files = [p for p in local_files if p not in _history_media_paths]
if local_files:
logger.info("[%s] extract_local_files found %d file(s) in response", self.name, len(local_files))
if not (text_content or images or local_files or media_files):
_recovered = _strip_media_directives(response).strip()
if _recovered:
logger.warning(
"[%s] response_delivery_recovered: extract pipeline "
"reduced a non-empty response (%d chars) to empty with "
"no attachment; delivering recovered original to %s",
self.name, len(pre_extract), event.source.chat_id,
)
text_content = _recovered
return _ExtractedResponse(
text_content=text_content, images=images, media_files=media_files,
local_files=local_files, force_document_attachments=force_document, pre_extract=pre_extract,
)
async def _fire_post_delivery_callback(self, session_key: str, interrupt_event: asyncio.Event) -> None:
"""Run the one-shot post-delivery callback (bounded, errors swallowed).
The generation is snapshotted HERE: ``_hermes_run_generation`` is stamped on
the interrupt event DURING the handler await, so an earlier snapshot would
be None and let stale runs fire a fresher run's callbacks."""
_callback_generation = getattr(interrupt_event, "_hermes_run_generation", None)
if hasattr(self, "pop_post_delivery_callback"):
_post_cb = self.pop_post_delivery_callback(session_key, generation=_callback_generation)
else:
_post_cb = getattr(self, "_post_delivery_callbacks", {}).pop(session_key, None)
if callable(_post_cb):
try:
_post_result = _post_cb()
if inspect.isawaitable(_post_result):
await asyncio.wait_for(_post_result, timeout=_POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS)
except (asyncio.TimeoutError, Exception):
pass
def _finish_session_task(self, session_key: str, interrupt_event: asyncio.Event) -> None:
"""Final guard/ownership reconciliation at the end of a processing task.
A late arrival in ``_pending_messages`` must not be dropped: if another task
already owns the session (drain handoff) re-queue it for that task, else
spawn the drain task and leave the guard for it. With nothing pending,
release the guard only if we still own the session.
"""
late_pending = self._pending_messages.pop(session_key, None)
current_task = asyncio.current_task()
if late_pending is not None:
existing_task = self._session_tasks.get(session_key)
if existing_task is not None and existing_task is not current_task:
self._pending_messages[session_key] = late_pending
else:
logger.debug(
"[%s] Late-arrival pending message during cleanup — spawning drain task",
self.name,
)
self._spawn_drain_task(late_pending, session_key)
elif current_task is not None and self._session_tasks.get(session_key) is current_task:
self._cleanup_finished_session_task(session_key, interrupt_event)
async def _process_message_background(self, event: MessageEvent, session_key: str) -> None:
"""Background task that actually processes the message."""
# Track delivery outcomes for the processing-complete hook
delivery_attempted = False
delivery_succeeded = False
def _record_delivery(result):
nonlocal delivery_attempted, delivery_succeeded
if result is None:
return
delivery_attempted = True
if getattr(result, "success", False):
delivery_succeeded = True
# Reuse the interrupt event handle_message() installed before spawning
# this task; fall back to a new Event only if it was removed externally.
interrupt_event = self._active_sessions.get(session_key) or asyncio.Event()
self._active_sessions[session_key] = interrupt_event
_thread_metadata = _thread_metadata_for_source(event.source, _reply_anchor_for_event(event))
typing_task = self._start_typing_refresh(event, interrupt_event, _thread_metadata)
async def _stop_typing_task() -> None:
await self._stop_typing_refresh(event.source.chat_id, typing_task, metadata=_thread_metadata)
try:
await self._run_processing_hook("on_processing_start", event)
response = await self._message_handler(event)
is_ephemeral_response = isinstance(response, EphemeralReply)
# Unwrap EphemeralReply for downstream text processing; TTL applies after send.
response, _ephemeral_ttl = self._unwrap_ephemeral(response)
# None/empty is normal (streamed or queued). Suppress a stale response
# when the session was interrupted by a still-pending message.
if (response and interrupt_event.is_set() and session_key in self._pending_messages):
logger.info(
"[%s] Suppressing stale response for interrupted session %s",
self.name,
session_key,
)
response = None
if not response:
logger.debug("[%s] Handler returned empty/None response for %s", self.name, event.source.chat_id)
if response:
extracted = await self._extract_response_content(
response, event, session_key, is_ephemeral_response=is_ephemeral_response,
)
text_content, media_files = extracted.text_content, extracted.media_files
# Final user-visible content gets notify=True; typing/status
# metadata stays unmarked so progress bubbles remain thread-strict.
_final_thread_metadata = _mark_notify_metadata(_thread_metadata)
# Auto-TTS on voice input (voice-first), gated by /voice or voice.auto_tts;
# skipped when streaming TTS already delivered audio this turn.
_tts_paths: List[str] = []
_tts_requested_path = None
if (self._should_auto_tts_for_chat(event.source.chat_id)
and event.message_type == MessageType.VOICE
and text_content
and not media_files
and not self._streaming_tts_turn_completed(
session_key,
getattr(interrupt_event, "_hermes_run_generation", None),
event=event,
)):
_tts_paths, _tts_requested_path = await self._synthesize_auto_tts(text_content)
# TTS plays before text; generated files are removed afterwards. On
# Telegram the ORIGINAL reply text rides as the first file's caption
# when ≤1024 chars and the separate text send is skipped.
_tts_caption_delivered = False
_tts_cleanup_paths = {_tts_requested_path, *_tts_paths} - {None}
for _tts_index, _tts_path in enumerate(_tts_paths):
try:
telegram_tts_caption = None
if (
_tts_index == 0
and self.platform == Platform.TELEGRAM
and text_content
and text_content[:1024] == text_content
):
telegram_tts_caption = text_content
tts_result = await self.play_tts(
chat_id=event.source.chat_id,
audio_path=_tts_path,
caption=telegram_tts_caption,
metadata=_final_thread_metadata,
)
_record_delivery(tts_result)
_tts_caption_delivered = bool(
_tts_caption_delivered
or (telegram_tts_caption and getattr(tts_result, "success", False))
)
finally:
try:
os.remove(_tts_path)
except OSError:
pass
if not _tts_paths and _tts_cleanup_paths:
for _cleanup_path in _tts_cleanup_paths:
try:
os.remove(_cleanup_path)
except OSError:
pass
if text_content and not _tts_caption_delivered:
await self._send_final_text(
event, session_key, text_content, _final_thread_metadata,
is_ephemeral_response, _ephemeral_ttl, _record_delivery,
)
await self._deliver_attachments(
event, extracted, _final_thread_metadata,
anything_sent=delivery_attempted or _tts_caption_delivered,
)
processing_ok = delivery_succeeded if delivery_attempted else not bool(response)
# Clean up the per-turn streaming-TTS flag.
self._streaming_tts_completed_turns.discard(
self._streaming_tts_turn_key(
session_key, getattr(interrupt_event, "_hermes_run_generation", None), event=event,
)
or ""
)
await self._run_processing_hook(
"on_processing_complete",
event,
ProcessingOutcome.SUCCESS if processing_ok else ProcessingOutcome.FAILURE,
)
# The active drain owns debounce state: force-flush an unfired
# queue-mode timer so this task hands off the follow-up.
await self._flush_text_debounce_now(session_key)
# Hand a queued follow-up to a fresh drain task. Clear the Event BEFORE
# the stop-typing await so a concurrent inbound still sees a live guard.
if session_key in self._pending_messages:
pending_event = self._pending_messages.pop(session_key)
logger.debug("[%s] Processing queued follow-up message", self.name)
_active = self._active_sessions.get(session_key)
if _active is not None:
_active.clear()
await _stop_typing_task()
self._spawn_drain_task(pending_event, session_key)
return # Drain task owns the session now.
except asyncio.CancelledError:
current_task = asyncio.current_task()
outcome = ProcessingOutcome.CANCELLED
if current_task is None or current_task not in self._expected_cancelled_tasks:
outcome = ProcessingOutcome.FAILURE
await self._run_processing_hook("on_processing_complete", event, outcome)
raise
except BaseException as e:
await self._run_processing_hook("on_processing_complete", event, ProcessingOutcome.FAILURE)
logger.error("[%s] Error handling message: %s", self.name, e, exc_info=True)
_thread_metadata = (await self._notify_turn_error(event, e)) or _thread_metadata
# SystemExit/KeyboardInterrupt must propagate; other BaseExceptions are
# contained so this task never logs "exception was never retrieved".
if isinstance(e, (SystemExit, KeyboardInterrupt)):
raise
finally:
# Stop typing BEFORE the post-delivery callback: a stuck callback
# must not leave the typing refresh running indefinitely.
await _stop_typing_task()
await self._fire_post_delivery_callback(session_key, interrupt_event)
# Callback work or a late refresh may have recreated a platform
# typing task — one final bounded stop before releasing the guard.
await self._stop_typing_refresh(
event.source.chat_id, None, metadata=_thread_metadata, stop_attempts=1,
)
# Flush any timer that missed the in-band drain, then reconcile ownership.
await self._flush_text_debounce_now(session_key)
self._finish_session_task(session_key, interrupt_event)
def _spawn_drain_task(self, pending_event: MessageEvent, session_key: str) -> None:
"""Hand the session to a fresh task for a queued follow-up — never recurse
(each chained follow-up grew the C stack and could SIGSEGV). Clearing, not
deleting, the Event keeps the guard live for concurrent inbound messages;
ownership moves to the drain task so stale-lock detection still works."""
_active = self._active_sessions.get(session_key)
if _active is not None:
_active.clear()
drain_task = asyncio.create_task(self._process_message_background(pending_event, session_key))
self._session_tasks[session_key] = drain_task
try:
self._background_tasks.add(drain_task)
drain_task.add_done_callback(self._background_tasks.discard)
except TypeError:
pass # Tests stub create_task() with non-hashable sentinels; tolerate.
def _cleanup_finished_session_task(
self, session_key: str, interrupt_event: Optional[asyncio.Event]
) -> None:
"""Release the guard for a finished owner task, then drop its
``_session_tasks`` entry ONLY if the guard was actually released: when a
concurrent path swapped in a different guard, keeping the done-task entry
lets ``_session_task_is_stale`` heal the orphan instead of deadlocking."""
self._release_session_guard(session_key, guard=interrupt_event)
if session_key not in self._active_sessions:
self._session_tasks.pop(session_key, None)
async def cancel_background_tasks(self) -> None:
"""Cancel in-flight background message tasks (gateway shutdown/replacement).
Each is awaited with a 5s bound; stragglers are untracked and left to unwind."""
# Re-drain until the task set stabilizes: a message arriving during the
# gather would spawn a new task that the final clear() would untrack.
MAX_DRAIN_ROUNDS = 5
for _ in range(MAX_DRAIN_ROUNDS):
tasks = [task for task in self._background_tasks if not task.done()]
if not tasks:
break
for task in tasks:
self._expected_cancelled_tasks.add(task)
task.cancel()
try:
await asyncio.wait_for(
asyncio.gather(*(asyncio.shield(t) for t in tasks), return_exceptions=True),
timeout=5.0,
)
except asyncio.TimeoutError:
logger.warning(
"[%s] %d background task(s) did not exit within 5s; "
"releasing tracking and letting them unwind in the background",
self.name, len([t for t in tasks if not t.done()]),
)
break
self._background_tasks.clear()
self._expected_cancelled_tasks.clear()
self._session_tasks.clear()
# Flush pending messages to disk before clearing.
try:
from gateway.shutdown_flush import flush_pending_to_file
flush_pending_to_file(self._pending_messages, reason="adapter_shutdown")
except Exception:
pass
self._pending_messages.clear()
self._active_sessions.clear()
for state in list(self._text_debounce_store().values()):
state.cancel_timer()
self._text_debounce_store().clear()
def has_pending_interrupt(self, session_key: str) -> bool:
"""Check if there's a pending interrupt for a session."""
return session_key in self._active_sessions and self._active_sessions[session_key].is_set()
def get_pending_message(self, session_key: str) -> Optional[MessageEvent]:
"""Get and clear any pending message for a session."""
return self._pending_messages.pop(session_key, None)
def build_source(
self,
chat_id: str,
chat_name: Optional[str] = None,
chat_type: str = "dm",
user_id: Optional[str] = None,
user_name: Optional[str] = None,
thread_id: Optional[str] = None,
chat_topic: Optional[str] = None,
user_id_alt: Optional[str] = None,
chat_id_alt: Optional[str] = None,
is_bot: bool = False,
scope_id: Optional[str] = None,
guild_id: Optional[str] = None,
parent_chat_id: Optional[str] = None,
message_id: Optional[str] = None,
role_authorized: bool = False,
auto_thread_created: bool = False,
auto_thread_initial_name: Optional[str] = None,
) -> SessionSource:
"""Build a SessionSource for this platform. With ``gateway.profile_routes``
configured, the matching profile is stamped on ``source.profile`` for
per-profile HERMES_HOME isolation downstream."""
if chat_topic is not None and not chat_topic.strip():
chat_topic = None
def _opt(value) -> Optional[str]:
return str(value) if value else None
fields = dict(
platform=self.platform, chat_id=str(chat_id), chat_name=chat_name, chat_type=chat_type,
user_id=_opt(user_id), user_name=user_name, thread_id=_opt(thread_id),
chat_topic=chat_topic.strip() if chat_topic else None,
user_id_alt=user_id_alt, chat_id_alt=chat_id_alt, is_bot=is_bot,
scope_id=_opt(scope_id), guild_id=_opt(guild_id), parent_chat_id=_opt(parent_chat_id),
message_id=_opt(message_id),
)
# Resolve profile from configured routes (None when no match / no routes)
profile = None
profile_route_rejected = False
runner = getattr(self, "gateway_runner", None)
if runner is not None:
from gateway.profile_routing import ProfileRouteRejected
try:
profile = runner._profile_name_for_source(SessionSource(**fields))
except ProfileRouteRejected:
profile_route_rejected = True
except Exception:
logger.warning(
"Profile resolution failed for %s/%s, defaulting to active profile",
self.platform, chat_id, exc_info=True,
)
source = SessionSource(
**fields,
profile=profile,
role_authorized=role_authorized,
auto_thread_created=auto_thread_created,
auto_thread_initial_name=auto_thread_initial_name,
)
# Not serialized by to_dict(): the live receiving adapter is authoritative
# for this turn even when profile_routes selects a different runtime.
source._transport_adapter_ref = weakref.ref(self)
# Transport-only fail-closed signal, kept out of SessionSource serialization;
# the shared handler consumes it before auth so rejected routes never 500.
source.profile_route_rejected = profile_route_rejected
return source
@abstractmethod
async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
"""Get information about a chat/channel; dict with at least ``name``
and ``type`` ("dm", "group", "channel")."""
pass
def toolsets_for_source(self, source: "SessionSource") -> Optional[List[str]]:
"""Per-source toolset override: a list of toolset keys that REPLACES the
``platform_toolsets.<platform>`` resolution, or None (default). Validated
through ``_get_platform_tools`` so unknown/restricted names are dropped.
Used by the webhook adapter to pin per-route toolsets."""
return None
def format_message(self, content: str) -> str:
"""Format a message for this platform (override for e.g. Telegram
MarkdownV2); default returns content as-is."""
return content
@staticmethod
def truncate_message(
content: str,
max_length: int = 4096,
len_fn: Optional["Callable[[str], int]"] = None,
) -> List[str]:
"""Split a long message into chunks, preserving code-block boundaries.
A split inside a triple-backtick block closes the fence at the chunk end
and reopens it (same language tag) in the next chunk; multi-chunk output
gets ``(1/3)`` indicators. ``len_fn`` overrides ``len`` (pass ``utf16_len``
for platforms like Telegram that count UTF-16 code units).
"""
_len = len_fn or len
if _len(content) <= max_length:
return [content]
INDICATOR_RESERVE = 10 # room for " (XX/XX)"
FENCE_CLOSE = "\n```"
chunks: List[str] = []
remaining = content
# Language tag (possibly "") when the previous chunk ended mid-code-block.
carry_lang: Optional[str] = None
while remaining:
prefix = f"```{carry_lang}\n" if carry_lang is not None else ""
# Body budget after prefix, potential closing fence, and chunk indicator.
headroom = max_length - INDICATOR_RESERVE - _len(prefix) - _len(FENCE_CLOSE)
if headroom < 1:
# Floor so a pathologically small max_length (0/1 from a relay
# capability descriptor) can't zero the headroom and stall the loop.
headroom = max(1, max_length // 2)
# Remainder fits in one final chunk; close a reopened fence if still open.
if _len(prefix) + _len(remaining) <= max_length - INDICATOR_RESERVE:
final_chunk = prefix + remaining
if carry_lang is not None and fence_state_after(remaining, True, carry_lang)[0]:
final_chunk += FENCE_CLOSE
chunks.append(final_chunk)
break
# Natural split (newline, then space). With a custom _len (utf16_len),
# headroom is in custom units: map it to the largest codepoint offset
# whose custom length fits the budget.
if _len is not len:
_cp_limit = _custom_unit_to_cp(remaining, headroom, _len)
else:
_cp_limit = headroom
region = remaining[:_cp_limit]
split_at = region.rfind("\n")
if split_at < _cp_limit // 2:
split_at = region.rfind(" ")
if split_at < 1:
# Floor at one codepoint: a zero _cp_limit (max_length 0/1, or a
# surrogate pair wider than the utf16 budget) would never shrink
# ``remaining`` and spin forever. The chunk then intentionally exceeds
# max_length by that codepoint — whole content beats data loss or a hang.
split_at = max(1, _cp_limit)
# Don't split inside an inline code span: an odd count of unescaped
# backticks would leave an unpaired one and break Telegram MarkdownV2.
candidate = remaining[:split_at]
backtick_count = candidate.count("`") - candidate.count("\\`")
if backtick_count % 2 == 1:
last_bt = candidate.rfind("`")
while last_bt > 0 and candidate[last_bt - 1] == "\\":
last_bt = candidate.rfind("`", 0, last_bt)
if last_bt > 0:
safe_split = candidate.rfind(" ", 0, last_bt)
nl_split = candidate.rfind("\n", 0, last_bt)
safe_split = max(safe_split, nl_split)
if safe_split > _cp_limit // 4:
split_at = safe_split
chunk_body = remaining[:split_at]
remaining = remaining[split_at:].lstrip()
full_chunk = prefix + chunk_body
# Walk only chunk_body (not the prepended prefix) for the fence state.
in_code, lang = fence_state_after(chunk_body, carry_lang is not None, carry_lang or "")
if in_code:
# Close the orphaned fence so the chunk is valid on its own
full_chunk += FENCE_CLOSE
carry_lang = lang
else:
carry_lang = None
chunks.append(full_chunk)
if len(chunks) > 1:
total = len(chunks)
chunks = [f"{chunk} ({i + 1}/{total})" for i, chunk in enumerate(chunks)]
return chunks
Reference in New Issue View Git Blame Copy Permalink