diff --git a/plugins/platforms/telegram/adapter.py b/plugins/platforms/telegram/adapter.py index 818d4a3e1e..f4280bf045 100644 --- a/plugins/platforms/telegram/adapter.py +++ b/plugins/platforms/telegram/adapter.py @@ -1,13 +1,7 @@ -""" -Telegram platform adapter. - -Uses python-telegram-bot library for: -- Receiving messages from users/groups -- Sending responses back -- Handling media and commands -""" +"""Telegram platform adapter (python-telegram-bot): inbound messages/media/commands, outbound replies.""" import asyncio +import contextlib import dataclasses import inspect import json @@ -32,21 +26,15 @@ def _redact_telegram_error_text(error: object) -> str: return text try: from agent.redact import redact_sensitive_text - return redact_sensitive_text(text, force=True) except Exception: return "" def _scoped_gate_env(name: str, default: str = "") -> str: - """Read a TELEGRAM_*/GATEWAY_* gate env var per-profile. - - Under multiplex_profiles the process env is first-writer-wins, so raw ``os.getenv`` can - return ANOTHER profile's allowlist. Falls back to ``os.getenv`` outside multiplex. - """ + """Per-profile TELEGRAM_*/GATEWAY_* gate env read (multiplex env is first-writer-wins).""" try: from gateway.authz_mixin import _platform_gate_env - return _platform_gate_env(name, default) except Exception: return (os.getenv(name) or default).strip() @@ -63,26 +51,19 @@ def _consume_abandoned_task(task: asyncio.Task) -> None: async def _await_with_thread_deadline(awaitable, timeout: float, *, on_abandon=None): - """Await with a wall-clock (thread-timer) deadline that survives a blocked event loop. + """Wall-clock deadline that survives a blocked loop / cancellation-shielded PTB+httpcore init. - Wrapper over ``run_bounded_async``: abandons cancellation-shielded tasks (PTB/httpcore - init inside anyio scopes) and runs ``on_abandon`` detached so an abandoned initialize() - can't leak an httpx pool. Raises ``asyncio.TimeoutError`` on expiry (PTB retry ladder). - """ - result = await run_bounded_async( - awaitable, timeout, label="telegram-init", on_abandon=on_abandon - ) + ``on_abandon`` runs detached so an abandoned initialize() can't leak an httpx pool. Raises + ``asyncio.TimeoutError`` on expiry (feeds the PTB retry ladder).""" + result = await run_bounded_async(awaitable, timeout, label="telegram-init", on_abandon=on_abandon) if result.timed_out: raise asyncio.TimeoutError() return result.value def _iter_exception_graph(error: BaseException) -> "Iterator[BaseException]": - """Yield ``error`` and every ``__cause__``/``__context__`` ancestor (DFS, cycle-safe). - - PTB wraps httpx exceptions and re-raises accumulate ``__context__`` chains, so - classifiers must inspect the whole graph, not just the top frame. - """ + """Yield ``error`` and every ``__cause__``/``__context__`` ancestor (DFS, cycle-safe) — + PTB wraps httpx errors, so classifiers must inspect the whole graph.""" seen: set[int] = set() stack: list[BaseException] = [error] while stack: @@ -92,26 +73,12 @@ def _iter_exception_graph(error: BaseException) -> "Iterator[BaseException]": continue seen.add(ident) yield cur - cause = getattr(cur, "__cause__", None) - context = getattr(cur, "__context__", None) - if cause is not None: - stack.append(cause) - if context is not None: - stack.append(context) - - -async def _first_completed(*futures: "asyncio.Future") -> None: - """Return when the first of ``futures`` completes; losers are NOT cancelled.""" - await asyncio.wait(set(futures), return_when=asyncio.FIRST_COMPLETED) + stack.extend(x for x in (getattr(cur, "__cause__", None), getattr(cur, "__context__", None)) if x is not None) async def _shutdown_abandoned_app(app) -> None: - """Release a half-built PTB app's httpx transports after init was abandoned. - - ``app.shutdown()`` is gated on ``_initialized`` flags a wedged ``initialize()`` never set, - so it no-ops and leaks the pool. ``HTTPXRequest`` builds its client eagerly and its - ``shutdown()`` gates only on ``client.is_closed``, so we also close transports directly. - """ + """Release a half-built PTB app's httpx transports after an abandoned init: ``app.shutdown()`` + no-ops when ``_initialized`` was never set, so the request transports are closed directly.""" if app is None: return try: @@ -119,10 +86,7 @@ async def _shutdown_abandoned_app(app) -> None: except Exception: logger.debug("Abandoned Telegram app.shutdown() failed", exc_info=True) bot = getattr(app, "bot", None) - requests = getattr(bot, "_request", None) if bot is not None else None - if not requests: - return - for request in requests: + for request in (getattr(bot, "_request", None) if bot is not None else None) or (): shutdown = getattr(request, "shutdown", None) if shutdown is None: continue @@ -140,30 +104,16 @@ try: except ImportError: LinkPreviewOptions = None from telegram.ext import ( - Application, CommandHandler, CallbackQueryHandler, InlineQueryHandler, - MessageHandler as TelegramMessageHandler, ContextTypes, TypeHandler, filters, - ) + Application, CommandHandler, CallbackQueryHandler, InlineQueryHandler, MessageHandler as TelegramMessageHandler, + ContextTypes, TypeHandler, filters) from telegram.constants import ParseMode, ChatType from telegram.request import HTTPXRequest TELEGRAM_AVAILABLE = True except ImportError: TELEGRAM_AVAILABLE = False - Update = Any - Bot = Any - Message = Any - InlineKeyboardButton = Any - InlineKeyboardMarkup = Any - LinkPreviewOptions = None - Application = Any - CommandHandler = Any - CallbackQueryHandler = Any - InlineQueryHandler = Any - TypeHandler = Any - TelegramMessageHandler = Any - HTTPXRequest = Any - filters = None - ParseMode = None - ChatType = None + Update = Bot = Message = InlineKeyboardButton = InlineKeyboardMarkup = Application = Any + CommandHandler = CallbackQueryHandler = InlineQueryHandler = TypeHandler = TelegramMessageHandler = HTTPXRequest = Any + LinkPreviewOptions = filters = ParseMode = ChatType = None # Mock so ContextTypes.DEFAULT_TYPE annotations don't crash class definition without the lib. class _MockContextTypes: @@ -177,23 +127,17 @@ sys.path.insert(0, str(_Path(__file__).resolve().parents[3])) from gateway.authz_mixin import _coerce_allow_set from gateway.config import Platform, PlatformConfig from gateway.platforms.base import ( - BasePlatformAdapter, MessageEvent, MessageType, ProcessingOutcome, SendResult, - classify_send_error, cache_image_from_bytes, cache_audio_from_bytes, cache_video_from_bytes, - resolve_proxy_url, SUPPORTED_VIDEO_TYPES, SUPPORTED_DOCUMENT_TYPES, - SUPPORTED_IMAGE_DOCUMENT_TYPES, _TEXT_INJECT_EXTENSIONS, utf16_len, -) + BasePlatformAdapter, MessageEvent, MessageType, ProcessingOutcome, SendResult, classify_send_error, + cache_image_from_bytes, cache_audio_from_bytes, cache_video_from_bytes, resolve_proxy_url, SUPPORTED_VIDEO_TYPES, + SUPPORTED_DOCUMENT_TYPES, SUPPORTED_IMAGE_DOCUMENT_TYPES, _TEXT_INJECT_EXTENSIONS, utf16_len) from plugins.platforms.telegram.telegram_ids import normalize_telegram_chat_id from plugins.platforms.telegram.telegram_network import ( - SEED_FALLBACK_IPS, TelegramFallbackTransport, discover_fallback_ips, parse_fallback_ip_env, - tcp_keepalive_socket_options, -) + SEED_FALLBACK_IPS, TelegramFallbackTransport, discover_fallback_ips, parse_fallback_ip_env, tcp_keepalive_socket_options) from utils import env_float, env_int _TELEGRAM_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp", ".gif"} - -# Max seconds a send/edit may sleep inline on a flood-control RetryAfter. Longer penalties -# fail closed with a ``flood_control:{wait}`` SendResult so the caller's retry machinery -# (delivery ledger, streaming fallback) owns the wait instead of pinning a worker. +# Max seconds a send/edit may sleep inline on a flood-control RetryAfter; longer penalties fail +# closed with ``flood_control:{wait}`` so the caller's retry machinery owns the wait. _FLOOD_INLINE_WAIT_CAP_SECS = 5.0 @@ -202,14 +146,8 @@ def _flood_cap_result(wait: float) -> "SendResult": return SendResult(success=False, error=f"flood_control:{wait}", retry_after=float(wait)) -_TELEGRAM_IMAGE_MIME_TO_EXT = { - "image/png": ".png", "image/jpeg": ".jpg", "image/jpg": ".jpg", "image/webp": ".webp", - "image/gif": ".gif", -} -_TELEGRAM_IMAGE_EXT_TO_MIME = { - ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", - ".gif": "image/gif", -} +_TELEGRAM_IMAGE_MIME_TO_EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/jpg": ".jpg", "image/webp": ".webp", "image/gif": ".gif"} +_TELEGRAM_IMAGE_EXT_TO_MIME = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif"} def _coerce_duration_seconds(value: Any) -> Optional[int]: @@ -222,43 +160,33 @@ def _coerce_duration_seconds(value: Any) -> Optional[int]: def _probe_voice_duration_seconds(path: str) -> Optional[int]: - """Best-effort audio length in whole seconds for outgoing voice/audio (None if unreadable). + """Best-effort whole-second audio length (wave → mutagen → ffprobe; None if unreadable). - Telegram only derives duration from metadata for short clips; longer ones render as 0:00, - so we pass it explicitly. Tries wave (WAV), mutagen, then ffprobe — mirrors - ``gateway.run._probe_audio_duration``. Blocking: call via ``asyncio.to_thread``. - """ - ext = os.path.splitext(path)[1].lower() - if ext == ".wav": + Telegram renders long clips as 0:00 without an explicit duration. Blocking: use ``to_thread``.""" + if os.path.splitext(path)[1].lower() == ".wav": try: import wave with wave.open(path, "rb") as wf: rate = wf.getframerate() or 0 - if rate: - secs = _coerce_duration_seconds(wf.getnframes() / float(rate)) - if secs is not None: - return secs + secs = _coerce_duration_seconds(wf.getnframes() / float(rate)) if rate else None + if secs is not None: + return secs except Exception: pass - try: import mutagen - audio = mutagen.File(path) - secs = _coerce_duration_seconds(getattr(getattr(audio, "info", None), "length", None)) + secs = _coerce_duration_seconds(getattr(getattr(mutagen.File(path), "info", None), "length", None)) if secs is not None: return secs except Exception: pass - try: import shutil import subprocess if shutil.which("ffprobe"): proc = subprocess.run( - ["ffprobe", "-v", "error", "-show_entries", "format=duration", - "-of", "default=noprint_wrappers=1:nokey=1", path], - capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5, - ) + ["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", path], + capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5) if proc.returncode == 0: return _coerce_duration_seconds(proc.stdout.strip()) except Exception: @@ -267,11 +195,8 @@ def _probe_voice_duration_seconds(path: str) -> Optional[int]: def telegram_deps_present() -> bool: - """PASSIVE probe: is python-telegram-bot importable? Must never install anything. - - Registry ``check_fn`` (status displays, config loading). The ACTIVE lazy-installer is - ``check_telegram_requirements`` (``ensure_deps_fn``, run from ``create_adapter()``). - """ + """PASSIVE registry ``check_fn``: is python-telegram-bot importable? Never installs + (``check_telegram_requirements`` is the active ``ensure_deps_fn``).""" return TELEGRAM_AVAILABLE @@ -289,38 +214,19 @@ def check_telegram_requirements() -> bool: except Exception: return False try: - from telegram import Update as _Update, Bot as _Bot, Message as _Message - from telegram import InlineKeyboardButton as _IKB, InlineKeyboardMarkup as _IKM - try: - from telegram import LinkPreviewOptions as _LPO - except ImportError: - _LPO = None - from telegram.ext import ( - Application as _App, CommandHandler as _CH, CallbackQueryHandler as _CQH, - InlineQueryHandler as _IQH, MessageHandler as _MH, ContextTypes as _CT, - filters as _filters, TypeHandler as _TH, - ) - from telegram.constants import ParseMode as _PM, ChatType as _CtT - from telegram.request import HTTPXRequest as _HR - except ImportError: + import importlib + _tg, _ext, _const, _req = ( + importlib.import_module(m) for m in ("telegram", "telegram.ext", "telegram.constants", "telegram.request")) + Update, Bot, Message, InlineKeyboardButton, InlineKeyboardMarkup = ( + getattr(_tg, n) for n in ("Update", "Bot", "Message", "InlineKeyboardButton", "InlineKeyboardMarkup")) + LinkPreviewOptions = getattr(_tg, "LinkPreviewOptions", None) + Application, CommandHandler, CallbackQueryHandler, InlineQueryHandler, TelegramMessageHandler = ( + getattr(_ext, n) for n in ("Application", "CommandHandler", "CallbackQueryHandler", "InlineQueryHandler", "MessageHandler")) + ContextTypes, filters, TypeHandler = _ext.ContextTypes, _ext.filters, _ext.TypeHandler + ParseMode, ChatType = _const.ParseMode, _const.ChatType + HTTPXRequest = _req.HTTPXRequest + except (ImportError, AttributeError): return False - Update = _Update - Bot = _Bot - Message = _Message - InlineKeyboardButton = _IKB - InlineKeyboardMarkup = _IKM - LinkPreviewOptions = _LPO - Application = _App - CommandHandler = _CH - CallbackQueryHandler = _CQH - InlineQueryHandler = _IQH - TelegramMessageHandler = _MH - ContextTypes = _CT - filters = _filters - ParseMode = _PM - ChatType = _CtT - HTTPXRequest = _HR - TypeHandler = _TH TELEGRAM_AVAILABLE = True return True @@ -339,8 +245,7 @@ def _strip_mdv2(text: str) -> str: cleaned = re.sub(r'\\([_*\[\]()~`>#\+\-=|{}.!\\])', r'\1', text) # escape backslashes cleaned = re.sub(r'\*\*([^*]+)\*\*', r'\1', cleaned) # **bold** BEFORE MarkdownV2 *bold* cleaned = re.sub(r'\*([^*]+)\*', r'\1', cleaned) - # italic: word-boundary guarded so snake_case like my_variable_name survives - cleaned = re.sub(r'(?(?:\\)?\(\d+/ def _separate_chunk_indicator_from_fence(text: str) -> str: - """Move ``(N/M)`` chunk markers onto their own line after a closing code fence. - - ``truncate_message()`` appends the indicator to a chunk that may end with a synthesized - closing fence, yielding ````` \\(1/2\\)`` — Telegram rejects that as a fence and falls - back to plain text. - """ + """Move a ``(N/M)`` chunk marker that ``truncate_message()`` appended to a synthesized closing + fence onto its own line — Telegram rejects ````` \\(1/2\\)`` as a fence.""" return _CHUNK_INDICATOR_ON_FENCE_RE.sub(r'```\n\g', text) -# MarkdownV2 has no table syntax ('|' is just an escaped literal), so pipe tables are -# converted to bullet groups by the shared convert_table_to_bullets(). +# MarkdownV2 has no table syntax, so pipe tables become bullet groups via convert_table_to_bullets(). from gateway.platforms.helpers import ( - TABLE_SEPARATOR_RE as _TABLE_SEPARATOR_RE, - compile_mention_patterns, - convert_table_to_bullets as _wrap_markdown_tables, -) + TABLE_SEPARATOR_RE as _TABLE_SEPARATOR_RE, compile_mention_patterns, convert_table_to_bullets as _wrap_markdown_tables) - -# Rich-message newline normalization. Protected regions whose internal newlines must stay -# bare: fenced code blocks OR GFM pipe-table blocks (header row, delimiter row, data rows). -# Telegram renders both natively; injected hard breaks would corrupt them. +# Rich-message regions whose internal newlines must stay bare (Telegram renders them natively): +# fenced code blocks OR GFM pipe-table blocks (header row, delimiter row, data rows). _RICH_PROTECTED_REGION_RE = re.compile( r'(?:```[^\n]*\n[\s\S]*?```)' # fenced code block r'|(?:^[^\n]*\|[^\n]*\n' # table header row (has a pipe) r'[ \t]*\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)+\|?[ \t]*' # delimiter r'(?:\n[^\n]*\|[^\n]*)*)', # data rows (newline-led, trailing \n left for prose) - re.MULTILINE, -) + re.MULTILINE) def _rich_normalize_linebreaks(text: str) -> str: - """Convert single ``\\n`` to Markdown hard breaks (two trailing spaces) for sendRichMessage. - - Markdown treats a lone ``\\n`` as a soft break, collapsing multi-line content into one - paragraph. ``\\n\\n``, fenced code and pipe-table blocks are left untouched. - """ + """Convert lone ``\\n`` (a Markdown soft break) to hard breaks for sendRichMessage; ``\\n\\n``, + fenced code and pipe tables are left untouched.""" if not text or '\n' not in text: return text out: list[str] = [] - # Inject hard breaks only in the prose between protected regions. pos = 0 for m in _RICH_PROTECTED_REGION_RE.finditer(text): - prose = text[pos:m.start()] - out.append(re.sub(r'(? float: + def _env_float_clamped(name: str, default: float, *, min_value: Optional[float] = None, max_value: Optional[float] = None) -> float: """Read a float env var; non-finite → default; clamp to bounds (safe for asyncio.sleep).""" import math raw = os.getenv(name) @@ -509,134 +375,100 @@ class TelegramAdapter(BasePlatformAdapter): def __init__(self, config: PlatformConfig): super().__init__(config, Platform.TELEGRAM) + extra = self.config.extra self._app: Optional[Application] = None self._bot: Optional[Bot] = None self._webhook_mode: bool = False self._mention_patterns = self._compile_mention_patterns() self._reply_to_mode: str = getattr(config, 'reply_to_mode', 'first') or 'first' self._disable_link_previews: bool = self._coerce_bool_extra("disable_link_previews", False) - # Bot API 10.1 Rich Messages (sendRichMessage / rich_message param) render constructs - # MarkdownV2 degrades (tables, task lists,
, block math). Keep opt-in: current - # clients make rich messages hard to copy as plain text, which is worse for command - # snippets and mobile handoffs. Enable via platforms.telegram.extra.rich_messages. + # Bot API 10.1 Rich Messages render what MarkdownV2 degrades (tables, task lists,
, block + # math). Opt-in: current clients make rich messages hard to copy as plain text. rich_drafts is a + # separate opt-in (Desktop can leave rich draft frames overlaid): off keeps native draft transport + # but skips rich draft rendering; the final reply still lands via sendRichMessage. self._rich_messages_enabled: bool = self._coerce_bool_extra("rich_messages", False) - # Separate opt-in: macOS/Desktop can leave rich draft frames overlaid until redraw. - # rich_messages on + rich_drafts off keeps native draft *transport* and only skips - # rich draft *rendering*; the final reply still lands via sendRichMessage. self._rich_drafts_enabled: bool = self._coerce_bool_extra("rich_drafts", False) - # Latched off after a capability failure (e.g. older PTB without the endpoint). - self._rich_send_disabled: bool = False - self._rich_draft_disabled: bool = False - # Transient sendChatAction failures recur on every keep-typing tick during a long - # model call; back off per chat so an outage doesn't spam the API/logs. + self._rich_send_disabled = self._rich_draft_disabled = False # latched after a capability failure + # Transient sendChatAction failures recur on every keep-typing tick; back off per chat. self._telegram_typing_cooldown_until: Dict[str, float] = {} self._telegram_typing_cooldown_seconds: float = self._coerce_float_extra( - "typing_cooldown_seconds", 30.0, min_value=1.0, max_value=300.0 - ) + "typing_cooldown_seconds", 30.0, min_value=1.0, max_value=300.0) # Buffer album/photo bursts into a single MessageEvent instead of self-interrupting turns. self._media_batch_delay_seconds = env_float("HERMES_TELEGRAM_MEDIA_BATCH_DELAY_SECONDS", 0.8) self._pending_photo_batches: Dict[str, MessageEvent] = {} self._pending_photo_batch_tasks: Dict[str, asyncio.Task] = {} self._media_group_events: Dict[str, MessageEvent] = {} self._media_group_tasks: Dict[str, asyncio.Task] = {} - # Aggregate client-side splits of long messages into one MessageEvent. Bounds are - # conservative for Telegram's ~1 edit/s flood envelope (see _calc_text_batch_delay). + # Aggregate client-side splits of long messages into one MessageEvent; bounds are conservative + # for Telegram's ~1 edit/s flood envelope. self._text_batch_delay_seconds = self._env_float_clamped( - "HERMES_TELEGRAM_TEXT_BATCH_DELAY_SECONDS", 0.3, min_value=0.08, max_value=2.0 - ) + "HERMES_TELEGRAM_TEXT_BATCH_DELAY_SECONDS", 0.3, min_value=0.08, max_value=2.0) self._text_batch_split_delay_seconds = self._env_float_clamped( - "HERMES_TELEGRAM_TEXT_BATCH_SPLIT_DELAY_SECONDS", 1.0, - min_value=self._text_batch_delay_seconds, max_value=4.0, - ) + "HERMES_TELEGRAM_TEXT_BATCH_SPLIT_DELAY_SECONDS", 1.0, min_value=self._text_batch_delay_seconds, max_value=4.0) self._pending_text_batches: Dict[str, MessageEvent] = {} self._pending_text_batch_tasks: Dict[str, asyncio.Task] = {} self._drop_delayed_deliveries = False - # Held across disconnect: PTB advances the polling offset before our drop-guard runs, - # so Telegram won't redeliver — dropping is permanent loss (see _hold_inbound_event). + # Held across disconnect: PTB advances the offset before our drop-guard runs, so Telegram won't + # redeliver — dropping is permanent loss (see _hold_inbound_event). self._held_inbound_events: List[MessageEvent] = [] self._held_inbound_redispatch_task: Optional[asyncio.Task] = None self._polling_error_task: Optional[asyncio.Task] = None - self._polling_conflict_count: int = 0 - self._polling_conflict_recovery_generation: Optional[int] = None - self._polling_network_error_count: int = 0 - self._polling_generation: int = 0 - self._polling_progress_event = asyncio.Event() - self._polling_progress_accepting: bool = False self._polling_progress_verifier_task: Optional[asyncio.Task] = None - self._polling_teardown_started: bool = False - self._polling_error_callback_ref = None self._polling_heartbeat_task: Optional[asyncio.Task] = None + self._bot_identity_refresh_task: Optional[asyncio.Task] = None + self._post_connect_task: Optional[asyncio.Task] = None # command menu + DM topics, off the connect path + self._polling_conflict_count = self._polling_network_error_count = self._polling_generation = 0 + self._polling_conflict_recovery_generation: Optional[int] = None + self._polling_progress_event = asyncio.Event() + self._polling_progress_accepting = self._polling_teardown_started = False + self._polling_error_callback_ref = None # Stall watchdog: generation start and last successful getUpdates (None = unknown). self._polling_generation_started_monotonic: Optional[float] = None self._polling_last_progress_monotonic: Optional[float] = None - # Live @username. PTB caches getMe() in Bot._bot_user at initialize() and only rewrites - # it inside get_me(), so a BotFather rename leaves self._bot.username stale. All - # mention/routing comparisons read _current_bot_username() instead. + # Live @username: PTB caches getMe() at initialize() and only rewrites it inside get_me(), so a + # BotFather rename leaves self._bot.username stale; routing reads _current_bot_username(). self._bot_username_observed: Optional[str] = None - # None = never checked. Must NOT be 0.0: compared against time.monotonic(), which on - # a fresh host starts near zero, so 0.0 would suppress the first refresh for a TTL. + # None = never checked. Must NOT be 0.0: compared against time.monotonic(), which on a fresh host + # starts near zero, so 0.0 would suppress the first refresh for a TTL. self._bot_identity_checked_at: Optional[float] = None - self._bot_identity_refresh_task: Optional[asyncio.Task] = None - # Consecutive heartbeat probes seeing queued updates the poller isn't consuming. - # get_me() can't see this (send path healthy, getUpdates wedged), so the heartbeat - # probes get_webhook_info().pending_update_count and escalates after two. - self._polling_pending_stuck_count: int = 0 - # Consecutive probes finding the updater stopped (running=False) in polling mode with - # no reconnect in flight — the long-poll task is simply gone, so no probe or PTB - # error_callback ever fires and the gateway silently stops receiving. - self._polling_not_running_count: int = 0 - # Degraded until getUpdates makes progress (start_polling() return and getMe() on the - # general path are NOT polling-health signals). While True, send() short-circuits to - # failure so callers (cron live-adapter branch) fall through to standalone delivery. + # Consecutive heartbeat probes seeing queued updates the poller isn't consuming (get_me() can't + # see a wedged getUpdates) / finding the updater stopped with no reconnect in flight; escalate after two. + self._polling_pending_stuck_count = self._polling_not_running_count = 0 + # Degraded until getUpdates makes progress; while True, send() short-circuits to failure so callers + # (cron live-adapter branch) fall through to standalone delivery. self._send_path_degraded: bool = False self._general_request_drain_lock = asyncio.Lock() self._dm_topics: Dict[str, int] = {} # topic_name -> message_thread_id self._forum_command_registered: set[int] = set() # forum chats with commands registered self._forum_lock = asyncio.Lock() - # Status indicator: sets the bot's short description to "Online"/"Offline" on - # connect/clean disconnect — bots have no presence dot. Off by default because it - # mutates the GLOBAL profile; opt in via extra.status_indicator/status_online/status_offline. - self._status_indicator_enabled: bool = bool( - self.config.extra.get("status_indicator", False) - ) - self._status_online_text: str = str(self.config.extra.get("status_online", "Online")) - self._status_offline_text: str = str(self.config.extra.get("status_offline", "Offline")) - self._dm_topics_config: List[Dict[str, Any]] = self.config.extra.get("dm_topics", []) + # Status indicator: bot short description "Online"/"Offline" on connect/clean disconnect. Off by + # default because it mutates the GLOBAL profile; opt in via extra.status_indicator. + self._status_indicator_enabled: bool = bool(extra.get("status_indicator", False)) + self._status_online_text: str = str(extra.get("status_online", "Online")) + self._status_offline_text: str = str(extra.get("status_offline", "Offline")) + self._dm_topics_config: List[Dict[str, Any]] = extra.get("dm_topics", []) # chat_ids with DM topics configured (O(1) root-DM ignore check) - self._dm_topic_chat_ids: Set[str] = { - str(e["chat_id"]) for e in self._dm_topics_config if "chat_id" in e - } + self._dm_topic_chat_ids: Set[str] = {str(e["chat_id"]) for e in self._dm_topics_config if "chat_id" in e} # getFile cap: 20MB on the public Bot API, 2GB on a local telegram-bot-api (base_url). - self._max_doc_bytes: int = ( - 2 * 1024 * 1024 * 1024 if self.config.extra.get("base_url") else 20 * 1024 * 1024 - ) + self._max_doc_bytes: int = 2 * 1024 * 1024 * 1024 if extra.get("base_url") else 20 * 1024 * 1024 self._model_picker_state: Dict[str, dict] = {} # per-chat interactive picker state self._choice_picker_state: Dict[str, dict] = {} self._approval_state: Dict[int, str] = {} # message_id → session_key - # confirm_id → session_key (see GatewayRunner._request_slash_confirm) - self._slash_confirm_state: Dict[str, str] = {} - # clarify_id → session_key (see GatewayRunner clarify_callback wiring) - self._clarify_state: Dict[str, str] = {} - # "important" (default): only final responses, approvals and slash confirmations - # notify; progress/streaming/status go out with disable_notification. - # "all": every message notifies (opt-in via display.platforms.telegram.notifications). + self._slash_confirm_state: Dict[str, str] = {} # confirm_id → session_key + self._clarify_state: Dict[str, str] = {} # clarify_id → session_key + # "important" (default): only final responses, approvals and slash confirmations notify; + # "all": every message notifies (display.platforms.telegram.notifications). self._notifications_mode: str = "important" - # send_or_update_status(): {(chat_id, status_key) -> message_id} so repeat calls edit - # the same bubble instead of appending. + # send_or_update_status(): {(chat_id, status_key) -> message_id} so repeat calls edit in place. self._status_message_ids: Dict[tuple, str] = {} - # Last truncated mid-stream preview per (chat_id, message_id). Once an oversized - # stream saturates the 4096 cap every edit truncates to the SAME text; resending is a - # no-op that still burns flood budget (200s+ penalties). Entries dropped on finalize. + # Last truncated mid-stream preview per (chat_id, message_id): past the 4096 cap every edit + # truncates to the SAME text, and resending burns flood budget. Dropped on finalize. self._last_overflow_preview: Dict[tuple, str] = {} - # Post-connect housekeeping (command menu + DM topics) runs off the connect path so a - # slow Bot API call (set_my_commands stall) can't blow the gateway connect timeout. - self._post_connect_task: Optional[asyncio.Task] = None def _mark_connected(self) -> None: self._drop_delayed_deliveries = False super()._mark_connected() - # Drain the hold queue — PTB will not redeliver these events. - self._schedule_held_inbound_redispatch() + self._schedule_held_inbound_redispatch() # PTB will not redeliver these events def _mark_disconnected(self) -> None: self._drop_delayed_deliveries = True @@ -645,18 +477,14 @@ class TelegramAdapter(BasePlatformAdapter): def _set_fatal_error(self, code: str, message: str, *, retryable: bool) -> None: self._drop_delayed_deliveries = True super()._set_fatal_error(code, message, retryable=retryable) - # Permanent fatal: no reconnect will drain, so discard the hold queue and refuse - # further holds (teardown salvage / late enqueue must not re-populate it). + # Permanent fatal: no reconnect will drain, so discard the hold queue (later holds are refused). if not retryable: held = getattr(self, "_held_inbound_events", None) n = len(held) if held else 0 if held: held.clear() if n: - logger.warning( - "[Telegram] Non-retryable fatal (%s); discarding %d held inbound message(s)", - code, n, - ) + logger.warning("[Telegram] Non-retryable fatal (%s); discarding %d held inbound message(s)", code, n) def _is_permanent_fatal(self) -> bool: """True after non-retryable fatal — holds must discard, not queue.""" @@ -665,11 +493,8 @@ class TelegramAdapter(BasePlatformAdapter): return not bool(getattr(self, "_fatal_error_retryable", True)) def _replacement_telegram_adapter(self) -> Optional["TelegramAdapter"]: - """Return the live adapter if the reconnect watcher replaced us in ``runner.adapters``. - - An in-flight ``send()`` still holds the old instance whose ``_bot`` stays None, so - waiting only on ``self._bot`` would drop the final reply. - """ + """Live adapter if the reconnect watcher replaced us in ``runner.adapters`` (an in-flight + ``send()`` still holds the old instance whose ``_bot`` stays None).""" runner = getattr(self, "gateway_runner", None) adapters = getattr(runner, "adapters", None) or {} live = adapters.get(self.platform) @@ -678,19 +503,14 @@ class TelegramAdapter(BasePlatformAdapter): return None async def _wait_for_reconnection(self) -> bool: - """Wait for ``_bot`` or a replacement adapter after a transient drop. - - Returns True if sending can proceed; False on wait expiry or permanent fatal. - """ + """Wait for ``_bot`` or a replacement adapter; False on expiry or permanent fatal.""" if self._bot or self._replacement_telegram_adapter() is not None: return True if self._is_permanent_fatal(): return False wait_s = float(getattr(self, "_RECONNECT_WAIT_SECONDS", 15.0)) poll_s = float(getattr(self, "_RECONNECT_POLL_INTERVAL", 0.5)) - logger.info( - "[%s] Not connected — waiting for reconnection (up to %.0fs)", self.name, wait_s - ) + logger.info("[%s] Not connected — waiting for reconnection (up to %.0fs)", self.name, wait_s) waited = 0.0 while waited < wait_s: await asyncio.sleep(poll_s) @@ -704,26 +524,16 @@ class TelegramAdapter(BasePlatformAdapter): return False def _should_drop_delayed_delivery(self) -> bool: - """True once teardown/fatal-error started — delayed flushes must not dispatch. - - Buffered flushes sit behind an asyncio.sleep(); if disconnect wins the race they'd - spawn an agent on a torn-down session. Callers must NOT destroy the event (PTB already - advanced the offset) — use ``_hold_inbound_event`` and redispatch on reconnect. - """ + """True once teardown/fatal started: delayed flushes must not dispatch onto a torn-down session. + Callers must NOT destroy the event (PTB already advanced the offset) — hold and redispatch.""" return bool(getattr(self, "_drop_delayed_deliveries", False)) def _schedule_held_inbound_redispatch(self) -> None: - """Ensure a tracked drain runs when held events exist and delivery is live. - - Triggered by ``_mark_connected``, holds created while connected (cancel-after-pop), - and the end of a drain pass with leftovers. No-op while down or after permanent fatal. - """ - if self._is_permanent_fatal(): + """Ensure a tracked drain runs when held events exist and delivery is live (no-op while + down or after permanent fatal; an in-flight drain schedules its own follow-up).""" + if self._is_permanent_fatal() or self._should_drop_delayed_delivery(): return - if self._should_drop_delayed_delivery(): - return - held = getattr(self, "_held_inbound_events", None) - if not held: + if not getattr(self, "_held_inbound_events", None): return try: loop = asyncio.get_running_loop() @@ -734,77 +544,54 @@ class TelegramAdapter(BasePlatformAdapter): current = asyncio.current_task() except RuntimeError: current = None - # Already draining on another task — that pass schedules any follow-up itself. if prior is not None and not prior.done() and prior is not current: return - self._held_inbound_redispatch_task = loop.create_task( - self._redispatch_held_inbound(prior=None if prior is current else prior) - ) + self._held_inbound_redispatch_task = loop.create_task(self._redispatch_held_inbound(prior=None if prior is current else prior)) - def _hold_inbound_event( - self, event: "MessageEvent", *, where: str, schedule: bool = True - ) -> None: - """Preserve an inbound event that cannot be dispatched right now. - - By enqueue/flush time PTB has already acked the update and advanced the offset, so - destroying the event is silent permanent loss. Hold it, redispatch from - ``_mark_connected`` (or immediately if connected). Capped, identity-deduped; - permanent fatal discards. ``schedule=False`` inside a drain (avoids poison-event loops). - """ + def _hold_inbound_event(self, event: "MessageEvent", *, where: str, schedule: bool = True) -> None: + """Preserve an inbound event that cannot be dispatched now (PTB already acked the update, so dropping is silent loss). + Capped, identity-deduped; permanent fatal discards. ``schedule=False`` inside a drain avoids poison-event loops.""" if self._is_permanent_fatal(): logger.warning( - "[Telegram] Discarding inbound under non-retryable fatal (%s, %d chars)", - where, len(getattr(event, "text", None) or ""), - ) + "[Telegram] Discarding inbound under non-retryable fatal (%s, %d chars)", where, len(getattr(event, "text", None) or "")) return held = getattr(self, "_held_inbound_events", None) if held is None: - self._held_inbound_events = [] - held = self._held_inbound_events - for existing in held: - if existing is event: - return + self._held_inbound_events = held = [] + if any(existing is event for existing in held): + return max_n = int(getattr(self, "HELD_INBOUND_MAX", 64) or 64) while len(held) >= max_n: dropped = held.pop(0) logger.warning( - "[Telegram] Held-inbound queue full (%d); dropping oldest (%d chars)", - max_n, len(getattr(dropped, "text", None) or ""), - ) + "[Telegram] Held-inbound queue full (%d); dropping oldest (%d chars)", max_n, len(getattr(dropped, "text", None) or "")) held.append(event) logger.warning( - "[Telegram] Holding inbound (%s, %d chars, queue=%d)%s", - where, len(getattr(event, "text", None) or ""), len(held), - " - will redispatch on reconnect" if self._should_drop_delayed_delivery() - else (" - scheduling redispatch" if schedule else ""), - ) + "[Telegram] Holding inbound (%s, %d chars, queue=%d)%s", where, len(getattr(event, "text", None) or ""), len(held), + " - will redispatch on reconnect" if self._should_drop_delayed_delivery() else (" - scheduling redispatch" if schedule else "")) # A live-path hold must not orphan the event waiting for a reconnect that never comes. if schedule and not self._should_drop_delayed_delivery(): self._schedule_held_inbound_redispatch() - async def _redispatch_held_inbound(self, prior: Optional[asyncio.Task] = None) -> None: - """Drain the hold queue after reconnect or a connected-path hold. + def _rehold_from(self, events: list, idx: int, where: str) -> None: + """Re-hold ``events[idx:]`` without rescheduling (drain interrupted / failed / cancelled).""" + for rest in events[idx:]: + self._hold_inbound_event(rest, where=where, schedule=False) - ``prior`` (previous redispatch task) is cancelled+awaited here so ``_mark_connected`` - stays synchronous while teardown can still cancel the single tracked task. - """ + async def _redispatch_held_inbound(self, prior: Optional[asyncio.Task] = None) -> None: + """Drain the hold queue after reconnect or a connected-path hold; ``prior`` (previous + redispatch task) is cancelled+awaited here so ``_mark_connected`` stays synchronous.""" if prior is not None and prior is not asyncio.current_task() and not prior.done(): prior.cancel() - try: + with contextlib.suppress(asyncio.CancelledError): await prior - except asyncio.CancelledError: - pass + held = getattr(self, "_held_inbound_events", None) if self._is_permanent_fatal(): - held = getattr(self, "_held_inbound_events", None) if held: n = len(held) held.clear() - logger.warning( - "[Telegram] Redispatch aborted; discarded %d held inbound under non-retryable fatal", - n, - ) + logger.warning("[Telegram] Redispatch aborted; discarded %d held inbound under non-retryable fatal", n) return - held = getattr(self, "_held_inbound_events", None) if not held: return # Take ownership atomically; concurrent holds append to the fresh list for a follow-up. @@ -815,30 +602,19 @@ class TelegramAdapter(BasePlatformAdapter): try: for idx, event in enumerate(events): if self._is_permanent_fatal() or self._should_drop_delayed_delivery(): - # Disconnect/fatal mid-drain — re-hold current + remainder. - self._hold_inbound_event(event, where="redispatch-interrupted", schedule=False) - for rest in events[idx + 1 :]: - self._hold_inbound_event( - rest, where="redispatch-interrupted", schedule=False - ) + self._rehold_from(events, idx, "redispatch-interrupted") return try: await self.handle_message(event) except asyncio.CancelledError: - self._hold_inbound_event(event, where="redispatch-cancelled", schedule=False) - for rest in events[idx + 1 :]: - self._hold_inbound_event(rest, where="redispatch-cancelled", schedule=False) + self._rehold_from(events, idx, "redispatch-cancelled") raise except Exception: - # Retryable failure: re-hold current + remainder but do NOT reschedule now — - # a poison event would tight-loop. Next mark_connected/live hold drains. + # Retryable failure: re-hold but do NOT reschedule now (a poison event would + # tight-loop); the next mark_connected/live hold drains. logger.exception( - "[Telegram] Failed to redispatch held inbound (%d chars); re-holding", - len(getattr(event, "text", None) or ""), - ) - self._hold_inbound_event(event, where="redispatch-failed", schedule=False) - for rest in events[idx + 1 :]: - self._hold_inbound_event(rest, where="redispatch-failed", schedule=False) + "[Telegram] Failed to redispatch held inbound (%d chars); re-holding", len(getattr(event, "text", None) or "")) + self._rehold_from(events, idx, "redispatch-failed") allow_followup_schedule = False return finally: @@ -847,94 +623,86 @@ class TelegramAdapter(BasePlatformAdapter): allow_followup_schedule and getattr(self, "_held_inbound_events", None) and not self._should_drop_delayed_delivery() - and not self._is_permanent_fatal() - ): + and not self._is_permanent_fatal()): self._schedule_held_inbound_redispatch() def _notification_kwargs(self, metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]: """In "important" mode return disable_notification=True unless ``metadata["notify"]``.""" - if getattr(self, "_notifications_mode", "important") != "important": - return {} - if (metadata or {}).get("notify"): + if getattr(self, "_notifications_mode", "important") != "important" or (metadata or {}).get("notify"): return {} return {"disable_notification": True} + @staticmethod + def _normalize_chat_type(chat_type: Any, *, is_forum: bool) -> str: + """Telegram chat type → gateway chat type (``private``→``dm``, ``supergroup``→forum/group).""" + normalized = str(chat_type or "dm").strip().lower() or "dm" + if normalized == "private": + return "dm" + if normalized == "supergroup": + return "forum" if is_forum else "group" + return normalized + + def _legacy_runner_auth_fn(self): + """``runner._is_user_authorized`` resolved off the bound handler (bare-adapter tests, direct + embedding); None under multiplex where the handler is a profile closure.""" + runner = getattr(getattr(self, "_message_handler", None), "__self__", None) + auth_fn = getattr(runner, "_is_user_authorized", None) + return auth_fn if callable(auth_fn) else None + + @staticmethod + def _env_allowlist_decision(user_id: str) -> Optional[bool]: + """TELEGRAM_ALLOWED_USERS decision; None when no allowlist is configured.""" + allowed_csv = _scoped_gate_env("TELEGRAM_ALLOWED_USERS").strip() + if not allowed_csv: + return None + allowed_ids = {uid.strip() for uid in allowed_csv.split(",") if uid.strip()} + return "*" in allowed_ids or user_id in allowed_ids + def _is_callback_user_authorized( - self, - user_id: str, - *, - chat_id: Optional[str] = None, - chat_type: Optional[str] = None, - thread_id: Optional[str] = None, - user_name: Optional[str] = None, - ) -> bool: + self, user_id: str, *, chat_id: Optional[str] = None, chat_type: Optional[str] = None, + thread_id: Optional[str] = None, user_name: Optional[str] = None) -> bool: """Return whether a Telegram inline-button caller may perform gated actions.""" normalized_user_id = str(user_id or "").strip() if not normalized_user_id: return False - normalized_chat_type = str(chat_type or "dm").strip().lower() or "dm" - if normalized_chat_type == "private": - normalized_chat_type = "dm" - elif normalized_chat_type == "supergroup": - normalized_chat_type = "forum" if thread_id is not None else "group" - + normalized_chat_type = self._normalize_chat_type(chat_type, is_forum=thread_id is not None) # Preferred: the auth callback GatewayRunner injects (set_authorization_check) → full - # _is_user_authorized chain. Unlike the __self__ introspection below it also works for - # a secondary multiplexed adapter whose _message_handler is a profile closure. getattr - # tolerates partially-constructed adapters (object.__new__ in tests). + # _is_user_authorized chain; also works for a multiplexed adapter whose _message_handler is a + # profile closure. getattr tolerates partially-constructed adapters (object.__new__ in tests). if getattr(self, "_authorization_check", None) is not None: injected = self._is_sender_authorized( - normalized_user_id, - chat_type=normalized_chat_type, - chat_id=str(chat_id or normalized_user_id), - thread_id=str(thread_id) if thread_id is not None else None, - ) + normalized_user_id, chat_type=normalized_chat_type, chat_id=str(chat_id or normalized_user_id), + thread_id=str(thread_id) if thread_id is not None else None) if injected is not None: return injected - - # Legacy: resolve the runner off the bound handler (bare-adapter tests, direct embedding). - runner = getattr(getattr(self, "_message_handler", None), "__self__", None) - auth_fn = getattr(runner, "_is_user_authorized", None) - if callable(auth_fn): + auth_fn = self._legacy_runner_auth_fn() + if auth_fn is not None: try: from gateway.session import SessionSource source = SessionSource( - platform=Platform.TELEGRAM, - chat_id=str(chat_id or normalized_user_id), - chat_type=normalized_chat_type, - user_id=normalized_user_id, - user_name=str(user_name).strip() if user_name else None, - thread_id=str(thread_id) if thread_id is not None else None, - ) + platform=Platform.TELEGRAM, chat_id=str(chat_id or normalized_user_id), chat_type=normalized_chat_type, + user_id=normalized_user_id, user_name=str(user_name).strip() if user_name else None, + thread_id=str(thread_id) if thread_id is not None else None) return bool(auth_fn(source)) except Exception: logger.debug( - "[Telegram] Falling back to env-only callback auth for user %s", - normalized_user_id, exc_info=True, - ) - allowed_csv = _scoped_gate_env("TELEGRAM_ALLOWED_USERS").strip() - if not allowed_csv: + "[Telegram] Falling back to env-only callback auth for user %s", normalized_user_id, exc_info=True) + decision = self._env_allowlist_decision(normalized_user_id) + if decision is None: # Fail-closed: no allowlist means deny unless GATEWAY_ALLOW_ALL_USERS is set. return _scoped_gate_env("GATEWAY_ALLOW_ALL_USERS").lower() in {"true", "1", "yes"} - allowed_ids = {uid.strip() for uid in allowed_csv.split(",") if uid.strip()} - return "*" in allowed_ids or normalized_user_id in allowed_ids + return decision def _source_from_message_for_auth(self, message: Message): - """Build the SessionSource the gateway auth path expects. - - Identity comes from ``from_user``, falling back to ``sender_chat`` for channel posts - so an unauthorized channel cannot inject content via the broadcast path. - """ + """Build the SessionSource the gateway auth path expects; identity comes from ``from_user``, + falling back to ``sender_chat`` for channel posts so an unauthorized channel can't inject.""" from gateway.session import SessionSource user = getattr(message, "from_user", None) chat = getattr(message, "chat", None) user_id = str(getattr(user, "id", "")).strip() or None # Carry is_bot so the runner's ``*_ALLOW_BOTS`` branch is reachable, as in build_source. is_bot = bool(getattr(user, "is_bot", False)) if user is not None else False - user_name = ( - str(getattr(user, "username", "") or getattr(user, "full_name", "") or "").strip() - or None - ) + user_name = str(getattr(user, "username", "") or getattr(user, "full_name", "") or "").strip() or None if not user_id: # channel post — authorize the sender chat instead sender_chat = getattr(message, "sender_chat", None) if sender_chat is not None: @@ -942,190 +710,112 @@ class TelegramAdapter(BasePlatformAdapter): if not user_name: user_name = str(getattr(sender_chat, "title", "") or "").strip() or None chat_id = str(getattr(chat, "id", "")).strip() or user_id - chat_type = str(getattr(chat, "type", "dm")).strip().lower() or "dm" - if chat_type == "private": - chat_type = "dm" - elif chat_type == "supergroup": - thread_id_raw = getattr(message, "message_thread_id", None) - is_topic_message = bool(getattr(message, "is_topic_message", False)) - is_forum_group = getattr(chat, "is_forum", False) is True - chat_type = ( - "forum" - if thread_id_raw is not None and (is_topic_message or is_forum_group) - else "group" - ) - thread_id = None thread_id_raw = getattr(message, "message_thread_id", None) - if thread_id_raw is not None: - is_topic_message = bool(getattr(message, "is_topic_message", False)) - is_forum_group = getattr(chat, "is_forum", False) is True - if (chat_type == "forum" and (is_topic_message or is_forum_group)) or ( - chat_type == "dm" and is_topic_message - ): - thread_id = str(thread_id_raw) + is_topic_message = bool(getattr(message, "is_topic_message", False)) + is_forum_group = getattr(chat, "is_forum", False) is True + chat_type = self._normalize_chat_type( + getattr(chat, "type", "dm"), is_forum=thread_id_raw is not None and (is_topic_message or is_forum_group)) + thread_id = None + if thread_id_raw is not None and ( + (chat_type == "forum" and (is_topic_message or is_forum_group)) or (chat_type == "dm" and is_topic_message)): + thread_id = str(thread_id_raw) return SessionSource( platform=Platform.TELEGRAM, chat_id=chat_id or "", chat_type=chat_type, user_id=user_id, - user_name=user_name, thread_id=thread_id, is_bot=is_bot, - ) + user_name=user_name, thread_id=thread_id, is_bot=is_bot) def _source_from_reaction_for_auth(self, update): - """Build the SessionSource for a ``message_reaction`` update's actor. + """SessionSource for a ``message_reaction`` update's actor (``user`` or ``actor_chat``). - Like ``_source_from_message_for_auth`` but reactions carry ``user`` (or ``actor_chat`` - for an anonymous admin) and ``chat``, no ``Message`` and no thread id. - - Raises ``ValueError`` when actor, chat or message identity is absent so the post-auth - boundary fails closed rather than authorizing an incomplete source. - """ + Raises ``ValueError`` when actor, chat or message identity is absent so the post-auth boundary fails closed.""" mr = getattr(update, "message_reaction", None) if mr is None: - raise ValueError( - "gateway_platform_event source extraction requires a message_reaction update" - ) + raise ValueError("gateway_platform_event source extraction requires a message_reaction update") user = getattr(mr, "user", None) or getattr(mr, "actor_chat", None) chat = getattr(mr, "chat", None) user_id = str(getattr(user, "id", "")).strip() or None - user_name = ( - str( - getattr(user, "username", "") - or getattr(user, "full_name", "") - or getattr(user, "title", "") - ).strip() - or None - ) + user_name = str(getattr(user, "username", "") or getattr(user, "full_name", "") or getattr(user, "title", "")).strip() or None chat_id = str(getattr(chat, "id", "")).strip() or None message_id = getattr(mr, "message_id", None) if not user_id or not chat_id or message_id is None or not str(message_id).strip(): - raise ValueError( - "gateway_platform_event reaction requires actor, chat, and message identities" - ) - chat_type = str(getattr(chat, "type", "dm")).strip().lower() or "dm" - if chat_type == "private": - chat_type = "dm" - elif chat_type == "supergroup": - # Reactions carry no message_thread_id; is_forum is the only forum signal. - chat_type = "forum" if getattr(chat, "is_forum", False) is True else "group" + raise ValueError("gateway_platform_event reaction requires actor, chat, and message identities") + # Reactions carry no message_thread_id; is_forum is the only forum signal. + chat_type = self._normalize_chat_type(getattr(chat, "type", "dm"), is_forum=getattr(chat, "is_forum", False) is True) return self.build_source( - chat_id=chat_id, chat_type=chat_type, user_id=user_id, user_name=user_name, - thread_id=None, message_id=str(message_id), - ) + chat_id=chat_id, chat_type=chat_type, user_id=user_id, user_name=user_name, thread_id=None, message_id=str(message_id)) def _telegram_auth_env_configured(self) -> bool: """Return True when Telegram auth env vars make an early decision safe.""" keys = ( - "TELEGRAM_ALLOWED_USERS", "TELEGRAM_GROUP_ALLOWED_USERS", - "TELEGRAM_GROUP_ALLOWED_CHATS", "TELEGRAM_ALLOW_ALL_USERS", - "GATEWAY_ALLOWED_USERS", "GATEWAY_ALLOW_ALL_USERS", - ) + "TELEGRAM_ALLOWED_USERS", "TELEGRAM_GROUP_ALLOWED_USERS", "TELEGRAM_GROUP_ALLOWED_CHATS", + "TELEGRAM_ALLOW_ALL_USERS", "GATEWAY_ALLOWED_USERS", "GATEWAY_ALLOW_ALL_USERS") return any(_scoped_gate_env(key).strip() for key in keys) def _should_pass_unauthorized_dm_for_pairing(self, source) -> bool: - """True when an unauthorized DM must still reach gateway pairing. - - Early auth must not short-circuit the pairing handshake when - ``unauthorized_dm_behavior`` resolves to ``pair`` — including an allowlist plus an - explicit platform override opting back into pairing. - """ + """True when an unauthorized DM must still reach gateway pairing (``unauthorized_dm_behavior`` + resolves to ``pair``, incl. an allowlist plus an explicit platform override).""" if source.chat_type != "dm": return False - # Bound-handler ``__self__`` is None under multiplex (profile closure); ``gateway_runner`` - # is injected on every adapter and survives that wrapping. - runner = getattr(getattr(self, "_message_handler", None), "__self__", None) or getattr( - self, "gateway_runner", None - ) + # Bound-handler ``__self__`` is None under multiplex; ``gateway_runner`` survives that wrapping. + runner = getattr(getattr(self, "_message_handler", None), "__self__", None) or getattr(self, "gateway_runner", None) behavior_fn = getattr(runner, "_get_unauthorized_dm_behavior", None) if callable(behavior_fn): try: - return ( - behavior_fn( - Platform.TELEGRAM, - profile=getattr(source, "profile", None) - or getattr(self, "_owner_profile", None), - ) - == "pair" - ) + profile = getattr(source, "profile", None) or getattr(self, "_owner_profile", None) + return behavior_fn(Platform.TELEGRAM, profile=profile) == "pair" except Exception: - logger.debug( - "[Telegram] Failed to resolve unauthorized DM behavior; " - "falling back to adapter-local override", - exc_info=True, - ) + logger.debug("[Telegram] Failed to resolve unauthorized DM behavior; falling back to adapter-local override", exc_info=True) extra = getattr(getattr(self, "config", None), "extra", None) or {} return str(extra.get("unauthorized_dm_behavior", "")).strip().lower() == "pair" def _is_user_authorized_from_message(self, message: Message) -> bool: - """Intake auth prefilter, run BEFORE text batching/event construction/group observation. + """Intake auth prefilter, run BEFORE batching/event construction/group observation. - Only rejects when it can make the same context-aware decision the runner would. - Unknown DMs pass through when there is no allowlist, or when pairing is the effective - unauthorized-DM behavior, so the pairing flow can run. - """ + Only rejects when it can make the same context-aware decision the runner would; unknown DMs pass through when + there is no allowlist or pairing is the unauthorized-DM behavior.""" source = self._source_from_message_for_auth(message) user_id = source.user_id - # No identity → group service message (pin, new_chat_members…) or channel post without - # sender_chat; nothing authorizable, defer to _should_process_message gating. + # No identity → service message or channel post without sender_chat; defer to message gating. if not user_id: return True authorized: Optional[bool] = None # Adapter-level allow_from (DMs) / group_allow_from (groups) are the sole authority if set. - chat_type = source.chat_type or "" - if chat_type in ("group", "forum", "channel"): - adapter_allow_from = self.config.extra.get("group_allow_from") - else: - adapter_allow_from = self.config.extra.get("allow_from") + adapter_allow_from = self.config.extra.get( + "group_allow_from" if (source.chat_type or "") in ("group", "forum", "channel") else "allow_from") if adapter_allow_from is not None: allowed = _coerce_allow_set(adapter_allow_from) authorized = user_id in allowed or "*" in allowed - - # Instance-level override only (tests). The class method _is_callback_user_authorized is - # for inline buttons and must not become a user-id-only shortcut for real messages. + # Instance-level override only (tests): the class method _is_callback_user_authorized is for + # inline buttons and must not become a user-id-only shortcut for real messages. if authorized is None: callback_auth = self.__dict__.get("_is_callback_user_authorized") if callable(callback_auth): - try: - authorized = bool( - callback_auth( - user_id, chat_id=source.chat_id, chat_type=source.chat_type, - thread_id=source.thread_id, user_name=source.user_name, - ) - ) - except Exception: - pass + with contextlib.suppress(Exception): + authorized = bool(callback_auth( + user_id, chat_id=source.chat_id, chat_type=source.chat_type, thread_id=source.thread_id, + user_name=source.user_name)) if authorized is None: - # Runner's full auth chain. Prefer the set_authorization_check callback: it survives - # multiplex handler wrapping, whereas bound-handler __self__ is None for a profile - # closure (which silently default-denied allowlisted group members). - runner = getattr(getattr(self, "_message_handler", None), "__self__", None) - auth_fn = getattr(runner, "_is_user_authorized", None) + # Runner's full auth chain; prefer the set_authorization_check callback (survives multiplex + # handler wrapping, unlike bound-handler __self__). + auth_fn = self._legacy_runner_auth_fn() has_callback = getattr(self, "_authorization_check", None) is not None - if has_callback or callable(auth_fn): + if has_callback or auth_fn is not None: # No allowlist → unknown DMs must reach pairing, not be default-denied here. if not self._telegram_auth_env_configured(): return True - decision = ( - self._is_sender_authorized( - user_id, chat_type=source.chat_type, chat_id=source.chat_id, - is_bot=source.is_bot, thread_id=source.thread_id, - ) - if has_callback - else None - ) + decision = self._is_sender_authorized( + user_id, chat_type=source.chat_type, chat_id=source.chat_id, is_bot=source.is_bot, + thread_id=source.thread_id) if has_callback else None if decision is not None: authorized = decision - elif callable(auth_fn): + elif auth_fn is not None: try: authorized = bool(auth_fn(source)) except Exception: - logger.debug( - "[Telegram] Falling back to env-only auth for user %s", - user_id, exc_info=True, - ) + logger.debug("[Telegram] Falling back to env-only auth for user %s", user_id, exc_info=True) if authorized is None: - allowed_csv = _scoped_gate_env("TELEGRAM_ALLOWED_USERS").strip() - if not allowed_csv: + authorized = self._env_allowlist_decision(user_id) + if authorized is None: return True - allowed_ids = {uid.strip() for uid in allowed_csv.split(",") if uid.strip()} - authorized = "*" in allowed_ids or user_id in allowed_ids if authorized: return True # Unauthorized DM the gateway would pair: forward so pairing can run. @@ -1133,38 +823,31 @@ class TelegramAdapter(BasePlatformAdapter): @classmethod def _metadata_thread_id(cls, metadata: Optional[Dict[str, Any]]) -> Optional[str]: - if not metadata: - return None - thread_id = metadata.get("thread_id") or metadata.get("message_thread_id") + thread_id = (metadata or {}).get("thread_id") or (metadata or {}).get("message_thread_id") return str(thread_id) if thread_id is not None else None @classmethod def _metadata_direct_messages_topic_id(cls, metadata: Optional[Dict[str, Any]]) -> Optional[str]: - if not metadata: - return None - topic_id = metadata.get("direct_messages_topic_id") or metadata.get("telegram_direct_messages_topic_id") + topic_id = (metadata or {}).get("direct_messages_topic_id") or (metadata or {}).get("telegram_direct_messages_topic_id") return str(topic_id) if topic_id is not None else None @classmethod def _metadata_reply_to_message_id(cls, metadata: Optional[Dict[str, Any]]) -> Optional[int]: - if not metadata: - return None - reply_to = metadata.get("telegram_reply_to_message_id") + reply_to = (metadata or {}).get("telegram_reply_to_message_id") return int(reply_to) if reply_to is not None else None + @staticmethod + def _dm_topic_fallback(metadata: Optional[Dict[str, Any]]) -> bool: + """True for Hermes private-chat topic lanes (``telegram_dm_topic_reply_fallback``).""" + return bool(metadata and metadata.get("telegram_dm_topic_reply_fallback")) + @classmethod - def _is_private_dm_topic_send( - cls, chat_id: str, thread_id: Optional[str], metadata: Optional[Dict[str, Any]] - ) -> bool: + def _is_private_dm_topic_send(cls, chat_id: str, thread_id: Optional[str], metadata: Optional[Dict[str, Any]]) -> bool: if cls._metadata_direct_messages_topic_id(metadata) is not None: - return bool( - metadata - and metadata.get("telegram_dm_topic_reply_fallback") - and cls._metadata_reply_to_message_id(metadata) is not None - ) + return cls._dm_topic_fallback(metadata) and cls._metadata_reply_to_message_id(metadata) is not None if metadata and metadata.get("telegram_dm_topic_created_for_send"): return False - return bool(thread_id and metadata and metadata.get("telegram_dm_topic_reply_fallback")) + return bool(thread_id) and cls._dm_topic_fallback(metadata) @staticmethod def _dm_topic_missing_anchor_error() -> str: @@ -1172,38 +855,25 @@ class TelegramAdapter(BasePlatformAdapter): @classmethod def _reply_to_message_id_for_send( - cls, reply_to: Optional[str], metadata: Optional[Dict[str, Any]] = None, - reply_to_mode: Optional[str] = None, - ) -> Optional[int]: + cls, reply_to: Optional[str], metadata: Optional[Dict[str, Any]] = None, reply_to_mode: Optional[str] = None) -> Optional[int]: if reply_to: return int(reply_to) - if metadata and metadata.get("telegram_dm_topic_reply_fallback"): - if reply_to_mode == "off": - return None + if cls._dm_topic_fallback(metadata) and reply_to_mode != "off": return cls._metadata_reply_to_message_id(metadata) return None @classmethod def _thread_kwargs_for_send( - cls, - chat_id: str, - thread_id: Optional[str], - metadata: Optional[Dict[str, Any]] = None, - reply_to_message_id: Optional[int] = None, - reply_to_mode: Optional[str] = None, - ) -> Dict[str, Any]: + cls, chat_id: str, thread_id: Optional[str], metadata: Optional[Dict[str, Any]] = None, + reply_to_message_id: Optional[int] = None, reply_to_mode: Optional[str] = None) -> Dict[str, Any]: """Telegram send kwargs for forum and direct-message topic routing. - Forum topics use ``message_thread_id``; native Bot API DM topics opt in via explicit - ``direct_messages_topic_id`` metadata; Hermes private-chat topic lanes are marked - ``telegram_dm_topic_reply_fallback``. Anchor-less synthetic sends (loop wakeups, - restart-resumed follow-ups) prefer the Hermes topic's ``message_thread_id`` so they stay - in the active lane — the native DM-topic id renders in a different chat lane. - ``reply_to_mode="off"`` suppresses the anchor but keeps ``message_thread_id``. - """ - if metadata and metadata.get("telegram_dm_topic_reply_fallback"): - if reply_to_mode == "off": - return {"message_thread_id": cls._message_thread_id_for_send(thread_id)} + Forum topics use ``message_thread_id``; native Bot API DM topics opt in via explicit ``direct_messages_topic_id`` + metadata; Hermes private-chat topic lanes are marked ``telegram_dm_topic_reply_fallback``. Anchor-less synthetic sends + prefer the Hermes topic's ``message_thread_id`` (the native DM-topic id renders in a different chat lane). + ``reply_to_mode="off"`` suppresses the anchor but keeps ``message_thread_id``.""" + fallback = cls._dm_topic_fallback(metadata) + if fallback and reply_to_mode != "off": if reply_to_message_id is None: reply_to_message_id = cls._metadata_reply_to_message_id(metadata) if reply_to_message_id is None: @@ -1211,32 +881,27 @@ class TelegramAdapter(BasePlatformAdapter): thread_message_id = cls._message_thread_id_for_send(thread_id) if thread_message_id is not None: return {"message_thread_id": thread_message_id} - direct_topic_id = cls._metadata_direct_messages_topic_id(metadata) - if direct_topic_id is not None: - return { - "message_thread_id": None, "direct_messages_topic_id": int(direct_topic_id) - } - return {} - return {"message_thread_id": cls._message_thread_id_for_send(thread_id)} - direct_topic_id = cls._metadata_direct_messages_topic_id(metadata) - if direct_topic_id is not None: - return {"message_thread_id": None, "direct_messages_topic_id": int(direct_topic_id)} + return cls._direct_topic_kwargs(metadata) or {} + elif not fallback: + direct_kwargs = cls._direct_topic_kwargs(metadata) + if direct_kwargs is not None: + return direct_kwargs return {"message_thread_id": cls._message_thread_id_for_send(thread_id)} - def _thread_kwargs_for_draft( - self, chat_id: str, metadata: Optional[Dict[str, Any]] - ) -> Dict[str, Any]: - """Routing kwargs for ``sendMessageDraft`` / ``sendRichMessageDraft``. + @classmethod + def _direct_topic_kwargs(cls, metadata: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]: + """Native Bot API DM-topic routing kwargs, or None when no ``direct_messages_topic_id``.""" + direct_topic_id = cls._metadata_direct_messages_topic_id(metadata) + if direct_topic_id is None: + return None + return {"message_thread_id": None, "direct_messages_topic_id": int(direct_topic_id)} - Reuses ``_thread_kwargs_for_send`` so DM topics get an integer ``message_thread_id`` — - Telegram rejects the raw string ``thread_id``, which disabled draft streaming for the turn. - """ - thread_id = self._metadata_thread_id(metadata) - reply_to_id = self._reply_to_message_id_for_send(None, metadata) + def _thread_kwargs_for_draft(self, chat_id: str, metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]: + """Routing kwargs for ``sendMessageDraft`` / ``sendRichMessageDraft`` (integer + ``message_thread_id`` for DM topics — Telegram rejects the raw string ``thread_id``).""" kwargs = self._thread_kwargs_for_send( - chat_id, thread_id, metadata, reply_to_message_id=reply_to_id, - reply_to_mode=getattr(self, "_reply_to_mode", None), - ) + chat_id, self._metadata_thread_id(metadata), metadata, reply_to_message_id=self._reply_to_message_id_for_send(None, metadata), + reply_to_mode=getattr(self, "_reply_to_mode", None)) return {k: v for k, v in kwargs.items() if v is not None} @classmethod @@ -1247,56 +912,34 @@ class TelegramAdapter(BasePlatformAdapter): @classmethod def _message_thread_id_for_typing(cls, thread_id: Optional[str]) -> Optional[int]: - # Deliberately asymmetric with _message_thread_id_for_send: sendMessage rejects - # message_thread_id=1 (forum General), but sendChatAction NEEDS it to place the typing - # bubble in General — omitting it hides the bubble entirely. - if not thread_id: - return None - return int(thread_id) + # Deliberately asymmetric with _message_thread_id_for_send: sendMessage rejects message_thread_id=1 + # (forum General), but sendChatAction NEEDS it to place the typing bubble in General. + return int(thread_id) if thread_id else None @staticmethod def _is_thread_not_found_error(error: Exception) -> bool: return "thread not found" in str(error).lower() - def _prune_stale_dm_topic_binding( - self, chat_id: Any, thread_id: Any, *, metadata: Optional[Dict[str, Any]] = None - ) -> None: - """Drop the stale ``telegram_dm_topic_bindings`` row for a topic Telegram confirmed deleted. - - Otherwise ``gateway.run._recover_telegram_topic_thread_id`` keeps steering inbound to - the dead thread. Best-effort: never raises from a send-fallback path. Rows are - namespaced by profile; under ``profile_routes`` the send's ``hermes_profile`` metadata - wins over the adapter's own stamp, falling back to ``"default"``. - """ + def _prune_stale_dm_topic_binding(self, chat_id: Any, thread_id: Any, *, metadata: Optional[Dict[str, Any]] = None) -> None: + """Drop the stale ``telegram_dm_topic_bindings`` row for a topic Telegram confirmed deleted, else + ``_recover_telegram_topic_thread_id`` keeps steering inbound to the dead thread. Best-effort. + Rows are namespaced by profile: the send's ``hermes_profile`` wins over the adapter's stamp.""" if chat_id is None or thread_id is None: return - store = getattr(self, "_session_store", None) - if store is None: - return - db = getattr(store, "_db", None) + db = getattr(getattr(self, "_session_store", None), "_db", None) if db is None or not hasattr(db, "delete_telegram_topic_binding"): return try: - profile_name = ( - (metadata or {}).get("hermes_profile") - or getattr(self, "_hermes_profile_name", None) - or "default" - ) - removed = db.delete_telegram_topic_binding( - chat_id=str(chat_id), thread_id=str(thread_id), profile_name=profile_name - ) + profile_name = (metadata or {}).get("hermes_profile") or getattr(self, "_hermes_profile_name", None) or "default" + removed = db.delete_telegram_topic_binding(chat_id=str(chat_id), thread_id=str(thread_id), profile_name=profile_name) except Exception: logger.debug( "[%s] delete_telegram_topic_binding failed for chat=%s thread=%s — skipping prune", - self.name, chat_id, thread_id, exc_info=True, - ) + self.name, chat_id, thread_id, exc_info=True) return if removed: logger.info( - "[%s] Pruned stale Telegram DM topic binding " - "chat=%s thread=%s (Bot API: thread not found)", - self.name, chat_id, thread_id, - ) + "[%s] Pruned stale Telegram DM topic binding chat=%s thread=%s (Bot API: thread not found)", self.name, chat_id, thread_id) @staticmethod def _is_bad_request_error(error: Exception) -> bool: @@ -1311,53 +954,32 @@ class TelegramAdapter(BasePlatformAdapter): @classmethod def _should_retry_without_dm_topic_reply_anchor( - cls, error: Exception, metadata: Optional[Dict[str, Any]], - reply_to_message_id: Optional[int], - ) -> bool: - """True when a DM-topic send should be retried with routing stripped. - - Cases: (1) stale anchor — reply target deleted ("message to be replied not found"); - (2) anchor-less synthetic send whose ``direct_messages_topic_id`` Bot API rejects with a - topic/thread BadRequest. Retry without routing rather than drop the message. - """ - if not (metadata and metadata.get("telegram_dm_topic_reply_fallback")): - return False - if not cls._is_bad_request_error(error): + cls, error: Exception, metadata: Optional[Dict[str, Any]], reply_to_message_id: Optional[int]) -> bool: + """True when a DM-topic send should be retried with routing stripped: (1) stale anchor — reply + target deleted; (2) anchor-less synthetic send whose ``direct_messages_topic_id`` Bot API rejects.""" + if not cls._dm_topic_fallback(metadata) or not cls._is_bad_request_error(error): return False err_lower = str(error).lower() if reply_to_message_id is not None and "message to be replied not found" in err_lower: return True - if metadata.get("direct_messages_topic_id"): # topic id rejected → plain DM send - topic_markers = ( - "direct_messages_topic", "message thread not found", "thread not found", - "topic_closed", "topic_deleted", "topic not found", - ) - if any(marker in err_lower for marker in topic_markers): - return True - return False + if not metadata.get("direct_messages_topic_id"): # topic id rejected → plain DM send + return False + topic_markers = ( + "direct_messages_topic", "message thread not found", "thread not found", "topic_closed", "topic_deleted", "topic not found") + return any(marker in err_lower for marker in topic_markers) async def _send_with_dm_topic_reply_anchor_retry( - self, - send_fn: Any, - send_kwargs: Dict[str, Any], - metadata: Optional[Dict[str, Any]], - reply_to_message_id: Optional[int], - media_label: str, - reset_media: Optional[Any] = None, - ) -> Any: + self, send_fn: Any, send_kwargs: Dict[str, Any], metadata: Optional[Dict[str, Any]], + reply_to_message_id: Optional[int], media_label: str, reset_media: Optional[Any] = None) -> Any: """Retry stale private-topic media replies once without the topic anchor.""" try: return await send_fn(**send_kwargs) except Exception as send_err: - if not self._should_retry_without_dm_topic_reply_anchor( - send_err, metadata, reply_to_message_id - ): + if not self._should_retry_without_dm_topic_reply_anchor(send_err, metadata, reply_to_message_id): raise logger.warning( - "[%s] Reply target deleted for Telegram %s, " - "retrying without reply/topic anchor: %s", - self.name, media_label, _redact_telegram_error_text(send_err), - ) + "[%s] Reply target deleted for Telegram %s, retrying without reply/topic anchor: %s", + self.name, media_label, _redact_telegram_error_text(send_err)) if reset_media is not None: reset_media() retry_kwargs = dict(send_kwargs) @@ -1379,18 +1001,13 @@ class TelegramAdapter(BasePlatformAdapter): return ( error.__class__.__name__.lower() == "conflict" or "terminated by other getupdates request" in text - or "another bot instance is running" in text - ) + or "another bot instance is running" in text) @staticmethod def _looks_like_auth_error(error: Exception) -> bool: - """True for terminal credential failures (InvalidToken, Forbidden) → retryable=False. - - Deliberately narrower than "not network error": BadRequest/RetryAfter are transient at - connect time and must keep retrying. Type-based only; never match on message text. - """ - name = error.__class__.__name__.lower() - if name in {"invalidtoken", "forbidden"}: + """True for terminal credential failures (InvalidToken, Forbidden) → retryable=False. Type-based + only, never message text; BadRequest/RetryAfter are transient at connect time.""" + if error.__class__.__name__.lower() in {"invalidtoken", "forbidden"}: return True try: from telegram.error import Forbidden, InvalidToken @@ -1407,9 +1024,7 @@ class TelegramAdapter(BasePlatformAdapter): if name in {"networkerror", "timedout", "connectionerror"}: return True try: - from telegram.error import ( - BadRequest, Forbidden, InvalidToken, NetworkError, RetryAfter, TimedOut, - ) + from telegram.error import BadRequest, Forbidden, InvalidToken, NetworkError, RetryAfter, TimedOut if isinstance(error, (BadRequest, InvalidToken, Forbidden, RetryAfter)): return False if isinstance(error, (NetworkError, TimedOut)): @@ -1419,31 +1034,28 @@ class TelegramAdapter(BasePlatformAdapter): return isinstance(error, OSError) @staticmethod - def _looks_like_connect_timeout(error: Exception) -> bool: - """True when a TimedOut wraps a ConnectTimeout: TCP never connected, so re-sending is safe. - - A plain TimedOut may have reached Telegram and must not be re-sent. - """ + def _exception_graph_matches(error: Exception, name_marker: str, *text_markers: str) -> bool: + """True when any exception in ``error``'s cause/context graph matches by class name or text.""" for cur in _iter_exception_graph(error): - name = cur.__class__.__name__.lower() text = str(cur).lower() - if "connecttimeout" in name or "connect timeout" in text or "connect timed out" in text: + if name_marker in cur.__class__.__name__.lower() or any(m in text for m in text_markers): return True return False + @classmethod + def _looks_like_connect_timeout(cls, error: Exception) -> bool: + """True when a TimedOut wraps a ConnectTimeout: TCP never connected, so re-sending is safe + (a plain TimedOut may have reached Telegram and must not be re-sent).""" + return cls._exception_graph_matches(error, "connecttimeout", "connect timeout", "connect timed out") + @staticmethod def _looks_like_pool_timeout(error: Exception) -> bool: - """True when a TimedOut wraps ``httpx.PoolTimeout``: the request never left the process. - - PTB's message says "Request was *not* sent to Telegram", so re-sending cannot duplicate - (unlike a generic TimedOut). Matches the wrapped class AND the text to survive rewording. - """ + """True when a TimedOut wraps ``httpx.PoolTimeout``: PTB says "Request was *not* sent", so + re-sending cannot duplicate. Matches class AND text to survive rewording.""" for cur in _iter_exception_graph(error): name = cur.__class__.__name__.lower() text = str(cur).lower() - if "pooltimeout" in name or "pool timeout" in text or ( - "connection pool" in text and "occupied" in text - ): + if "pooltimeout" in name or "pool timeout" in text or ("connection pool" in text and "occupied" in text): return True return False @@ -1461,9 +1073,7 @@ class TelegramAdapter(BasePlatformAdapter): return bool(value) def _coerce_float_extra( - self, key: str, default: float, *, - min_value: Optional[float] = None, max_value: Optional[float] = None, - ) -> float: + self, key: str, default: float, *, min_value: Optional[float] = None, max_value: Optional[float] = None) -> float: value = self.config.extra.get(key) if getattr(self.config, "extra", None) else None if value is None: return default @@ -1484,20 +1094,16 @@ class TelegramAdapter(BasePlatformAdapter): return {"link_preview_options": LinkPreviewOptions(is_disabled=True)} return {"disable_web_page_preview": True} - # --- Bot API 10.1 Rich Messages (sendRichMessage) --------------------------------------- - # Final/new-message replies opportunistically send RAW agent markdown so tables, task lists, - #
, math render natively; legacy MarkdownV2 send() is the fallback. Streaming edits - # stay on the MarkdownV2 edit path; finalization may re-send rich and delete the preview. + # --- Bot API 10.1 Rich Messages (sendRichMessage): final/new-message replies opportunistically send + # RAW agent markdown so tables, task lists,
, math render natively; legacy MarkdownV2 send() + # is the fallback. Streaming edits stay on the MarkdownV2 edit path. def _content_fits_rich_limits(self, content: str) -> bool: - """Pre-check the 32,768-char cap only; other rich limits (blocks, nesting, columns) - surface as BadRequest, which ``_is_rich_fallback_error`` treats as permanent.""" + """Pre-check the 32,768-char cap only; other rich limits surface as BadRequest (permanent).""" return len(content) <= self.RICH_MESSAGE_MAX_CHARS def _bot_supports_rich(self) -> bool: - """True when ``do_api_request`` is an *async* callable (real Bot or AsyncMock). - - Plain MagicMock (sync auto-child) and SimpleNamespace bots resolve False → legacy path. - """ + """True when ``do_api_request`` is an *async* callable (real Bot or AsyncMock); plain MagicMock + and SimpleNamespace bots resolve False → legacy path.""" return inspect.iscoroutinefunction(getattr(self._bot, "do_api_request", None)) _RICH_DETAILS_RE = re.compile(r"]*>.*?
", re.IGNORECASE | re.DOTALL) @@ -1505,30 +1111,16 @@ class TelegramAdapter(BasePlatformAdapter): r"(\$\$.*?\$\$|\\\[.*?\\\]|\\\(.*?\\\)|" r"\\(?:sum|frac|alpha|beta|gamma|delta|theta|lambda|mu|pi|sigma|" r"int|prod|sqrt|lim|infty|begin\{(?:equation|align|matrix|cases)\}))", - re.IGNORECASE | re.DOTALL, - ) - _RICH_CJK_RE = re.compile( - "[" - "\u3040-\u30ff" # Hiragana, Katakana - "\u3400-\u4dbf" # CJK Extension A - "\u4e00-\u9fff" # CJK Unified Ideographs - "\uac00-\ud7af" # Hangul syllables - "\uf900-\ufaff" # CJK Compatibility Ideographs - "\U00020000-\U000323af" # CJK extensions and compatibility supplement - "]" - ) + re.IGNORECASE | re.DOTALL) + # Hiragana/Katakana, CJK Ext A, CJK Unified, Hangul, CJK Compatibility, CJK ext/compat supplement. + _RICH_CJK_RE = re.compile("[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uac00-\ud7af\uf900-\ufaff\U00020000-\U000323af]") def _has_telegram_desktop_details_math_crash_shape(self, content: str) -> bool: - """True for math inside a
block — crashes Telegram Desktop 6.9.1 (tdesktop#30808). - - The Bot API accepts the payload, so we must skip rich delivery up front. - """ + """Math inside
crashes Telegram Desktop 6.9.1 (tdesktop#30808); the Bot API accepts + the payload, so rich delivery must be skipped up front.""" if not content: return False - for details_block in self._RICH_DETAILS_RE.findall(content): - if self._RICH_MATH_IN_DETAILS_RE.search(details_block): - return True - return False + return any(self._RICH_MATH_IN_DETAILS_RE.search(block) for block in self._RICH_DETAILS_RE.findall(content)) def _has_telegram_desktop_cjk_rich_garble_shape(self, content: str) -> bool: """True for CJK content: Telegram Mac/Desktop rich rendering leaves overlapping glyphs.""" @@ -1536,9 +1128,7 @@ class TelegramAdapter(BasePlatformAdapter): def _needs_rich_rendering(self, content: str) -> bool: """True for constructs MarkdownV2 degrades: pipe tables, task lists,
, block math. - - Ordinary replies stay on MarkdownV2 so clients render consistent font weight/spacing. - """ + Ordinary replies stay on MarkdownV2 so clients render consistent font weight/spacing.""" if not content: return False if any(_TABLE_SEPARATOR_RE.match(line) for line in content.splitlines()): @@ -1553,63 +1143,49 @@ class TelegramAdapter(BasePlatformAdapter): """Whether rich delivery is allowed (``rich_messages`` opt-in).""" return bool(getattr(self, "_rich_messages_enabled", True)) - def _rich_eligible(self, content: str) -> bool: - """Rich eligibility ignoring ``expect_edits``. - - ``_try_edit_rich`` needs this: a streamed preview carries ``expect_edits=True`` to stay - editable mid-stream, but the FINAL edit should still upgrade to rich. - """ + def _rich_content_ok(self, content: str) -> bool: + """Shape checks shared by rich sends and rich drafts (non-blank, no Desktop crash/garble + shapes, under the cap, async-capable bot).""" return bool( - self._rich_delivery_enabled() - and not getattr(self, "_rich_send_disabled", False) - and content - and content.strip() - and self._needs_rich_rendering(content) + content and content.strip() and not self._has_telegram_desktop_details_math_crash_shape(content) and not self._has_telegram_desktop_cjk_rich_garble_shape(content) and self._content_fits_rich_limits(content) - and self._bot_supports_rich() - ) + and self._bot_supports_rich()) + + def _rich_eligible(self, content: str) -> bool: + """Rich eligibility ignoring ``expect_edits`` (a streamed preview's FINAL edit still upgrades).""" + return bool( + self._rich_delivery_enabled() + and not getattr(self, "_rich_send_disabled", False) + and content and content.strip() + and self._needs_rich_rendering(content) + and self._rich_content_ok(content)) def _should_attempt_rich(self, content: str, metadata: Optional[Dict[str, Any]] = None) -> bool: return bool(not (metadata or {}).get("expect_edits") and self._rich_eligible(content)) - def prefers_fresh_final_streaming( - self, content: str, metadata: Optional[Dict[str, Any]] = None - ) -> bool: - """Whether to replace a streamed preview with a fresh rich final — DM topics only. - - Root DMs stay off: draft streaming has no preview message_id and an in-place rich edit - would duplicate a live draft. DM *topics* often reject sendMessageDraft and degrade to - edit-in-place, whose MarkdownV2 preview Telegram refuses to rich-edit — a fresh - sendRichMessage plus deleting the preview is the only way to keep native tables. - """ + def prefers_fresh_final_streaming(self, content: str, metadata: Optional[Dict[str, Any]] = None) -> bool: + """Replace a streamed preview with a fresh rich final — DM topics only. Root DMs stay off (a live + draft has no preview id); DM *topics* degrade to edit-in-place whose MarkdownV2 preview Telegram + refuses to rich-edit, so a fresh sendRichMessage + delete is the only way to keep native tables.""" metadata = metadata or {} - if not ( - metadata.get("telegram_dm_topic_reply_fallback") - or self._metadata_direct_messages_topic_id(metadata) - ): + if not (metadata.get("telegram_dm_topic_reply_fallback") or self._metadata_direct_messages_topic_id(metadata)): return False return self._rich_eligible(content) + def _rich_transport_available(self) -> bool: + return bool( + getattr(self, "_rich_messages_enabled", True) and not getattr(self, "_rich_send_disabled", False) and self._bot_supports_rich()) + def streaming_overflow_limit(self) -> Optional[int]: - """Let the stream consumer accumulate up to the rich cap so a reply that fits one - sendRichMessage isn't fragmented at 4,096. None (→ legacy limit) if rich is unavailable.""" - if ( - getattr(self, "_rich_messages_enabled", True) - and not getattr(self, "_rich_send_disabled", False) - and self._bot_supports_rich() - ): - return self.RICH_MESSAGE_MAX_CHARS - return None + """Let the stream consumer accumulate up to the rich cap so a reply that fits one sendRichMessage + isn't fragmented at 4,096. None (→ legacy limit) if rich is unavailable.""" + return self.RICH_MESSAGE_MAX_CHARS if self._rich_transport_available() else None - def _rich_message_payload( - self, content: str, *, skip_entity_detection: bool = False - ) -> Dict[str, Any]: - """Build the ``InputRichMessage`` from RAW markdown (single newlines → hard breaks). - - Never pass ``format_message(content)`` — MarkdownV2 escaping destroys table pipes. - """ + def _rich_message_payload(self, content: str, *, skip_entity_detection: bool = False) -> Dict[str, Any]: + """``InputRichMessage`` from RAW markdown — never ``format_message(content)``, whose MarkdownV2 + escaping destroys table pipes.""" payload: Dict[str, Any] = {"markdown": _rich_normalize_linebreaks(content)} if skip_entity_detection: payload["skip_entity_detection"] = True @@ -1617,15 +1193,10 @@ class TelegramAdapter(BasePlatformAdapter): def _is_rich_capability_error(self, exc: Exception) -> bool: """True ⇒ the rich endpoint itself is unavailable (old PTB/server); latches rich off. - - Per-message BadRequests (parser/limit) are NOT capability errors. - """ - name = exc.__class__.__name__.lower() - if name in {"endpointnotfound", "invalidtoken"}: + Per-message BadRequests (parser/limit) are NOT capability errors.""" + if exc.__class__.__name__.lower() in {"endpointnotfound", "invalidtoken"}: return True - if isinstance(exc, (AttributeError, TypeError, NotImplementedError)): - return True - if getattr(exc, "error_code", None) == 404: + if isinstance(exc, (AttributeError, TypeError, NotImplementedError)) or getattr(exc, "error_code", None) == 404: return True s = str(exc).lower() if ("method" in s or "endpoint" in s) and ("not found" in s or "does not exist" in s): @@ -1633,37 +1204,22 @@ class TelegramAdapter(BasePlatformAdapter): return "no such method" in s def _is_rich_fallback_error(self, exc: Exception) -> bool: - """True ⇒ permanent/capability error ⇒ safe to fall back to legacy. - - Conservative on purpose: anything not clearly permanent is transient — the - rich request may have reached Telegram, so a legacy resend risks a duplicate. - """ - if self._is_bad_request_error(exc): - return True - if self._is_rich_capability_error(exc): + """True ⇒ permanent/capability error ⇒ safe to fall back to legacy. Conservative: anything not + clearly permanent is transient — the rich request may have reached Telegram (duplicate risk).""" + if self._is_bad_request_error(exc) or self._is_rich_capability_error(exc): return True s = str(exc).lower() return "unsupported" in s or "not implemented" in s def _chunk_reply_routing( - self, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], - thread_id: Optional[str], index: int, - ) -> tuple: + self, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], thread_id: Optional[str], index: int) -> tuple: """Reply-anchor routing for chunk ``index``: ``(private_dm_topic_send, anchor_off, reply_to_id)``. - - ``anchor_off``: reply_to_mode="off" on the telegram_dm_topic_reply_fallback path is an - explicit opt-in to "message_thread_id alone is enough" — don't fail loud just because - the anchor was suppressed by config. - """ + ``anchor_off``: reply_to_mode="off" on the DM-topic fallback path opts into "message_thread_id + alone is enough" — don't fail loud because the anchor was suppressed by config.""" metadata_reply_to = self._metadata_reply_to_message_id(metadata) private_dm_topic_send = self._is_private_dm_topic_send(chat_id, thread_id, metadata) - dm_topic_reply_to_off = ( - private_dm_topic_send and self._reply_to_mode == "off" - and bool(metadata and metadata.get("telegram_dm_topic_reply_fallback")) - ) - reply_to_source = reply_to or ( - str(metadata_reply_to) if private_dm_topic_send and metadata_reply_to is not None else None - ) + dm_topic_reply_to_off = private_dm_topic_send and self._reply_to_mode == "off" and self._dm_topic_fallback(metadata) + reply_to_source = reply_to or (str(metadata_reply_to) if private_dm_topic_send and metadata_reply_to is not None else None) if private_dm_topic_send: should_thread = reply_to_source is not None and self._reply_to_mode != "off" else: @@ -1672,46 +1228,36 @@ class TelegramAdapter(BasePlatformAdapter): return private_dm_topic_send, dm_topic_reply_to_off, reply_to_id def _compute_single_send_routing( - self, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], - thread_id: Optional[str], - ) -> Optional[tuple]: - """Routing for a single (rich) send — mirrors send()'s index-0 block. - - Returns ``(reply_to_id, thread_kwargs)``, or ``None`` = "skip rich, let legacy - handle it" (DM-topic fail-loud case; legacy owns the refuse SendResult). - """ - private_dm_topic_send, dm_topic_reply_to_off, reply_to_id = self._chunk_reply_routing( - chat_id, reply_to, metadata, thread_id, 0 - ) + self, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], thread_id: Optional[str]) -> Optional[tuple]: + """Routing for a single (rich) send — mirrors send()'s index-0 block. Returns ``(reply_to_id, + thread_kwargs)`` or ``None`` = skip rich, legacy owns the DM-topic fail-loud SendResult.""" + private_dm_topic_send, dm_topic_reply_to_off, reply_to_id = self._chunk_reply_routing(chat_id, reply_to, metadata, thread_id, 0) thread_kwargs = self._thread_kwargs_for_send( - chat_id, thread_id, metadata, reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode - ) - # Refusing to send outside the requested DM topic — defer to legacy (canonical - # fail-loud SendResult). Synthetic/resumed sends via direct_messages_topic_id - # need no reply anchor. + chat_id, thread_id, metadata, reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode) + # Synthetic/resumed sends via direct_messages_topic_id need no reply anchor. if ( private_dm_topic_send and reply_to_id is None and not dm_topic_reply_to_off - and not thread_kwargs.get("direct_messages_topic_id") - ): + and not thread_kwargs.get("direct_messages_topic_id")): return None return reply_to_id, thread_kwargs - def _rich_transient_result(self, exc: Exception, what: str, *, retry_after: Any = None) -> SendResult: - """SendResult for a transient/unknown rich-API failure (request may have reached - Telegram, so the caller must NOT legacy-resend); retry semantics mirror legacy send().""" - err_str = str(exc).lower() + @staticmethod + def _is_timed_out(exc: Exception) -> bool: + """PTB ``TimedOut`` (when importable) or a "timed out" message.""" try: from telegram.error import TimedOut as _TimedOut except (ImportError, AttributeError): _TimedOut = None - is_timeout = (_TimedOut and isinstance(exc, _TimedOut)) or "timed out" in err_str - is_connect_timeout = self._looks_like_connect_timeout(exc) + return bool((_TimedOut and isinstance(exc, _TimedOut)) or "timed out" in str(exc).lower()) + + def _rich_transient_result(self, exc: Exception, what: str, *, retry_after: Any = None) -> SendResult: + """SendResult for a transient/unknown rich-API failure (request may have reached Telegram, so the + caller must NOT legacy-resend); retry semantics mirror legacy send().""" safe_error = _redact_telegram_error_text(exc) logger.warning("[%s] %s transient failure (no legacy resend): %s", self.name, what, safe_error) return SendResult( - success=False, error=safe_error, retryable=(is_connect_timeout or not is_timeout), - retry_after=retry_after, - ) + success=False, error=safe_error, + retryable=(self._looks_like_connect_timeout(exc) or not self._is_timed_out(exc)), retry_after=retry_after) @staticmethod def _record_rich_sent(chat_id: Any, message_id: Any, content: str) -> None: @@ -1723,46 +1269,27 @@ class TelegramAdapter(BasePlatformAdapter): pass async def _try_send_rich( - self, chat_id: str, content: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]] - ) -> Optional[SendResult]: - """Attempt a single ``sendRichMessage`` send. - - Returns a SendResult (success, or a transient failure the caller must NOT - legacy-resend), or ``None`` = fall back to legacy MarkdownV2 (permanent/capability - error or DM-topic skip). - """ + self, chat_id: str, content: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]]) -> Optional[SendResult]: + """Attempt a single ``sendRichMessage``. Returns a SendResult (success, or a transient failure the + caller must NOT legacy-resend), or ``None`` = fall back to legacy MarkdownV2.""" thread_id = self._metadata_thread_id(metadata) routing = self._compute_single_send_routing(chat_id, reply_to, metadata, thread_id) if routing is None: return None reply_to_id, thread_kwargs = routing - payload: Dict[str, Any] = { - "chat_id": normalize_telegram_chat_id(chat_id), - "rich_message": self._rich_message_payload(content), - } - # Only forward non-None routing keys: direct_messages_topic_id comes paired - # with message_thread_id=None, which must not hit the raw endpoint. + payload = self._rich_payload_base(chat_id, content) + # Only non-None routing keys: direct_messages_topic_id is paired with message_thread_id=None. payload.update({k: v for k, v in thread_kwargs.items() if v is not None}) payload.update(self._notification_kwargs(metadata)) - if getattr(self, "_disable_link_previews", False): - payload["link_preview_options"] = {"is_disabled": True} if reply_to_id is not None: - # sendRichMessage takes reply_parameters, NOT the legacy reply_to_message_id - # scalar; the Bot API silently ignores unknown params, dropping the anchor. + # sendRichMessage takes reply_parameters, NOT reply_to_message_id (silently ignored → anchor dropped). payload["reply_parameters"] = {"message_id": reply_to_id} try: - # Raw Bot API result: return_type=Message would make PTB deserialize a 10.1 - # shape it doesn't fully model; a post-delivery parse error ≠ send failure. + # Raw Bot API result: return_type=Message would make PTB deserialize a 10.1 shape it doesn't + # fully model; a post-delivery parse error ≠ send failure. msg = await self._bot.do_api_request("sendRichMessage", api_kwargs=payload) except Exception as exc: - if self._is_rich_fallback_error(exc): - if self._is_rich_capability_error(exc): - # Endpoint missing — latch rich off to avoid a doomed roundtrip per send. - self._rich_send_disabled = True - logger.debug( - "[%s] sendRichMessage rejected (%s) — falling back to MarkdownV2", - self.name, _redact_telegram_error_text(exc), - ) + if self._rich_rejected(exc, "sendRichMessage", "MarkdownV2"): return None # Honor Telegram's flood-control retry_after over the base retry schedule. _retry_after = getattr(exc, "retry_after", None) @@ -1771,7 +1298,6 @@ class TelegramAdapter(BasePlatformAdapter): if _m: _retry_after = float(_m.group(1)) return self._rich_transient_result(exc, "sendRichMessage", retry_after=_retry_after) - message_id = None if isinstance(msg, dict): message_id = msg.get("message_id") if message_id is None: @@ -1782,42 +1308,38 @@ class TelegramAdapter(BasePlatformAdapter): self._record_rich_sent(chat_id, message_id, content) return SendResult(success=True, message_id=str(message_id) if message_id is not None else None) - async def _try_edit_rich( - self, chat_id: str, message_id: str, content: str, metadata: Optional[Dict[str, Any]] = None - ) -> Optional[SendResult]: - """Edit a message in place as rich (``editMessageText`` + ``rich_message``). - - Lets a streamed preview finalize as rich without send+delete. Same error - contract as :meth:`_try_send_rich`: success → SendResult(True); permanent/ - capability → ``None`` (legacy edit; capability latches rich off); transient → - SendResult(False) with retry semantics (may already be edited; no legacy resend). - """ - payload: Dict[str, Any] = { - "chat_id": normalize_telegram_chat_id(chat_id), - "message_id": int(message_id), - "rich_message": self._rich_message_payload(content), - } - # No topic routing on edits: message_thread_id/direct_messages_topic_id make - # Telegram reject the rich edit and force the legacy table-to-bullets fallback. + def _rich_payload_base(self, chat_id: str, content: str) -> Dict[str, Any]: + payload: Dict[str, Any] = {"chat_id": normalize_telegram_chat_id(chat_id), "rich_message": self._rich_message_payload(content)} if getattr(self, "_disable_link_previews", False): payload["link_preview_options"] = {"is_disabled": True} + return payload + + def _rich_rejected(self, exc: Exception, what: str, fallback: str) -> bool: + """True for a permanent/capability rich-API failure (caller falls back to legacy); capability + errors latch rich off so no doomed roundtrip repeats per send.""" + if not self._is_rich_fallback_error(exc): + return False + if self._is_rich_capability_error(exc): + self._rich_send_disabled = True + logger.debug("[%s] %s rejected (%s) — falling back to %s", self.name, what, _redact_telegram_error_text(exc), fallback) + return True + + async def _try_edit_rich( + self, chat_id: str, message_id: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> Optional[SendResult]: + """Edit a message in place as rich (``editMessageText`` + ``rich_message``) so a streamed preview + finalizes without send+delete. Same contract as :meth:`_try_send_rich`.""" + # No topic routing on edits: message_thread_id/direct_messages_topic_id make Telegram reject it. + payload = {**self._rich_payload_base(chat_id, content), "message_id": int(message_id)} try: - # Raw result; no return_type=Message (see _try_send_rich). await self._bot.do_api_request("editMessageText", api_kwargs=payload) except Exception as exc: - if self._is_rich_fallback_error(exc): - if self._is_rich_capability_error(exc): - self._rich_send_disabled = True - # "Message is not modified" = successful no-op; skip the redundant legacy edit. - if "not modified" in str(exc).lower(): - return SendResult(success=True, message_id=message_id) - logger.debug( - "[%s] rich editMessageText rejected (%s) — falling back to MarkdownV2 edit", - self.name, _redact_telegram_error_text(exc), - ) - return None + # "Message is not modified" = successful no-op; skip the redundant legacy edit. if "not modified" in str(exc).lower(): + if self._is_rich_fallback_error(exc) and self._is_rich_capability_error(exc): + self._rich_send_disabled = True return SendResult(success=True, message_id=message_id) + if self._rich_rejected(exc, "rich editMessageText", "MarkdownV2 edit"): + return None return self._rich_transient_result(exc, "rich editMessageText") # Mirror the fresh-send index: a streamed final finalized via edit is otherwise never recorded. self._record_rich_sent(chat_id, message_id, content) @@ -1829,124 +1351,82 @@ class TelegramAdapter(BasePlatformAdapter): and getattr(self, "_rich_drafts_enabled", False) and not getattr(self, "_rich_send_disabled", False) and not getattr(self, "_rich_draft_disabled", False) - and content and content.strip() - and not self._has_telegram_desktop_details_math_crash_shape(content) - and not self._has_telegram_desktop_cjk_rich_garble_shape(content) - and self._content_fits_rich_limits(content) - and self._bot_supports_rich() - ) + and self._rich_content_ok(content)) - async def _try_send_rich_draft( - self, chat_id: str, draft_id: int, content: str, metadata: Optional[Dict[str, Any]] - ) -> bool: - """Emit one ``sendRichMessageDraft`` preview frame; True on success. - - Draft frames are ephemeral (overwritten by the next frame / final send), so a - lost or duplicate frame is harmless: any failure returns False and the caller - renders the legacy draft. Capability failures latch ``_rich_draft_disabled``. - """ + async def _try_send_rich_draft(self, chat_id: str, draft_id: int, content: str, metadata: Optional[Dict[str, Any]]) -> bool: + """Emit one ``sendRichMessageDraft`` frame; True on success. Frames are ephemeral, so any failure + returns False and the caller renders the legacy draft; capability failures latch off.""" payload: Dict[str, Any] = { - "chat_id": normalize_telegram_chat_id(chat_id), - "draft_id": int(draft_id), - "rich_message": self._rich_message_payload(content), - } + "chat_id": normalize_telegram_chat_id(chat_id), "draft_id": int(draft_id), "rich_message": self._rich_message_payload(content)} payload.update(self._thread_kwargs_for_draft(chat_id, metadata)) try: - ok = await self._bot.do_api_request("sendRichMessageDraft", api_kwargs=payload) - return bool(ok) + return bool(await self._bot.do_api_request("sendRichMessageDraft", api_kwargs=payload)) except Exception as exc: if self._is_rich_capability_error(exc): self._rich_draft_disabled = True logger.debug( - "[%s] sendRichMessageDraft unsupported (%s) — using legacy drafts", - self.name, _redact_telegram_error_text(exc), - ) + "[%s] sendRichMessageDraft unsupported (%s) — using legacy drafts", self.name, _redact_telegram_error_text(exc)) else: logger.debug( - "[%s] sendRichMessageDraft transient failure (%s) — legacy draft this frame", - self.name, _redact_telegram_error_text(exc), - ) + "[%s] sendRichMessageDraft transient failure (%s) — legacy draft this frame", self.name, + _redact_telegram_error_text(exc)) return False async def _drain_polling_connections(self) -> None: """Reset the httpx pool used for getUpdates polling before a reconnect. - Network errors (esp. via proxies like sing-box) leave half-closed httpx - connections occupying pool slots until ``Pool timeout: All connections in the - connection pool are occupied.`` Only ``_request[0]`` (getUpdates) is reset; - the general request (``_request[1]``) stays untouched so concurrent sends/edits - are never interrupted. Relies on PTB 22.x's private ``(get_updates, general)`` - tuple — review on PTB 23+. - """ + Half-closed connections (esp. via proxies) occupy pool slots until "Pool timeout: All connections in the connection pool + are occupied". Only ``_request[0]`` (getUpdates) is reset; the general request stays untouched so concurrent sends are + never interrupted. Relies on PTB 22.x's private ``(get_updates, general)`` tuple — review on PTB 23+.""" if not (self._app and self._app.bot): return try: polling_req = self._app.bot._request[0] # noqa: SLF001 except Exception: return - shutdown_ok = False - try: - # Bounded: a wedged CLOSE-WAIT socket can hang this close forever and freeze - # the reconnect ladder. Wall-clock thread deadline, not asyncio.wait_for: - # httpcore's pool close runs under AsyncShieldCancellation and wedges wait_for. - await _await_with_thread_deadline(polling_req.shutdown(), timeout=_DRAIN_TIMEOUT) - shutdown_ok = True - except Exception: - logger.debug( - "[%s] Polling request shutdown failed/timed out (non-fatal)", self.name, exc_info=True - ) - if not shutdown_ok: - # initialize() only rebuilds the client when ``client.is_closed``; an abandoned - # aclose() leaves it false, so start_polling would reuse the CLOSE-WAIT socket - # (alive but deaf). Swap in a fresh client first. + # Bounded wall-clock deadline (not asyncio.wait_for): httpcore's pool close runs under + # AsyncShieldCancellation and a wedged CLOSE-WAIT socket can hang it forever. + if not await self._bounded_request_step(polling_req.shutdown(), "Polling request shutdown failed/timed out (non-fatal)"): + # initialize() only rebuilds the client when ``client.is_closed``; an abandoned aclose() + # leaves it false, so start_polling would reuse the CLOSE-WAIT socket (alive but deaf). self._orphan_and_rebuild_polling_client(polling_req) - try: - await _await_with_thread_deadline(polling_req.initialize(), timeout=_DRAIN_TIMEOUT) + if await self._bounded_request_step(polling_req.initialize(), "Polling request re-initialize failed/timed out (non-fatal)"): logger.debug("[%s] Polling request pool drained before reconnect", self.name) - except Exception: - logger.debug( - "[%s] Polling request re-initialize failed/timed out (non-fatal)", self.name, exc_info=True - ) + else: self._orphan_and_rebuild_polling_client(polling_req) + async def _bounded_request_step(self, awaitable, failure_msg: str) -> bool: + """Await a request shutdown()/initialize() under ``_DRAIN_TIMEOUT``; False (debug-logged) on failure.""" + try: + await _await_with_thread_deadline(awaitable, timeout=_DRAIN_TIMEOUT) + return True + except Exception: + logger.debug("[%s] " + failure_msg, self.name, exc_info=True) + return False + def _orphan_and_rebuild_polling_client(self, polling_req) -> None: - """Replace a wedged HTTPXRequest client after a hung aclose(). - - ``initialize()`` only calls ``_build_client()`` when the client reports - ``is_closed``; after an abandoned shutdown() that flag stays false and polling - would reuse the dead connection. Swap in a fresh client and close the old one - in a detached, bounded background task so it can't block the reconnect ladder. - """ + """Replace a wedged HTTPXRequest client after a hung aclose(): swap in a fresh client and close + the old one in a detached, bounded task so it can't block the reconnect ladder.""" old = getattr(polling_req, "_client", None) build = getattr(polling_req, "_build_client", None) - if old is None or not callable(build): - return - if getattr(old, "is_closed", True): + if old is None or not callable(build) or getattr(old, "is_closed", True): return try: polling_req._client = build() # noqa: SLF001 except Exception: - logger.debug( - "[%s] Failed to rebuild polling HTTP client after hung drain", self.name, exc_info=True - ) + logger.debug("[%s] Failed to rebuild polling HTTP client after hung drain", self.name, exc_info=True) return - logger.warning( - "[%s] Replaced wedged getUpdates HTTP client after drain timeout (likely CLOSE-WAIT socket)", - self.name, - ) + logger.warning("[%s] Replaced wedged getUpdates HTTP client after drain timeout (likely CLOSE-WAIT socket)", self.name) async def _orphan_aclose() -> None: try: aclose = getattr(old, "aclose", None) if not callable(aclose): return - # Same cancellation-swallowing httpcore scope as shutdown(): wall-clock - # deadline so this cleanup can't hang and leak one task per reconnect. + # Same cancellation-swallowing httpcore scope as shutdown(): wall-clock deadline. await _await_with_thread_deadline(aclose(), timeout=_DRAIN_TIMEOUT) except Exception: - logger.debug( - "[%s] Orphan polling client aclose failed (non-fatal)", self.name, exc_info=True - ) + logger.debug("[%s] Orphan polling client aclose failed (non-fatal)", self.name, exc_info=True) try: task = asyncio.ensure_future(_orphan_aclose()) @@ -1956,15 +1436,18 @@ class TelegramAdapter(BasePlatformAdapter): except Exception: pass + def _fence_polling(self) -> None: + """Mark polling closed: no progress accepted, send path degraded.""" + self._polling_progress_accepting = False + self._send_path_degraded = True + def _begin_polling_generation(self) -> tuple[int, asyncio.Event]: """Start accepting progress for a new getUpdates polling generation.""" if self._teardown_started: - self._polling_progress_accepting = False - self._send_path_degraded = True + self._fence_polling() progress = getattr(self, "_polling_progress_event", None) if progress is None: - progress = asyncio.Event() - self._polling_progress_event = progress + progress = self._polling_progress_event = asyncio.Event() return getattr(self, "_polling_generation", 0), progress verifier = getattr(self, "_polling_progress_verifier_task", None) if verifier is not None and not verifier.done(): @@ -1981,19 +1464,11 @@ class TelegramAdapter(BasePlatformAdapter): def _record_polling_progress(self, generation: int) -> None: """Record successful getUpdates I/O for the current generation only.""" - if self._teardown_started: - return - if not self._polling_progress_accepting: - return - if generation != self._polling_generation: + if self._teardown_started or not self._polling_progress_accepting or generation != self._polling_generation: return if not self._polling_progress_event.is_set(): - # First confirmed round-trip resolves the "health pending" log line both - # reconnect paths end on; otherwise "healthy" and "hung" log identically. - logger.info( - "[%s] Telegram polling confirmed healthy: getUpdates progressing (generation %d)", - self.name, generation, - ) + # First confirmed round-trip resolves the "health pending" line both reconnect paths end on. + logger.info("[%s] Telegram polling confirmed healthy: getUpdates progressing (generation %d)", self.name, generation) self._polling_progress_event.set() self._polling_last_progress_monotonic = time.monotonic() self._polling_network_error_count = 0 @@ -2004,17 +1479,13 @@ class TelegramAdapter(BasePlatformAdapter): self._send_path_degraded = False def _observe_polling_request_result(self, request, generation, result): - """Record getUpdates progress from an observed do_request result. - - Purely observational: PTB still parses the untouched payload and owns any - resulting exception. Separate method so it is shared and testable. - """ + """Record getUpdates progress from an observed do_request result (purely observational: PTB still + parses the untouched payload and owns any resulting exception).""" status_code, payload = result if generation is None or not (200 <= status_code < 300): return try: - # The request's own parser keeps health observation in agreement with PTB - # (UTF-8 replacement decoding, BOM rejection). + # The request's own parser keeps health observation in agreement with PTB. envelope = request.parse_json_payload(payload) except Exception: return @@ -2024,15 +1495,11 @@ class TelegramAdapter(BasePlatformAdapter): def _instrument_polling_request(self, request): """Instrument one dedicated PTB getUpdates request with progress tracking. - PTB request classes use ``__slots__`` and on Python 3.13 have no ``__dict__``, - so ``request.do_request = wrapper`` raises AttributeError. Instead re-tag the - instance to a thin ``__slots__ = ()`` subclass overriding ``do_request`` — - identical layout makes the ``__class__`` swap legal; works for test doubles too. - """ + PTB request classes use ``__slots__`` (no ``__dict__`` on 3.13), so re-tag the instance to a thin ``__slots__ = ()`` + subclass overriding ``do_request`` — identical layout makes the ``__class__`` swap legal; works for test doubles too.""" adapter = self - base_cls = type(request) - class _InstrumentedPollingRequest(base_cls): + class _InstrumentedPollingRequest(type(request)): __slots__ = () async def do_request(self, *args, **kwargs): @@ -2045,15 +1512,10 @@ class TelegramAdapter(BasePlatformAdapter): return request async def _start_polling_once( - self, app, *, drop_pending_updates: bool, error_callback, - abandon_app_on_timeout: bool = False, schedule_verifier: bool = True, - ) -> tuple[int, asyncio.Event]: - """Start one generation and verify real getUpdates progress. - - Returns this generation's ``(generation, progress_event)`` so readiness-gating - callers bind to exactly it — a concurrent recovery task may already have - replaced ``self._polling_progress_event`` with a newer generation's event. - """ + self, app, *, drop_pending_updates: bool, error_callback, abandon_app_on_timeout: bool = False, + schedule_verifier: bool = True) -> tuple[int, asyncio.Event]: + """Start one generation and verify real getUpdates progress. Returns this generation's + ``(generation, progress_event)`` so readiness-gating callers bind to exactly it.""" if self._teardown_started: raise _PollingLifecycleAbort("Telegram polling teardown started") generation, progress = self._begin_polling_generation() @@ -2061,37 +1523,27 @@ class TelegramAdapter(BasePlatformAdapter): raise _PollingLifecycleAbort("Telegram polling teardown started") def _generation_error_callback(error: Exception) -> None: - if self._teardown_started: + if self._teardown_started or generation != self._polling_generation or error_callback is None: return - if generation != self._polling_generation: - return - if error_callback is not None: - callback_context_token = _POLLING_GENERATION_CONTEXT.set(None) - try: - error_callback(error) - finally: - _POLLING_GENERATION_CONTEXT.reset(callback_context_token) + callback_context_token = _POLLING_GENERATION_CONTEXT.set(None) + try: + error_callback(error) + finally: + _POLLING_GENERATION_CONTEXT.reset(callback_context_token) context_token = _POLLING_GENERATION_CONTEXT.set(generation) try: - # asyncio.wait_for can wait forever on httpcore/AnyIO shielded scopes; use the - # wall-deadline helper and abandon the partial updater (caller rebuilds). + # asyncio.wait_for can wait forever on httpcore/AnyIO shielded scopes; use the wall-deadline + # helper and abandon the partial updater (caller rebuilds). await _await_with_thread_deadline( app.updater.start_polling( - allowed_updates=Update.ALL_TYPES, - drop_pending_updates=drop_pending_updates, - error_callback=_generation_error_callback, - ), + allowed_updates=Update.ALL_TYPES, drop_pending_updates=drop_pending_updates, error_callback=_generation_error_callback), timeout=_UPDATER_START_TIMEOUT, - on_abandon=( - (lambda app=app: _shutdown_abandoned_app(app)) if abandon_app_on_timeout else None - ), - ) + on_abandon=((lambda app=app: _shutdown_abandoned_app(app)) if abandon_app_on_timeout else None)) finally: _POLLING_GENERATION_CONTEXT.reset(context_token) if self._teardown_started: - self._polling_progress_accepting = False - self._send_path_degraded = True + self._fence_polling() raise _PollingLifecycleAbort("Telegram polling teardown started") if schedule_verifier: self._schedule_polling_progress_verifier(generation, progress) @@ -2100,15 +1552,12 @@ class TelegramAdapter(BasePlatformAdapter): def _schedule_polling_progress_verifier(self, generation: int, progress: asyncio.Event) -> None: """Own exactly one tracked verifier for the current generation.""" if self._teardown_started: - self._polling_progress_accepting = False - self._send_path_degraded = True + self._fence_polling() return previous = getattr(self, "_polling_progress_verifier_task", None) if previous is not None and not previous.done(): previous.cancel() - task = asyncio.get_running_loop().create_task( - self._verify_polling_after_reconnect(generation, progress) - ) + task = asyncio.get_running_loop().create_task(self._verify_polling_after_reconnect(generation, progress)) self._polling_progress_verifier_task = task self._background_tasks.add(task) @@ -2122,16 +1571,12 @@ class TelegramAdapter(BasePlatformAdapter): def _get_general_request_drain_lock(self) -> asyncio.Lock: lock = getattr(self, "_general_request_drain_lock", None) if lock is None: - lock = asyncio.Lock() - self._general_request_drain_lock = lock + lock = self._general_request_drain_lock = asyncio.Lock() return lock async def _drain_general_connections_after_pool_timeout(self) -> None: - """Reset the general Bot API pool (``_request[1]``) after a confirmed send pool timeout. - - When httpx reports pool exhaustion PTB guarantees the request was not sent, so - resetting the wedged pool before retrying is safe. - """ + """Reset the general Bot API pool (``_request[1]``) after a confirmed send pool timeout — PTB + guarantees the request was not sent, so resetting before retrying is safe.""" bot = getattr(getattr(self, "_app", None), "bot", None) if bot is None: bot = getattr(self, "_bot", None) @@ -2142,21 +1587,11 @@ class TelegramAdapter(BasePlatformAdapter): except Exception: return async with self._get_general_request_drain_lock(): - try: - await _await_with_thread_deadline(general_req.shutdown(), timeout=_DRAIN_TIMEOUT) - except Exception: - logger.debug( - "[%s] General request shutdown failed/timed out after pool timeout (non-fatal)", - self.name, exc_info=True, - ) - try: - await _await_with_thread_deadline(general_req.initialize(), timeout=_DRAIN_TIMEOUT) + await self._bounded_request_step( + general_req.shutdown(), "General request shutdown failed/timed out after pool timeout (non-fatal)") + if await self._bounded_request_step( + general_req.initialize(), "General request re-initialize failed/timed out after pool timeout (non-fatal)"): logger.warning("[%s] General request pool drained after Telegram pool timeout", self.name) - except Exception: - logger.debug( - "[%s] General request re-initialize failed/timed out after pool timeout (non-fatal)", - self.name, exc_info=True, - ) def _spawn_polling_recovery(self, loop, coro) -> None: """Start ``coro`` as the tracked in-flight recovery task (reentrancy guard).""" @@ -2164,77 +1599,84 @@ class TelegramAdapter(BasePlatformAdapter): self._background_tasks.add(self._polling_error_task) self._polling_error_task.add_done_callback(self._background_tasks.discard) - def _schedule_polling_recovery(self, error: Exception, *, reason: str) -> None: - """Schedule background polling recovery without failing gateway startup. + def _recovery_in_flight(self) -> bool: + return bool(self._polling_error_task and not self._polling_error_task.done()) - A transient bootstrap failure (deleteWebhook / initial start_polling) degrades - only this adapter; the reconnect ladder recovers in the background. - """ - if self._teardown_started: + def _schedule_polling_recovery(self, error: Exception, *, reason: str) -> None: + """Schedule background polling recovery without failing gateway startup: a transient bootstrap + failure degrades only this adapter; the reconnect ladder recovers in the background.""" + if self._teardown_started or self.has_fatal_error: return - if self.has_fatal_error: - return - if self._polling_error_task and not self._polling_error_task.done(): + if self._recovery_in_flight(): logger.debug( - "[%s] Telegram polling recovery already scheduled; ignoring %s: %s", - self.name, reason, _redact_telegram_error_text(error), - ) + "[%s] Telegram polling recovery already scheduled; ignoring %s: %s", self.name, reason, _redact_telegram_error_text(error)) return self._send_path_degraded = True logger.warning( - "[%s] Telegram polling degraded (%s); gateway stays alive and will retry. Error: %s", - self.name, reason, _redact_telegram_error_text(error), - ) + "[%s] Telegram polling degraded (%s); gateway stays alive and will retry. Error: %s", self.name, reason, + _redact_telegram_error_text(error)) self._spawn_polling_recovery(asyncio.get_running_loop(), self._handle_polling_network_error(error)) async def _delete_webhook_best_effort(self, *, require_success: bool = False) -> bool: - """Clear a stale webhook; ``require_success`` fails closed on cold start. - - Reconnects recover transient errors in background; cold start raises so - GatewayRunner disposes the partial adapter and retries with a fresh Application. - """ + """Clear a stale webhook; ``require_success`` (cold start) raises so GatewayRunner disposes the + partial adapter, while reconnects recover transient errors in background.""" if not self._bot: return False delete_webhook = getattr(self._bot, "delete_webhook", None) if not callable(delete_webhook): return True try: - # Same shielded-cancellation class as initialize/start_polling: never let a - # wedged deleteWebhook pin initial connect. - await _await_with_thread_deadline( - delete_webhook(drop_pending_updates=False), timeout=_UPDATER_START_TIMEOUT - ) + # Same shielded-cancellation class as initialize/start_polling: never let it pin connect. + await _await_with_thread_deadline(delete_webhook(drop_pending_updates=False), timeout=_UPDATER_START_TIMEOUT) return True except Exception as err: - if self._looks_like_network_error(err): - if require_success: - raise OSError("Telegram deleteWebhook did not complete during initial connect") from err - logger.warning( - "[%s] deleteWebhook failed with a recoverable network error; " - "continuing to polling so getUpdates/retry can recover: %s", - self.name, _redact_telegram_error_text(err), - ) - self._send_path_degraded = True - return False - raise + if not self._looks_like_network_error(err): + raise + if require_success: + raise OSError("Telegram deleteWebhook did not complete during initial connect") from err + logger.warning( + "[%s] deleteWebhook failed with a recoverable network error; continuing to polling so getUpdates/retry can recover: %s", + self.name, _redact_telegram_error_text(err)) + self._send_path_degraded = True + return False - async def _start_polling_resilient( - self, *, drop_pending_updates: bool, error_callback, require_progress: bool = False - ) -> bool: - """Start PTB polling; ``require_progress`` (initial connect) demands real readiness. + async def _await_cold_start_readiness(self, progress: asyncio.Event, strict_error_event: asyncio.Event, strict_error: list) -> None: + """Cold start: wait for THIS generation's first getUpdates success or the first polling error; + raises OSError so GatewayRunner disposes the partial adapter and retries fresh.""" + progress_wait = asyncio.ensure_future(progress.wait()) + error_wait = asyncio.ensure_future(strict_error_event.wait()) + try: + # Losers are NOT cancelled here; the finally below does it. + await _await_with_thread_deadline( + asyncio.wait({progress_wait, error_wait}, return_when=asyncio.FIRST_COMPLETED), timeout=_INITIAL_POLLING_PROGRESS_TIMEOUT) + except asyncio.TimeoutError as exc: + raise OSError( + "Telegram getUpdates made no progress within " + f"{_INITIAL_POLLING_PROGRESS_TIMEOUT:.0f}s during initial " + "connect — failing startup so the gateway retries with a fresh adapter (#67498)" + ) from exc + finally: + for fut in (progress_wait, error_wait): + if not fut.done(): + fut.cancel() + await asyncio.gather(progress_wait, error_wait, return_exceptions=True) + if strict_error and not progress.is_set(): + raise OSError( + "Telegram polling errored before first getUpdates success during initial connect: " + f"{_redact_telegram_error_text(strict_error[0])}" + ) from strict_error[0] + if not progress.is_set(): + raise OSError("Telegram getUpdates did not become ready during initial connect") - Reconnects may recover in background. On cold start a bootstrap failure or a - missing first getUpdates success raises so GatewayRunner disposes this partial - adapter and retries with a fresh PTB Application. - """ + async def _start_polling_resilient(self, *, drop_pending_updates: bool, error_callback, require_progress: bool = False) -> bool: + """Start PTB polling; ``require_progress`` (initial connect) demands real readiness. Reconnects + may recover in background; on cold start a bootstrap failure raises (see _await_cold_start_readiness).""" if self._teardown_started: return False if not (self._app and self._app.updater): raise RuntimeError("Telegram application/updater not initialized") - # Strict cold start: background recovery must not run while the readiness gate - # waits, else a G1 error starts G2 on the same partial app — the cold connect - # times out on G1 despite G2 succeeding, or G2 "heals" the partial app so - # GatewayRunner never disposes it. Capture the first error and fail immediately. + # Strict cold start: background recovery must not run while the readiness gate waits, else a G1 + # error starts G2 on the same partial app and GatewayRunner never disposes it. strict_error: list[BaseException] = [] strict_error_event = asyncio.Event() strict_gate_open = True @@ -2243,8 +1685,7 @@ class TelegramAdapter(BasePlatformAdapter): loop = asyncio.get_running_loop() def _strict_error_callback(error: Exception) -> None: - # Registered for the whole generation: once the gate closes, delegate to - # the real callback so later errors still reach background recovery. + # Once the gate closes, delegate so later errors still reach background recovery. if not strict_gate_open: if error_callback is not None: error_callback(error) @@ -2256,44 +1697,15 @@ class TelegramAdapter(BasePlatformAdapter): effective_callback = _strict_error_callback try: - # Same watchdog bound as the reconnect ladders: a wedged pool can hang - # start_polling() at bootstrap too. The TimeoutError is an OSError subclass, - # so the except below classifies it as a network error → background recovery. + # Same watchdog bound as the reconnect ladders; the TimeoutError is an OSError subclass, so + # the except below classifies it as a network error → background recovery. generation, progress = await self._start_polling_once( self._app, drop_pending_updates=drop_pending_updates, error_callback=effective_callback, abandon_app_on_timeout=require_progress, # The strict gate IS the cold-start verifier; a background one would race it. - schedule_verifier=not require_progress, - ) + schedule_verifier=not require_progress) if require_progress: - # Bind to THIS generation's event, not self._polling_progress_event. - progress_wait = asyncio.ensure_future(progress.wait()) - error_wait = asyncio.ensure_future(strict_error_event.wait()) - try: - await _await_with_thread_deadline( - _first_completed(progress_wait, error_wait), - timeout=_INITIAL_POLLING_PROGRESS_TIMEOUT, - ) - except asyncio.TimeoutError as exc: - raise OSError( - "Telegram getUpdates made no progress within " - f"{_INITIAL_POLLING_PROGRESS_TIMEOUT:.0f}s during initial " - "connect — failing startup so the gateway retries with a " - "fresh adapter (#67498)" - ) from exc - finally: - for fut in (progress_wait, error_wait): - if not fut.done(): - fut.cancel() - await asyncio.gather(progress_wait, error_wait, return_exceptions=True) - if strict_error and not progress.is_set(): - raise OSError( - "Telegram polling errored before first getUpdates " - "success during initial connect: " - f"{_redact_telegram_error_text(strict_error[0])}" - ) from strict_error[0] - if not progress.is_set(): - raise OSError("Telegram getUpdates did not become ready during initial connect") + await self._await_cold_start_readiness(progress, strict_error_event, strict_error) # Readiness proven — close the gate so later errors reach background recovery. strict_gate_open = False self._polling_error_callback_ref = error_callback @@ -2307,10 +1719,8 @@ class TelegramAdapter(BasePlatformAdapter): raise if self._looks_like_polling_conflict(err): logger.warning( - "[%s] Telegram polling bootstrap conflict; gateway stays alive " - "while conflict retry runs: %s", - self.name, _redact_telegram_error_text(err), - ) + "[%s] Telegram polling bootstrap conflict; gateway stays alive while conflict retry runs: %s", + self.name, _redact_telegram_error_text(err)) self._spawn_polling_recovery(asyncio.get_running_loop(), self._handle_polling_conflict(err)) return False if self._looks_like_network_error(err): @@ -2318,13 +1728,17 @@ class TelegramAdapter(BasePlatformAdapter): return False raise + async def _go_fatal_network(self, message: str, log_message: str, *log_args) -> None: + """Retryable ``telegram_network_error`` fatal + runner handoff (supervisor rebuilds the adapter).""" + logger.error(log_message, *log_args) + self._set_fatal_error("telegram_network_error", message, retryable=True) + await self._handoff_polling_fatal_error() + async def _stop_updater_or_go_fatal(self, app, what: str) -> bool: """Bounded ``updater.stop()`` before a recovery restart; False = went fatal, caller returns. - Wall-clock deadline, not asyncio.wait_for: a CLOSE-WAIT socket wedges stop() on - epoll and PTB/AnyIO cancellation-shielded cleanup hangs wait_for. On timeout the - Updater's lifecycle lock may still be held, so rebuild the adapter instead. - """ + Wall-clock deadline, not asyncio.wait_for: a CLOSE-WAIT socket wedges stop() on epoll and PTB/AnyIO shielded cleanup + hangs wait_for. On timeout the Updater's lifecycle lock may still be held, so rebuild the adapter instead.""" try: if app and app.updater and app.updater.running: try: @@ -2332,27 +1746,23 @@ class TelegramAdapter(BasePlatformAdapter): except asyncio.TimeoutError: message = ( f"Telegram updater.stop() did not finish before the {what} deadline; " - "rebuilding the adapter instead of reusing an Updater whose lifecycle " - "lock may still be held." - ) - logger.error("[%s] %s (likely CLOSE-WAIT socket)", self.name, message) - self._set_fatal_error("telegram_network_error", message, retryable=True) - await self._handoff_polling_fatal_error() + "rebuilding the adapter instead of reusing an Updater whose lifecycle lock may still be held.") + await self._go_fatal_network(message, "[%s] %s (likely CLOSE-WAIT socket)", self.name, message) return False except Exception: pass return True + def _restart_polling_in_task(self, coro) -> None: + """Run a recovery coroutine as the tracked in-flight ``_polling_error_task``.""" + self._polling_error_task = asyncio.get_running_loop().create_task(coro) + async def _handle_polling_network_error(self, error: Exception) -> None: """Reconnect polling after a transient network interruption (NetworkError/TimedOut). - The host losing connectivity (sleep, WiFi switch, VPN) kills the long-poll silently - while the process lives. Exponential back-off (5s→60s cap) up to MAX_NETWORK_RETRIES, - then retryable-fatal so the supervisor restarts the gateway. - """ - if self._teardown_started: - return - if self.has_fatal_error: + Host connectivity loss (sleep, WiFi switch, VPN) kills the long-poll silently. Exponential back-off (5s→60s + cap) up to MAX_NETWORK_RETRIES, then retryable-fatal so the supervisor restarts the gateway.""" + if self._teardown_started or self.has_fatal_error: return MAX_NETWORK_RETRIES = 10 BASE_DELAY = 5 @@ -2363,34 +1773,24 @@ class TelegramAdapter(BasePlatformAdapter): if attempt > MAX_NETWORK_RETRIES: message = ( "Telegram polling could not reconnect after %d network error retries. " - "Escalating to gateway recovery." % MAX_NETWORK_RETRIES - ) - logger.error("[%s] %s Last error: %s", self.name, message, _redact_telegram_error_text(error)) - self._set_fatal_error("telegram_network_error", message, retryable=True) - await self._handoff_polling_fatal_error() + "Escalating to gateway recovery." % MAX_NETWORK_RETRIES) + await self._go_fatal_network(message, "[%s] %s Last error: %s", self.name, message, _redact_telegram_error_text(error)) return delay = min(BASE_DELAY * (2 ** (attempt - 1)), MAX_DELAY) - safe_error = _redact_telegram_error_text(error) logger.warning( - "[%s] Telegram network error (attempt %d/%d), reconnecting in %ds. Error: %s", - self.name, attempt, MAX_NETWORK_RETRIES, delay, safe_error, - ) + "[%s] Telegram network error (attempt %d/%d), reconnecting in %ds. Error: %s", self.name, attempt, + MAX_NETWORK_RETRIES, delay, _redact_telegram_error_text(error)) await asyncio.sleep(delay) if self._teardown_started: return - # Stable local ref: a concurrent disconnect() may set self._app = None while we - # await below; fail fast in one place instead of swapping in None mid-sequence. + # Stable local ref: a concurrent disconnect() may set self._app = None while we await. app = self._app - # Unguarded stop() on a CLOSE-WAIT socket would leave _polling_error_task - # perpetually "in-flight" so every probe skips reconnect for hours. - if not await self._stop_updater_or_go_fatal(app, "network-recovery"): + # Unguarded stop() on a CLOSE-WAIT socket would leave _polling_error_task perpetually + # "in-flight" so every probe skips reconnect for hours. + if not await self._stop_updater_or_go_fatal(app, "network-recovery") or self._teardown_started: return - if self._teardown_started: - return - # start_polling() bootstraps through the *general* pool before getUpdates; if - # stale proxy sockets exhausted it, draining only the polling pool can't recover. - # A confirmed pool timeout means the request was never sent, so rebuilding the - # general pool is safe. Generic network errors stay polling-only (sends untouched). + # start_polling() bootstraps through the *general* pool before getUpdates; a confirmed pool timeout means the request + # was never sent, so rebuilding that pool is safe. Generic network errors stay polling-only (sends untouched). if self._looks_like_pool_timeout(error): await self._drain_general_connections_after_pool_timeout() if self._teardown_started: @@ -2401,58 +1801,43 @@ class TelegramAdapter(BasePlatformAdapter): try: if not app: raise RuntimeError("Telegram application was torn down during reconnect") - await self._start_polling_once( - app, drop_pending_updates=False, error_callback=self._polling_error_callback_ref, - ) + await self._start_polling_once(app, drop_pending_updates=False, error_callback=self._polling_error_callback_ref) logger.info( - "[%s] Telegram polling restarted after network error (attempt %d); " - "health pending getUpdates progress", - self.name, attempt, - ) + "[%s] Telegram polling restarted after network error (attempt %d); health pending getUpdates progress", self.name, attempt) except _PollingLifecycleAbort: return except Exception as retry_err: if self._teardown_started: return - safe_retry_error = _redact_telegram_error_text(retry_err) - logger.warning("[%s] Telegram polling reconnect failed: %s", self.name, safe_retry_error) + logger.warning("[%s] Telegram polling reconnect failed: %s", self.name, _redact_telegram_error_text(retry_err)) # Polling is dead and no more error callbacks will fire — chain the retry ourselves. if not self.has_fatal_error and not self._teardown_started: task = asyncio.ensure_future(self._handle_polling_network_error(retry_err)) self._background_tasks.add(task) task.add_done_callback(self._background_tasks.discard) - # The chained retry IS the in-flight recovery: it must replace the reentrancy - # guard, or heartbeat/pending-probe/error_callback each start a second one. + # The chained retry IS the in-flight recovery: it must replace the reentrancy guard. self._polling_error_task = task async def _polling_heartbeat_loop(self) -> None: """Detect dead Telegram TCP sockets (CLOSE-WAIT) by periodic probing. - In CLOSE-WAIT epoll still reports the long-poll socket readable and nothing - raises, so PTB's ``error_callback`` never fires and receiving silently stops. - Probe ``get_me()`` every HEARTBEAT_INTERVAL on the *general* path (never the - getUpdates pool, so a healthy long-poll is not interrupted); any connect-level - failure feeds ``_handle_polling_network_error``. Unlike the one-shot generation - verifier this runs for the connection's lifetime, catching steady-state wedges. - """ + In CLOSE-WAIT epoll still reports the long-poll socket readable and nothing raises, so PTB's + ``error_callback`` never fires. Probe ``get_me()`` on the *general* path (never the getUpdates pool); + connect-level failures feed ``_handle_polling_network_error``. Runs for the connection's lifetime, catching + steady-state wedges the one-shot verifier can't.""" HEARTBEAT_INTERVAL = 90 # seconds between probes PROBE_TIMEOUT = 15 # seconds before declaring the path dead - # Wedged-recovery watchdog, tracked locally so no _polling_error_task assignment - # needs a timestamp: note when a recovery task is first seen in-flight and - # force-escalate if the *same* task object still runs past the stuck timeout - # (a healthy ladder attempt finishes or chains to a new task well before then). + # Wedged-recovery watchdog: note when a recovery task is first seen in-flight and force-escalate + # if the *same* task object still runs past the stuck timeout. stuck_task_ref: Optional[asyncio.Task] = None stuck_task_since = 0.0 while True: try: await asyncio.sleep(HEARTBEAT_INTERVAL) - if self._teardown_started: + if self._teardown_started or self.has_fatal_error: return - if self.has_fatal_error: - return - # If the recovery task hung on an unbounded await, every other recovery - # path is gated behind it forever (alive but deaf). Force retryable-fatal - # so the background reconnector rebuilds the adapter. + # A recovery task hung on an unbounded await gates every other recovery path forever + # (alive but deaf): force retryable-fatal so the reconnector rebuilds the adapter. recovery_task = self._polling_error_task if recovery_task is not None and not recovery_task.done(): now = time.monotonic() @@ -2462,21 +1847,15 @@ class TelegramAdapter(BasePlatformAdapter): elif now - stuck_task_since > _POLLING_ERROR_TASK_STUCK_TIMEOUT: stuck_for = now - stuck_task_since logger.error( - "[%s] Telegram reconnect task wedged for %.0fs with no " - "ladder progress; forcing retryable-fatal so the gateway " + "[%s] Telegram reconnect task wedged for %.0fs with no ladder progress; forcing retryable-fatal so the gateway " "reconnects instead of staying silently deaf.", - self.name, stuck_for, - ) - try: + self.name, stuck_for) + with contextlib.suppress(Exception): recovery_task.cancel() - except Exception: - pass self._set_fatal_error( "telegram_network_error", - "Telegram reconnect task wedged for %.0fs; forcing " - "gateway reconnect." % stuck_for, - retryable=True, - ) + "Telegram reconnect task wedged for %.0fs; forcing gateway reconnect." % stuck_for, + retryable=True) await self._handoff_polling_fatal_error() return else: @@ -2488,48 +1867,34 @@ class TelegramAdapter(BasePlatformAdapter): if not callable(getattr(bot, "get_me", None)): return await asyncio.wait_for(bot.get_me(), PROBE_TIMEOUT) - # get_me() refreshes PTB's cached bot user, so a BotFather rename is - # picked up here — adopt the reported handle before anything routes on it. + # get_me() refreshes PTB's cached bot user: adopt a BotFather rename before routing on it. self._bot_identity_checked_at = time.monotonic() self._note_bot_username(getattr(bot, "username", None)) - # get_me() OK proves only the general/send path. PTB can report - # updater.running=True while the long-poll is wedged and DMs queue - # server-side; get_webhook_info().pending_update_count exposes that. - # Escalates only after two consecutive non-zero probes so a single - # in-flight update never trips recovery. + # get_me() OK proves only the send path; a wedged long-poll shows as server-side queue. await self._probe_pending_updates(bot, PROBE_TIMEOUT) - # An empty queue can't hide a wedge forever: Telegram answers within ~50s, - # so no round-trip past the stall threshold ⇒ dead. Pure local-state check. + # An empty queue can't hide a wedge forever: no round-trip past the stall threshold ⇒ dead. await self._check_polling_stall() except asyncio.CancelledError: return except (asyncio.TimeoutError, OSError) as probe_err: self._schedule_polling_recovery(probe_err, reason="heartbeat probe") except Exception as probe_err: + # Non-connectivity errors (e.g. TelegramError 401) aren't CLOSE-WAIT symptoms. if self._looks_like_network_error(probe_err): self._schedule_polling_recovery(probe_err, reason="heartbeat probe") - continue - # Non-connectivity errors (e.g. TelegramError 401) aren't CLOSE-WAIT symptoms. - pass async def _probe_pending_updates(self, bot, probe_timeout: float) -> None: """Detect a wedged or stopped getUpdates consumer via pending_update_count. - PTB can report ``updater.running`` while the long-poll is stuck (e.g. WSL2 socket - epoll keeps reporting readable); get_me() stays healthy on the general path, yet - DMs queue in the Bot API. A stuck queue over two consecutive probes ⇒ dead - consumer; recovery reuses ``_handle_polling_network_error``. Also covers the - updater having stopped entirely (``running=False``, no reconnect in flight), - where no queue can be reported against a live consumer. - """ - if self._teardown_started: - return + PTB can report ``updater.running`` while the long-poll is stuck; get_me() stays healthy yet DMs queue in the + Bot API. A stuck queue over two consecutive probes ⇒ dead consumer. Also covers the updater having stopped + entirely (``running=False``, no reconnect in flight).""" # Polling mode only: in webhook mode Telegram pushes and holds no server-side queue. - if self._webhook_mode: + if self._teardown_started or self._webhook_mode: return - # An in-flight reconnect owns recovery — don't double-trigger, and don't misread its - # brief stop()->start_polling() window (updater.running transiently False) as dead. - if self._polling_error_task and not self._polling_error_task.done(): + # An in-flight reconnect owns recovery — don't double-trigger, and don't misread its brief + # stop()->start_polling() window (updater.running transiently False) as dead. + if self._recovery_in_flight(): self._polling_not_running_count = 0 return updater = getattr(self._app, "updater", None) if self._app else None @@ -2537,32 +1902,18 @@ class TelegramAdapter(BasePlatformAdapter): self._polling_pending_stuck_count = 0 return if not getattr(updater, "running", False): - # Updater stopped entirely with no reconnect in flight: the long-poll task is - # gone, general-path calls still succeed, so no error_callback/probe ever fires. - # Same ladder as a wedged consumer, debounced over two probes so a - # just-starting updater never trips it. + # Long-poll task gone, general-path calls still succeed, so no error_callback/probe ever + # fires. Debounced over two probes so a just-starting updater never trips it. self._polling_pending_stuck_count = 0 self._polling_not_running_count += 1 logger.warning( - "[%s] Telegram polling heartbeat: updater stopped while in " - "polling mode (stuck probe %d/2)", - self.name, self._polling_not_running_count, - ) + "[%s] Telegram polling heartbeat: updater stopped while in polling mode (stuck probe %d/2)", self.name, + self._polling_not_running_count) if self._polling_not_running_count >= 2: self._polling_not_running_count = 0 - if self._teardown_started: - return - logger.warning( - "[%s] Telegram updater is not running (long-poll task gone); " - "triggering polling restart", - self.name, - ) - loop = asyncio.get_running_loop() - self._polling_error_task = loop.create_task( - self._handle_polling_network_error( - RuntimeError("Telegram updater stopped while in polling mode") - ) - ) + self._escalate_stuck_consumer( + "[%s] Telegram updater is not running (long-poll task gone); triggering polling restart", + "Telegram updater stopped while in polling mode") return self._polling_not_running_count = 0 get_webhook_info = getattr(bot, "get_webhook_info", None) @@ -2571,48 +1922,33 @@ class TelegramAdapter(BasePlatformAdapter): try: info = await asyncio.wait_for(get_webhook_info(), probe_timeout) # type: ignore[arg-type] except (asyncio.TimeoutError, OSError): - # Connectivity symptom for the get_me() path / outer handler, not a stuck-queue signal. - return + return # connectivity symptom for the get_me() path, not a stuck-queue signal pending = int(getattr(info, "pending_update_count", 0) or 0) if pending <= 0: self._polling_pending_stuck_count = 0 return self._polling_pending_stuck_count += 1 logger.warning( - "[%s] Telegram polling heartbeat: %d update(s) queued but not consumed (stuck probe %d/2)", - self.name, pending, self._polling_pending_stuck_count, - ) + "[%s] Telegram polling heartbeat: %d update(s) queued but not consumed (stuck probe %d/2)", self.name, + pending, self._polling_pending_stuck_count) if self._polling_pending_stuck_count >= 2: self._polling_pending_stuck_count = 0 - if self._teardown_started: - return - logger.warning( + self._escalate_stuck_consumer( "[%s] getUpdates consumer appears wedged (queue not draining); triggering polling restart", - self.name, - ) - loop = asyncio.get_running_loop() - self._polling_error_task = loop.create_task( - self._handle_polling_network_error( - RuntimeError("getUpdates consumer wedged: pending updates not draining") - ) - ) + "getUpdates consumer wedged: pending updates not draining") - async def _check_polling_stall(self) -> None: - """Watchdog the last successful getUpdates round-trip. - - A long-poll can wedge without raising (TCP dies mid-read, e.g. TUN/proxy route - flip → CLOSE-WAIT): ``updater.running`` stays True, get_me() stays healthy and - with nothing queued ``pending_update_count`` stays 0 — every other probe is blind. - Telegram answers within ~50s, so no round-trip for ``_POLLING_STALL_TIMEOUT`` ⇒ - unambiguously wedged; escalate through the bounded reconnect ladder. - """ - if self._webhook_mode: - return + def _escalate_stuck_consumer(self, log_message: str, reason: str) -> None: + """Second consecutive stuck probe: restart polling via the network-error ladder (unless tearing down).""" if self._teardown_started: return - if self.has_fatal_error: - return - if self._polling_error_task and not self._polling_error_task.done(): + logger.warning(log_message, self.name) + self._polling_error_task = asyncio.get_running_loop().create_task(self._handle_polling_network_error(RuntimeError(reason))) + + async def _check_polling_stall(self) -> None: + """Watchdog the last successful getUpdates round-trip: a long-poll can wedge without raising + (CLOSE-WAIT after a route flip) while every other probe stays blind; no round-trip for + ``_POLLING_STALL_TIMEOUT`` ⇒ escalate through the bounded reconnect ladder.""" + if self._webhook_mode or self._teardown_started or self.has_fatal_error or self._recovery_in_flight(): return now = time.monotonic() last_progress = getattr(self, "_polling_last_progress_monotonic", None) @@ -2620,8 +1956,7 @@ class TelegramAdapter(BasePlatformAdapter): if last_progress is not None: stalled_for = now - last_progress elif generation_started is not None: - # No round-trip yet this generation: fallback for when the one-shot verifier - # (which owns the immediate post-start window) could not run. + # No round-trip yet this generation: fallback for when the one-shot verifier could not run. stalled_for = now - generation_started else: return @@ -2629,26 +1964,23 @@ class TelegramAdapter(BasePlatformAdapter): return logger.error( "[%s] Telegram polling stalled: no getUpdates progress for %.0fs " - "(generation %d). Rebuilding the long-poll consumer through the " - "reconnect ladder instead of staying silently deaf.", - self.name, stalled_for, getattr(self, "_polling_generation", 0), - ) + "(generation %d). Rebuilding the long-poll consumer through the reconnect ladder instead of staying silently deaf.", + self.name, stalled_for, getattr(self, "_polling_generation", 0)) self._spawn_polling_recovery( asyncio.get_running_loop(), self._handle_polling_network_error( - RuntimeError("getUpdates made no progress for %.0fs (polling stall watchdog)" % stalled_for) - ), - ) + RuntimeError("getUpdates made no progress for %.0fs (polling stall watchdog)" % stalled_for))) - async def _verify_polling_after_reconnect( - self, generation: Optional[int] = None, progress: Optional[asyncio.Event] = None, - ) -> None: - """Require getUpdates progress, using getMe only to classify failure. + def _verifier_stale(self, generation: int, progress: asyncio.Event) -> bool: + """True when a verifier's generation no longer matters (progressed, fatal, replaced, torn down).""" + return ( + self._teardown_started or progress.is_set() or self.has_fatal_error + or not self._polling_progress_accepting or generation != self._polling_generation + or progress is not self._polling_progress_event) - The generation-bound event is set only by a successful getUpdates response; a - general-path getMe success classifies connectivity but cannot heal polling health. - Connectivity failures enter the guarded recovery ladder; auth/validation don't churn. - """ + async def _verify_polling_after_reconnect(self, generation: Optional[int] = None, progress: Optional[asyncio.Event] = None) -> None: + """Require getUpdates progress, using getMe only to classify failure: a general-path getMe + success cannot heal polling health. Connectivity failures enter the guarded recovery ladder.""" PROBE_TIMEOUT = 10 if self._teardown_started: return @@ -2656,84 +1988,45 @@ class TelegramAdapter(BasePlatformAdapter): generation = self._polling_generation if progress is None: progress = self._polling_progress_event - try: + with contextlib.suppress(asyncio.TimeoutError): await asyncio.wait_for(progress.wait(), timeout=_POLLING_PROGRESS_TIMEOUT) - except asyncio.TimeoutError: - pass - if self._teardown_started: - return - if progress.is_set() or self.has_fatal_error: - return - if not self._polling_progress_accepting: - return - if generation != self._polling_generation: - return - if progress is not self._polling_progress_event: + if self._verifier_stale(generation, progress): return app = self._app if not (app and app.updater and app.updater.running): logger.warning("[%s] Updater made no getUpdates progress and is not running", self.name) self._schedule_polling_recovery( RuntimeError("Updater not running after polling progress deadline"), - reason="polling progress verifier: updater not running", - ) + reason="polling progress verifier: updater not running") return try: await asyncio.wait_for(app.bot.get_me(), PROBE_TIMEOUT) except Exception as probe_err: - if self._teardown_started: - return - if self.has_fatal_error or not self._polling_progress_accepting: - return - if generation != self._polling_generation: - return - if progress is not self._polling_progress_event or progress.is_set(): + if self._verifier_stale(generation, progress): return if not self._looks_like_network_error(probe_err): logger.warning( - "[%s] Polling progress verifier hit a non-connectivity error (not retrying): %s", - self.name, _redact_telegram_error_text(probe_err), - ) + "[%s] Polling progress verifier hit a non-connectivity error (not retrying): %s", self.name, + _redact_telegram_error_text(probe_err)) return logger.warning( - "[%s] Polling progress verifier connectivity probe failed: %s", - self.name, _redact_telegram_error_text(probe_err), - ) - self._schedule_polling_recovery( - probe_err, reason="polling progress verifier connectivity failure" - ) + "[%s] Polling progress verifier connectivity probe failed: %s", self.name, _redact_telegram_error_text(probe_err)) + self._schedule_polling_recovery(probe_err, reason="polling progress verifier connectivity failure") return - if self._teardown_started: - return - if self.has_fatal_error or not self._polling_progress_accepting: - return - if generation != self._polling_generation: - return - if progress is not self._polling_progress_event or progress.is_set(): + if self._verifier_stale(generation, progress): return self._schedule_polling_recovery( RuntimeError("getUpdates made no progress before verifier deadline"), - reason="polling progress verifier: general path healthy but getUpdates stalled", - ) + reason="polling progress verifier: general path healthy but getUpdates stalled") def _disarm_ptb_retry_loop(self) -> None: """Synchronously stop PTB's internal polling retry loop. - PTB's ``network_retry_loop`` (max_retries=-1) calls our ``error_callback`` - *synchronously* on a TelegramError (incl. 409 Conflict), then re-checks - ``while is_running()`` and polls again. Our callback only schedules async - recovery, so PTB keeps polling while we stop→sleep→start_polling: two sessions - overlap and Telegram returns a fresh 409 on a ~31s cadence. Setting PTB's private - ``stop_event`` inside the callback makes its loop exit on the next tick; our async - ``await updater.stop()`` (idempotent) + drain + ``start_polling()`` then builds a - fresh stop_event so the restart isn't poisoned. - - Best-effort: the attribute is name-mangled and spelled differently across PTB - versions, so probe both; if absent, do nothing (prior racing behaviour, never - worse). Deliberately NOT flipping ``updater._running``: stop() raises when - running is already False and our handler guards on it, so clearing the flag - would skip the real teardown and leave stop_event set for the next start_polling(). - """ + PTB's ``network_retry_loop`` calls our ``error_callback`` *synchronously* on a 409 Conflict then polls again; our + callback only schedules async recovery, so two sessions overlap and Telegram 409s on a ~31s cadence. Setting PTB's + private ``stop_event`` makes its loop exit on the next tick; ``updater.stop()`` + drain + ``start_polling()`` then build + a fresh one. Best-effort across PTB spellings. Deliberately NOT flipping ``updater._running``: stop() raises when + already False, which would skip the real teardown and poison the next start.""" updater = getattr(self._app, "updater", None) if self._app else None if updater is None: return @@ -2745,36 +2038,27 @@ class TelegramAdapter(BasePlatformAdapter): logger.debug("[%s] Disarmed PTB polling retry loop via %s", self.name, attr) return logger.debug( - "[%s] Could not disarm PTB polling retry loop " - "(stop_event not found on this PTB version); " - "falling back to async stop()", - self.name, - ) + "[%s] Could not disarm PTB polling retry loop (stop_event not found on this PTB version); falling back to async stop()", + self.name) async def _handle_polling_conflict(self, error: Exception) -> None: + """Recover a 409 Conflict: the previous gateway process was killed but Telegram holds its + getUpdates session ~30s. Stop, wait (growing delay), drain, restart — MAX_CONFLICT_RETRIES + times before going fatal; a failed retry must never return silently (limbo).""" if self._teardown_started: return if self.has_fatal_error and self.fatal_error_code == "telegram_polling_conflict": return - # Transient 409s: the previous gateway process was killed (update / --replace - # handoff) but Telegram holds its getUpdates session open for up to ~30s. - # Strategy: stop the local updater, wait for the server-side session to expire - # (RETRY_DELAY grows per attempt), drain the pool, restart — MAX_CONFLICT_RETRIES - # times before going fatal. A failed retry must never return silently: an updater - # that is neither running nor fatal drops messages while reporting "connected". self._polling_conflict_count += 1 MAX_CONFLICT_RETRIES = 5 - # 15s, 25s, 35s, 45s, 55s — clears Telegram's ~30s session window without - # hammering the API on fast-restart loops. + # 15s, 25s, 35s, 45s, 55s — clears Telegram's ~30s session window without hammering the API. RETRY_DELAY = 10 + (self._polling_conflict_count * 10) # seconds if self._polling_conflict_count <= MAX_CONFLICT_RETRIES: logger.warning( "[%s] Telegram polling conflict (%d/%d) — previous session still " - "held open on Telegram's servers. Waiting %ds for it to expire. " - "Error: %s", + "held open on Telegram's servers. Waiting %ds for it to expire. Error: %s", self.name, self._polling_conflict_count, MAX_CONFLICT_RETRIES, - RETRY_DELAY, _redact_telegram_error_text(error), - ) + RETRY_DELAY, _redact_telegram_error_text(error)) # Stop the updater before sleeping (no-op if PTB raised before running was set). if not await self._stop_updater_or_go_fatal(self._app, "conflict-retry"): return @@ -2784,27 +2068,19 @@ class TelegramAdapter(BasePlatformAdapter): await self._drain_polling_connections() if self._teardown_started: return - # Stable local ref: a concurrent disconnect() may null self._app across the - # awaits above; fail fast here (where the except reschedules or escalates) - # instead of an AttributeError deep inside start_polling. + # Stable local ref: a concurrent disconnect() may null self._app across the awaits above. app = self._app expected_generation = self._polling_generation + 1 if not app: raise RuntimeError("Telegram application was torn down during conflict reconnect") - # drop_pending_updates=True makes Telegram terminate any other getUpdates - # session for this token — the previous process's zombie or our own prior - # retry's still-expiring session. Without it each retry is immediately 409'd - # by the previous one, recreating the conflict we're recovering from. + # drop_pending_updates=True makes Telegram terminate any other getUpdates session for this + # token (zombie or our own prior retry); without it each retry is immediately 409'd. self._polling_conflict_recovery_generation = expected_generation try: - await self._start_polling_once( - app, drop_pending_updates=True, error_callback=self._polling_error_callback_ref, - ) + await self._start_polling_once(app, drop_pending_updates=True, error_callback=self._polling_error_callback_ref) logger.info( - "[%s] Telegram polling restarted after conflict retry %d/%d; " - "health pending getUpdates progress", - self.name, self._polling_conflict_count, MAX_CONFLICT_RETRIES, - ) + "[%s] Telegram polling restarted after conflict retry %d/%d; health pending getUpdates progress", + self.name, self._polling_conflict_count, MAX_CONFLICT_RETRIES) return except _PollingLifecycleAbort: return @@ -2812,19 +2088,12 @@ class TelegramAdapter(BasePlatformAdapter): if self._teardown_started: return logger.warning( - "[%s] Telegram polling retry %d/%d failed: %s. Scheduling next attempt.", - self.name, self._polling_conflict_count, MAX_CONFLICT_RETRIES, - _redact_telegram_error_text(retry_err), - ) + "[%s] Telegram polling retry %d/%d failed: %s. Scheduling next attempt.", self.name, + self._polling_conflict_count, MAX_CONFLICT_RETRIES, _redact_telegram_error_text(retry_err)) # Never return silently: alive-and-"connected" with no polling is limbo. - if ( - self._polling_conflict_count < MAX_CONFLICT_RETRIES - and not self._teardown_started - ): - # get_running_loop(): get_event_loop() raises on 3.10+ when PTB dispatches - # the error callback from a context without an attached loop. - loop = asyncio.get_running_loop() - self._polling_error_task = loop.create_task(self._handle_polling_conflict(retry_err)) + if self._polling_conflict_count < MAX_CONFLICT_RETRIES and not self._teardown_started: + # get_running_loop(): get_event_loop() raises on 3.10+ from PTB's callback context. + self._restart_polling_in_task(self._handle_polling_conflict(retry_err)) return # Fall through to fatal on the last retry. finally: @@ -2836,42 +2105,30 @@ class TelegramAdapter(BasePlatformAdapter): message = ( "Telegram polling could not recover after %d retries (%ds total wait). " "The previous gateway session is still held open on Telegram's servers, " - "or another process is using the same bot token. " - "To recover: ensure no other Hermes or OpenClaw instance is running " + "or another process is using the same bot token. To recover: ensure no other Hermes or OpenClaw instance is running " "with this token, then restart the gateway with 'hermes gateway restart'." - % (MAX_CONFLICT_RETRIES, sum(10 + i * 10 for i in range(1, MAX_CONFLICT_RETRIES + 1))) - ) + % (MAX_CONFLICT_RETRIES, sum(10 + i * 10 for i in range(1, MAX_CONFLICT_RETRIES + 1)))) logger.error("[%s] %s Original error: %s", self.name, message, _redact_telegram_error_text(error)) - # Snapshot whether WE transition to fatal: a concurrent retry task may be - # suspended past the entry guard, and the bounded stop() await below yields the - # loop so it reaches this branch too. Only the first transition notifies. + # Snapshot whether WE transition to fatal: a concurrent retry task suspended past the entry + # guard reaches this branch too. Only the first transition notifies. _already_fatal = self.has_fatal_error and self.fatal_error_code == "telegram_polling_conflict" self._set_fatal_error("telegram_polling_conflict", message, retryable=False) try: if self._app and self._app.updater: await _await_with_thread_deadline(self._app.updater.stop(), timeout=_UPDATER_STOP_TIMEOUT) except asyncio.TimeoutError: - logger.warning( - "[%s] updater.stop() timed out after exhausting conflict " - "retries (likely CLOSE-WAIT socket); proceeding to fatal notify", - self.name, - ) + logger.warning("[%s] updater.stop() timed out after exhausting conflict retries (likely CLOSE-WAIT socket); proceeding to fatal notify", self.name) except Exception as stop_error: logger.warning( - "[%s] Failed stopping Telegram updater after exhausting conflict retries: %s", - self.name, stop_error, exc_info=True, + "[%s] Failed stopping Telegram updater after exhausting conflict retries: %s", self.name, stop_error, + exc_info=True, ) if not _already_fatal: await self._handoff_polling_fatal_error() async def _handoff_polling_fatal_error(self) -> None: - """Notify the runner without letting child teardown cancel this owner. - - The runner bounds adapter cleanup in a child task, and ``disconnect()`` cancels - the tracked recovery and heartbeat tasks — so leaving the current notifier in - either field would cancel the fatal callback mid-decision. Release only the - current owner from whichever field tracks it. - """ + """Notify the runner without letting child teardown cancel this owner: ``disconnect()`` cancels + the tracked recovery/heartbeat tasks, so release only the current owner from its field.""" current_task = asyncio.current_task() if self._polling_error_task is current_task: self._polling_error_task = None @@ -2880,13 +2137,8 @@ class TelegramAdapter(BasePlatformAdapter): await self._notify_fatal_error() async def _create_dm_topic( - self, chat_id: int, name: str, icon_color: Optional[int] = None, - icon_custom_emoji_id: Optional[str] = None, - ) -> Optional[int]: - """Create a forum topic in a private (DM) chat (Bot API 9.4+ createForumTopic). - - Returns the message_thread_id, or None on failure. - """ + self, chat_id: int, name: str, icon_color: Optional[int] = None, icon_custom_emoji_id: Optional[str] = None) -> Optional[int]: + """Create a forum topic in a private (DM) chat (Bot API 9.4+); message_thread_id or None.""" if not self._bot: return None try: @@ -2897,38 +2149,27 @@ class TelegramAdapter(BasePlatformAdapter): kwargs["icon_custom_emoji_id"] = icon_custom_emoji_id topic = await self._bot.create_forum_topic(**kwargs) thread_id = topic.message_thread_id - logger.info( - "[%s] Created DM topic '%s' in chat %s -> thread_id=%s", - self.name, name, chat_id, thread_id, - ) + logger.info("[%s] Created DM topic '%s' in chat %s -> thread_id=%s", self.name, name, chat_id, thread_id) return thread_id except Exception as e: error_text = str(e).lower() # Telegram has no "list topics" API: an existing topic is mapped from incoming messages. if "topic_name_duplicate" in error_text or "already" in error_text: logger.info( - "[%s] DM topic '%s' already exists in chat %s (will be mapped from incoming messages)", - self.name, name, chat_id, - ) + "[%s] DM topic '%s' already exists in chat %s (will be mapped from incoming messages)", self.name, name, chat_id) elif "not a forum" in error_text or "forums_disabled" in error_text: logger.warning( "[%s] Cannot create DM topic '%s' in chat %s: Topics mode is not enabled. " "The user must open the DM with this bot in Telegram, tap the bot name " "at the top, and enable 'Topics' in chat settings before topics can be created.", - self.name, name, chat_id, - ) + self.name, name, chat_id) else: logger.warning( - "[%s] Failed to create DM topic '%s' in chat %s: %s", - self.name, name, chat_id, _redact_telegram_error_text(e), - ) + "[%s] Failed to create DM topic '%s' in chat %s: %s", self.name, name, chat_id, _redact_telegram_error_text(e)) return None async def create_handoff_thread(self, parent_chat_id: str, name: str) -> Optional[str]: - """Create a forum topic for a session handoff (DM topics or forum supergroups). - - Returns the ``message_thread_id`` as a string, or ``None`` on failure. - """ + """Create a forum topic for a session handoff; ``message_thread_id`` as str, or None.""" try: chat_id_int = int(parent_chat_id) except (TypeError, ValueError): @@ -2955,10 +2196,7 @@ class TelegramAdapter(BasePlatformAdapter): if str(entry.get("chat_id")) != str(chat_id_int): continue chat_entry = entry - for candidate in entry.get("topics", []): - if candidate.get("name") == name: - topic_conf = candidate - break + topic_conf = next((c for c in entry.get("topics", []) if c.get("name") == name), None) break if topic_conf and topic_conf.get("thread_id") and not force_create: thread_id = int(topic_conf["thread_id"]) @@ -2971,9 +2209,7 @@ class TelegramAdapter(BasePlatformAdapter): topic_conf = {"name": name} chat_entry.setdefault("topics", []).append(topic_conf) thread_id = await self._create_dm_topic( - chat_id_int, name=name, icon_color=topic_conf.get("icon_color"), - icon_custom_emoji_id=topic_conf.get("icon_custom_emoji_id"), - ) + chat_id_int, name=name, icon_color=topic_conf.get("icon_color"), icon_custom_emoji_id=topic_conf.get("icon_custom_emoji_id")) if not thread_id: return None topic_conf["thread_id"] = thread_id @@ -2990,13 +2226,9 @@ class TelegramAdapter(BasePlatformAdapter): except (TypeError, ValueError): chat_id_arg = chat_id await self._bot.edit_forum_topic(chat_id=chat_id_arg, message_thread_id=int(thread_id), name=name) - logger.info( - "[%s] Renamed DM topic in chat %s thread_id=%s -> '%s'", self.name, chat_id, thread_id, name, - ) + logger.info("[%s] Renamed DM topic in chat %s thread_id=%s -> '%s'", self.name, chat_id, thread_id, name) - def _persist_dm_topic_thread_id( - self, chat_id: int, topic_name: str, thread_id: int, replace_existing: bool = False, - ) -> None: + def _persist_dm_topic_thread_id(self, chat_id: int, topic_name: str, thread_id: int, replace_existing: bool = False) -> None: """Save a newly created thread_id back into config.yaml so it survives restarts.""" try: from hermes_constants import get_hermes_home @@ -3006,56 +2238,39 @@ class TelegramAdapter(BasePlatformAdapter): return from hermes_cli.config import atomic_config_write, read_user_config_raw config = read_user_config_raw(config_path) - # platforms.telegram.extra.dm_topics — create the path for topics a named - # delivery target asks for that were not predeclared in config.yaml. - platforms = config.setdefault("platforms", {}) - telegram_config = platforms.setdefault("telegram", {}) - extra = telegram_config.setdefault("extra", {}) - dm_topics = extra.setdefault("dm_topics", []) + # platforms.telegram.extra.dm_topics — create the path for topics not predeclared in config.yaml. + dm_topics = config.setdefault("platforms", {}).setdefault("telegram", {}).setdefault("extra", {}).setdefault("dm_topics", []) changed = False matching_chat_entry = None for chat_entry in dm_topics: try: - chat_matches = int(chat_entry.get("chat_id", 0)) == int(chat_id) + if int(chat_entry.get("chat_id", 0)) != int(chat_id): + continue except (TypeError, ValueError): - chat_matches = False - if not chat_matches: continue matching_chat_entry = chat_entry - for t in chat_entry.setdefault("topics", []): - if t.get("name") == topic_name: - if (replace_existing or not t.get("thread_id")) and t.get("thread_id") != thread_id: - t["thread_id"] = thread_id - changed = True - break - else: - chat_entry.setdefault("topics", []).append({"name": topic_name, "thread_id": thread_id}) + topics = chat_entry.setdefault("topics", []) + t = next((t for t in topics if t.get("name") == topic_name), None) + if t is None: + topics.append({"name": topic_name, "thread_id": thread_id}) + changed = True + elif (replace_existing or not t.get("thread_id")) and t.get("thread_id") != thread_id: + t["thread_id"] = thread_id changed = True break if matching_chat_entry is None: - dm_topics.append( - {"chat_id": chat_id, "topics": [{"name": topic_name, "thread_id": thread_id}]} - ) + dm_topics.append({"chat_id": chat_id, "topics": [{"name": topic_name, "thread_id": thread_id}]}) changed = True if changed: atomic_config_write(config_path, config, default_flow_style=False, sort_keys=False) - logger.info( - "[%s] Persisted thread_id=%s for topic '%s' in config.yaml", - self.name, thread_id, topic_name, - ) + logger.info("[%s] Persisted thread_id=%s for topic '%s' in config.yaml", self.name, thread_id, topic_name) except Exception as e: logger.warning("[%s] Failed to persist thread_id to config: %s", self.name, e, exc_info=True) async def _setup_dm_topics(self) -> None: - """Load or create configured DM topics for specified chats. - - ``config.extra['dm_topics']`` is a list of ``{"chat_id": int, "topics": [{"name", - "icon_color", "thread_id"?, "skill"?}, ...]}``. Topics with a persisted thread_id - are cached without an API call; the rest are created and saved back to config.yaml. - """ - if not self._dm_topics_config: - return - for chat_entry in self._dm_topics_config: + """Load or create configured DM topics: ``extra['dm_topics']`` is ``[{"chat_id", "topics": [{"name", + "icon_color", "thread_id"?, "skill"?}]}]``; persisted thread_ids are cached without an API call.""" + for chat_entry in self._dm_topics_config or (): chat_id = chat_entry.get("chat_id") topics = chat_entry.get("topics", []) if not chat_id or not topics: @@ -3069,53 +2284,35 @@ class TelegramAdapter(BasePlatformAdapter): existing_thread_id = topic_conf.get("thread_id") if existing_thread_id: self._dm_topics[cache_key] = int(existing_thread_id) - logger.info( - "[%s] DM topic loaded from config: %s -> thread_id=%s", - self.name, cache_key, existing_thread_id, - ) + logger.info("[%s] DM topic loaded from config: %s -> thread_id=%s", self.name, cache_key, existing_thread_id) continue - icon_color = topic_conf.get("icon_color") - icon_emoji = topic_conf.get("icon_custom_emoji_id") thread_id = await self._create_dm_topic( - chat_id=normalize_telegram_chat_id(chat_id), name=topic_name, - icon_color=icon_color, icon_custom_emoji_id=icon_emoji, - ) - if thread_id: - self._dm_topics[cache_key] = thread_id - logger.info("[%s] DM topic cached: %s -> thread_id=%s", self.name, cache_key, thread_id) - self._persist_dm_topic_thread_id(int(chat_id), topic_name, thread_id) - # Seed message: Telegram's client hides empty topics until they contain one. - try: - await self._bot.send_message( - chat_id=normalize_telegram_chat_id(chat_id), message_thread_id=thread_id, - text=f"\U0001f4cc {topic_name}", - ) - except Exception as seed_err: - logger.debug( - "[%s] Could not send seed message to topic '%s': %s", - self.name, topic_name, seed_err, - ) + chat_id=normalize_telegram_chat_id(chat_id), name=topic_name, icon_color=topic_conf.get("icon_color"), + icon_custom_emoji_id=topic_conf.get("icon_custom_emoji_id")) + if not thread_id: + continue + self._dm_topics[cache_key] = thread_id + logger.info("[%s] DM topic cached: %s -> thread_id=%s", self.name, cache_key, thread_id) + self._persist_dm_topic_thread_id(int(chat_id), topic_name, thread_id) + # Seed message: Telegram's client hides empty topics until they contain one. + try: + await self._bot.send_message( + chat_id=normalize_telegram_chat_id(chat_id), message_thread_id=thread_id, text=f"\U0001f4cc {topic_name}") + except Exception as seed_err: + logger.debug("[%s] Could not send seed message to topic '%s': %s", self.name, topic_name, seed_err) async def _bot_identity_refresh_loop(self) -> None: - """Keep the cached @username fresh when no heartbeat is running. - - Webhook mode never calls ``get_me()`` again after ``initialize()`` (polling mode - does via the heartbeat), so a BotFather rename would break mention routing until restart. - """ + """Keep the cached @username fresh in webhook mode (no heartbeat calls ``get_me()`` there).""" while True: try: await asyncio.sleep(self._BOT_IDENTITY_TTL_SECONDS) - if self._teardown_started: - return - if self.has_fatal_error: + if self._teardown_started or self.has_fatal_error: return await self._refresh_bot_identity(force=True) except asyncio.CancelledError: return except Exception: - logger.debug( - "[%s] Telegram identity refresh loop iteration failed", self.name, exc_info=True - ) + logger.debug("[%s] Telegram identity refresh loop iteration failed", self.name, exc_info=True) def _start_post_connect_housekeeping(self) -> None: """Kick off deferred post-connect housekeeping; idempotent while a task is still running.""" @@ -3124,58 +2321,43 @@ class TelegramAdapter(BasePlatformAdapter): return self._post_connect_task = asyncio.ensure_future(self._run_post_connect_housekeeping()) - async def _run_post_connect_housekeeping(self) -> None: - """Register the command menu, status indicator and DM topics off the connect path. - - A slow Bot API call must not blow the gateway connect timeout. Every step is non-fatal. - """ - try: - # Command menu derives from the central COMMAND_REGISTRY. + async def _register_command_menu(self) -> None: + """Register the command menu (from COMMAND_REGISTRY) in every scope — Telegram picks the + narrowest matching one per chat type; forum topics are handled lazily by _ensure_forum_commands.""" + from telegram import BotCommand, BotCommandScopeAllPrivateChats, BotCommandScopeAllGroupChats, BotCommandScopeDefault + from hermes_cli.commands import telegram_menu_commands, telegram_menu_max_commands + if not self._bot: + return + # Telegram allows 100 commands but has an undocumented ~4KB payload limit; default cap 60. + max_commands = telegram_menu_max_commands() + menu_commands, hidden_count = telegram_menu_commands(max_commands=max_commands) + bot_commands = [BotCommand(name, desc) for name, desc in menu_commands] + for scope_cls in (BotCommandScopeDefault, BotCommandScopeAllPrivateChats, BotCommandScopeAllGroupChats): + scope_name = getattr(scope_cls, "__name__", str(scope_cls)) try: - from telegram import ( - BotCommand, BotCommandScopeAllPrivateChats, BotCommandScopeAllGroupChats, - BotCommandScopeDefault, - ) - from hermes_cli.commands import telegram_menu_commands, telegram_menu_max_commands - if not self._bot: - return - # Telegram allows 100 commands but has an undocumented ~4KB payload limit; - # the default cap of 60 stays under it (tunable via extra.command_menu). - max_commands = telegram_menu_max_commands() - menu_commands, hidden_count = telegram_menu_commands(max_commands=max_commands) - bot_commands = [BotCommand(name, desc) for name, desc in menu_commands] - # Register every scope: Telegram picks the narrowest matching one per chat type. - for scope_cls in (BotCommandScopeDefault, BotCommandScopeAllPrivateChats, BotCommandScopeAllGroupChats): - scope_name = getattr(scope_cls, "__name__", str(scope_cls)) - try: - await self._bot.set_my_commands(bot_commands, scope=scope_cls()) - logger.info("[%s] set_my_commands OK for scope %s (%d cmds)", self.name, scope_name, len(bot_commands)) - except Exception as scope_err: - logger.warning("[%s] set_my_commands FAILED for scope %s: %s", self.name, scope_name, scope_err) - # Forum topics don't inherit AllGroupChats; _ensure_forum_commands registers - # BotCommandScopeChat(chat_id) lazily on the first forum-topic message. - if hidden_count: - logger.info( - "[%s] Telegram menu: %d commands registered, %d hidden (over %d limit). Use /commands for full list.", - self.name, len(menu_commands), hidden_count, max_commands, - ) + await self._bot.set_my_commands(bot_commands, scope=scope_cls()) + logger.info("[%s] set_my_commands OK for scope %s (%d cmds)", self.name, scope_name, len(bot_commands)) + except Exception as scope_err: + logger.warning("[%s] set_my_commands FAILED for scope %s: %s", self.name, scope_name, scope_err) + if hidden_count: + logger.info( + "[%s] Telegram menu: %d commands registered, %d hidden (over %d limit). Use /commands for full list.", + self.name, len(menu_commands), hidden_count, max_commands) + + async def _run_post_connect_housekeeping(self) -> None: + """Command menu, status indicator and DM topics off the connect path; every step is non-fatal.""" + try: + try: + await self._register_command_menu() except Exception as e: logger.warning( - "[%s] Could not register Telegram command menu: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) - # "Online" in the bot's short description (opt-in via extra.status_indicator). - try: + "[%s] Could not register Telegram command menu: %s", self.name, _redact_telegram_error_text(e), exc_info=True) + with contextlib.suppress(Exception): await self._set_status_indicator(online=True) - except Exception: - pass - # DM topics (Bot API 9.4 Private Chat Topics); the bot works fine without them. try: await self._setup_dm_topics() except Exception as topics_err: - logger.warning( - "[%s] DM topics setup failed (non-fatal): %s", self.name, topics_err, exc_info=True - ) + logger.warning("[%s] DM topics setup failed (non-fatal): %s", self.name, topics_err, exc_info=True) except asyncio.CancelledError: raise finally: @@ -3183,16 +2365,9 @@ class TelegramAdapter(BasePlatformAdapter): self._post_connect_task = None async def _on_platform_update(self, update, context) -> None: - """Catch-all PTB handler firing ``gateway_platform_event`` per inbound update. - - Normalizes the update into a stable envelope (no raw SDK objects) and forwards - it with an internal source to the gateway-owned post-auth boundary. Registered - in a dedicated high group so it observes alongside, never displaces, the core - handlers. Malformed updates and dispatch errors never raise into PTB's loop. - """ - handler: Optional[Callable[[Dict[str, Any], Any], Awaitable[None]]] = getattr( - self, "_platform_event_handler", None - ) + """Catch-all PTB handler (group 99) firing ``gateway_platform_event`` per inbound update with a + stable envelope (no raw SDK objects) and an internal auth source. Never raises into PTB.""" + handler: Optional[Callable[[Dict[str, Any], Any], Awaitable[None]]] = getattr(self, "_platform_event_handler", None) if handler is None: return try: @@ -3205,21 +2380,16 @@ class TelegramAdapter(BasePlatformAdapter): return if event is None: return - # The gateway-owned boundary runs the full profile-scoped authorization chain - # before plugin dispatch. No callback = no trusted auth boundary ⇒ fail closed. + # The gateway-owned boundary runs the full profile-scoped auth chain before plugin dispatch. try: source = self._source_for_platform_event_auth(update) await handler(event, source) except Exception: logger.debug("[%s] gateway_platform_event dispatch error", self.name, exc_info=True) - return def _source_for_platform_event_auth(self, update): - """Route a supported update to its event-specific auth-source extractor. - - A reaction carries the reactor, an edit the editor. Raises ``ValueError`` for - updates without a wired extractor so the boundary fails closed. - """ + """Route a supported update to its event-specific auth-source extractor (reactor / editor); + raises ``ValueError`` for updates without one so the boundary fails closed.""" if getattr(update, "message_reaction", None) is not None: return self._source_from_reaction_for_auth(update) edited = getattr(update, "edited_message", None) @@ -3227,32 +2397,26 @@ class TelegramAdapter(BasePlatformAdapter): source = self._source_from_message_for_auth(edited) # Tolerates missing identities for pairing-flow callers; this boundary must not. if not source.user_id or not source.chat_id: - raise ValueError( - "gateway_platform_event message_edited requires editor and chat identities" - ) + raise ValueError("gateway_platform_event message_edited requires editor and chat identities") return source - raise ValueError( - "gateway_platform_event source extraction has no extractor for this update type" - ) + raise ValueError("gateway_platform_event source extraction has no extractor for this update type") def _normalize_platform_event(self, update) -> Optional[Dict[str, Any]]: - """Map a PTB update to a ``{platform, event_type, payload}`` envelope, or ``None``. - - Each event type has its own additive payload contract (hooks.md); raw SDK objects - never leave this boundary. Types without a contract (forward, chat-member) → ``None``. - """ + """Map a PTB update to a ``{platform, event_type, payload}`` envelope (hooks.md contracts), or + ``None`` for types without one.""" if getattr(update, "message_reaction", None) is not None: return self._normalize_reaction_event(update) if getattr(update, "edited_message", None) is not None: return self._normalize_message_edited_event(update) return None - def _normalize_reaction_event(self, update) -> Optional[Dict[str, Any]]: - """Normalize a ``message_reaction`` update (event_type ``reaction``). + @staticmethod + def _is_id_like(value: Any) -> bool: + return not isinstance(value, bool) and isinstance(value, (str, int)) - Payload: ``emojis`` (unicode), ``custom_emoji_ids`` (PTB exposes ``custom_emoji_id`` - with no ``.emoji``), ``chat_id``, ``message_id``, ``thread_id``. - """ + def _normalize_reaction_event(self, update) -> Optional[Dict[str, Any]]: + """``message_reaction`` → ``reaction`` event: emojis (unicode), custom_emoji_ids, chat_id, + message_id, thread_id (always None — reactions carry none).""" mr = getattr(update, "message_reaction", None) if mr is None: return None @@ -3262,10 +2426,7 @@ class TelegramAdapter(BasePlatformAdapter): return None chat_id = getattr(chat, "id", None) if chat is not None else None message_id = getattr(mr, "message_id", None) - if ( - isinstance(chat_id, bool) or not isinstance(chat_id, (str, int)) - or isinstance(message_id, bool) or not isinstance(message_id, (str, int)) - ): + if not self._is_id_like(chat_id) or not self._is_id_like(message_id): return None emojis: List[str] = [] custom_emoji_ids: List[str] = [] @@ -3274,50 +2435,33 @@ class TelegramAdapter(BasePlatformAdapter): if isinstance(emoji, str) and emoji: emojis.append(emoji[:64]) custom_id = getattr(r, "custom_emoji_id", None) - if not isinstance(custom_id, bool) and isinstance(custom_id, (str, int)): + if self._is_id_like(custom_id): custom_emoji_ids.append(str(custom_id)[:128]) return { "platform": "telegram", "event_type": "reaction", "payload": { - "emojis": emojis, - "custom_emoji_ids": custom_emoji_ids, - "chat_id": str(chat_id)[:128], - "message_id": str(message_id)[:128], - # Reactions carry no thread_id; don't guess or expose an adapter object. - "thread_id": None, - }, + "emojis": emojis, "custom_emoji_ids": custom_emoji_ids, "chat_id": str(chat_id)[:128], + "message_id": str(message_id)[:128], "thread_id": None}, } - def _normalize_message_edited_event(self, update) -> Optional[Dict[str, Any]]: - """Normalize an ``edited_message`` update into a ``message_edited`` event. - Payload (v1, additive): chat_id, message_id, thread_id (forum topic), text - (edited text or caption, bounded), edited_at (ISO 8601 UTC or None). No raw - PTB ``Message`` leaves this boundary; malformed identities return None. - """ + def _normalize_message_edited_event(self, update) -> Optional[Dict[str, Any]]: + """``edited_message`` → ``message_edited`` event (v1, additive): chat_id, message_id, thread_id + (forum topic), text (edited text or caption, bounded), edited_at (ISO 8601 UTC or None).""" message = getattr(update, "edited_message", None) if message is None: return None chat = getattr(message, "chat", None) chat_id = getattr(chat, "id", None) if chat is not None else None message_id = getattr(message, "message_id", None) - if ( - isinstance(chat_id, bool) - or not isinstance(chat_id, (str, int)) - or isinstance(message_id, bool) - or not isinstance(message_id, (str, int)) - ): + if not self._is_id_like(chat_id) or not self._is_id_like(message_id): return None text = getattr(message, "text", None) or getattr(message, "caption", None) if not isinstance(text, str): text = None thread_id = None thread_id_raw = getattr(message, "message_thread_id", None) - if ( - not isinstance(thread_id_raw, bool) - and isinstance(thread_id_raw, (str, int)) - and bool(getattr(message, "is_topic_message", False)) - ): + if self._is_id_like(thread_id_raw) and bool(getattr(message, "is_topic_message", False)): thread_id = str(thread_id_raw)[:128] edited_at = None edit_date = getattr(message, "edit_date", None) @@ -3330,354 +2474,211 @@ class TelegramAdapter(BasePlatformAdapter): "platform": "telegram", "event_type": "message_edited", "payload": { - "chat_id": str(chat_id)[:128], - "message_id": str(message_id)[:128], - "thread_id": thread_id, - "text": text[:8192] if text is not None else None, - "edited_at": edited_at, - }, + "chat_id": str(chat_id)[:128], "message_id": str(message_id)[:128], "thread_id": thread_id, + "text": text[:8192] if text is not None else None, "edited_at": edited_at}, } def _register_handlers(self, app) -> None: - """Register every PTB handler on ``app``. - - Single source of truth: initial connect and the transient-init rebuild both - call this, keeping the group-99 observer in lockstep with the core handlers. - """ - app.add_handler(TelegramMessageHandler( - filters.TEXT & ~filters.COMMAND, self._handle_text_message - )) + """Register every PTB handler on ``app`` (initial connect and the transient-init rebuild).""" + app.add_handler(TelegramMessageHandler(filters.TEXT & ~filters.COMMAND, self._handle_text_message)) app.add_handler(TelegramMessageHandler(filters.COMMAND, self._handle_command)) app.add_handler(TelegramMessageHandler( - filters.LOCATION | getattr(filters, "VENUE", filters.LOCATION), - self._handle_location_message - )) + filters.LOCATION | getattr(filters, "VENUE", filters.LOCATION), self._handle_location_message)) app.add_handler(TelegramMessageHandler( filters.PHOTO | filters.VIDEO | filters.AUDIO | filters.VOICE | filters.Document.ALL | filters.Sticker.ALL, - self._handle_media_message - )) - # Inline keyboard button callbacks (update prompts) + self._handle_media_message)) app.add_handler(CallbackQueryHandler(self._handle_callback_query)) - # Inline command picker (@botname ). Inert until the owner enables - # inline mode via BotFather /setinline, so registering unconditionally is safe. + # Inline command picker; inert until the owner enables inline mode via BotFather /setinline. app.add_handler(InlineQueryHandler(self._handle_inline_query)) - # gateway_platform_event observer (see _on_platform_update); group 99 so it - # observes alongside, never displaces, the core handlers. + # gateway_platform_event observer: group 99 observes alongside, never displaces, core handlers. app.add_handler(TypeHandler(Update, self._on_platform_update), group=99) async def _build_ptb_requests(self) -> tuple: - """Build the (general, getUpdates) HTTPXRequest pair for the PTB app. - - Picks the fallback-IP transport, an explicit proxy, or direct DNS, and - instruments the getUpdates request for polling-progress tracking. - """ - # PTB's pool_timeout=1s default trips "Pool timeout: All connections in the - # connection pool are occupied" on flaky networks; use safer defaults + env overrides. + """Build the (general, getUpdates) HTTPXRequest pair: fallback-IP transport, explicit proxy, or + direct DNS; the getUpdates request is instrumented for polling-progress tracking.""" + # PTB's pool_timeout=1s default trips "Pool timeout" on flaky networks; safer defaults + env overrides. request_kwargs = { "connection_pool_size": env_int("HERMES_TELEGRAM_HTTP_POOL_SIZE", 512), "pool_timeout": env_float("HERMES_TELEGRAM_HTTP_POOL_TIMEOUT", 8.0), "connect_timeout": env_float("HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT", 10.0), "read_timeout": env_float("HERMES_TELEGRAM_HTTP_READ_TIMEOUT", 20.0), "write_timeout": env_float("HERMES_TELEGRAM_HTTP_WRITE_TIMEOUT", 20.0), - # Not a duplicate of write_timeout: PTB routes requests carrying files to - # media_write_timeout. httpx budgets it per socket write (stall tolerance, - # not a size/bandwidth cap); 60s rides out congested-link buffer stalls. + # PTB routes file requests to media_write_timeout; httpx budgets it per socket write (stall + # tolerance, not bandwidth), so 60s rides out congested-link buffer stalls. "media_write_timeout": 60.0, } - - # CLOSE_WAIT fd leak: PTB builds its httpx.AsyncClient with no keepalive - # tuning, so httpx's default keepalive_expiry=5.0 applies. Behind a proxy a - # peer FIN can sit in CLOSE_WAIT longer, leaking fds in the general pool that - # _drain_polling_connections never resets. Inject platform_httpx_limits() - # while preserving PTB's max_connections; httpx_kwargs is spread last into - # PTB's client kwargs, so `limits` here wins. + # CLOSE_WAIT fd leak: PTB's httpx.AsyncClient has no keepalive tuning; inject platform_httpx_limits() + # while preserving PTB's max_connections (httpx_kwargs is spread last, so `limits` here wins). from gateway.platforms._http_client_limits import platform_httpx_limits - _base_limits = platform_httpx_limits() if _base_limits is not None: import httpx as _httpx - _pool_limits = _httpx.Limits( max_connections=request_kwargs["connection_pool_size"], - max_keepalive_connections=_base_limits.max_keepalive_connections, - keepalive_expiry=_base_limits.keepalive_expiry, - ) - # A long-poll request is continuously active, so keepalive expiry can't - # protect it from a server-side close. Never hand getUpdates a pooled - # socket from a previous poll; ordinary requests keep the reusable pool. + max_keepalive_connections=_base_limits.max_keepalive_connections, keepalive_expiry=_base_limits.keepalive_expiry) + # A long-poll is continuously active, so keepalive expiry can't protect it from a server-side + # close: never hand getUpdates a pooled socket from a previous poll. _updates_limits = _httpx.Limits( - max_connections=request_kwargs["connection_pool_size"], - max_keepalive_connections=0, - keepalive_expiry=_base_limits.keepalive_expiry, - ) + max_connections=request_kwargs["connection_pool_size"], max_keepalive_connections=0, + keepalive_expiry=_base_limits.keepalive_expiry) else: # pragma: no cover — httpx always present alongside PTB - _pool_limits = None - _updates_limits = None + _pool_limits = _updates_limits = None def _with_limits(httpx_kwargs: Optional[dict] = None) -> dict: - """Merge tuned keepalive limits into httpx client kwargs (proxy/direct - branches only; a caller-supplied ``limits`` wins). The fallback-IP branch - must NOT use this — see the ``_transport_kwargs`` note below.""" + """Merge tuned limits into httpx client kwargs (proxy/direct branches only; the fallback-IP + branch must pass limits straight into the transport — httpx ignores client `limits` then).""" kwargs = dict(httpx_kwargs or {}) if _pool_limits is not None and "limits" not in kwargs: kwargs["limits"] = _pool_limits return kwargs - disable_fallback = ( - os.getenv("HERMES_TELEGRAM_DISABLE_FALLBACK_IPS", "").strip().lower() - in {"1", "true", "yes", "on"} - ) - fallback_ips = self._fallback_ips() - if disable_fallback: - fallback_ips = [] + disable_fallback = os.getenv("HERMES_TELEGRAM_DISABLE_FALLBACK_IPS", "").strip().lower() in {"1", "true", "yes", "on"} + fallback_ips = [] if disable_fallback else self._fallback_ips() if not fallback_ips and not disable_fallback: - discovery_timeout = self._env_float_clamped( - "HERMES_TELEGRAM_FALLBACK_DISCOVERY_TIMEOUT", 5.0, min_value=0.0 - ) - logger.warning( - "[%s] Discovering Telegram API fallback IPs via DNS-over-HTTPS…", self.name - ) + discovery_timeout = self._env_float_clamped("HERMES_TELEGRAM_FALLBACK_DISCOVERY_TIMEOUT", 5.0, min_value=0.0) + logger.warning("[%s] Discovering Telegram API fallback IPs via DNS-over-HTTPS…", self.name) try: - fallback_ips = await _await_with_thread_deadline( - discover_fallback_ips(), timeout=discovery_timeout - ) + fallback_ips = await _await_with_thread_deadline(discover_fallback_ips(), timeout=discovery_timeout) except Exception as exc: logger.warning( "[%s] Telegram fallback-IP discovery failed after %.0fs; " - "using seed IPv4 Telegram API IPs so a blackholed IPv6 " - "hostname path cannot hang initialize() (#87015): %s", - self.name, discovery_timeout, _redact_telegram_error_text(exc), - ) + "using seed IPv4 Telegram API IPs so a blackholed IPv6 hostname path cannot hang initialize() (#87015): %s", + self.name, discovery_timeout, _redact_telegram_error_text(exc)) fallback_ips = list(SEED_FALLBACK_IPS) else: - logger.info( - "[%s] Auto-discovered Telegram fallback IPs: %s", - self.name, ", ".join(fallback_ips), - ) + logger.info("[%s] Auto-discovered Telegram fallback IPs: %s", self.name, ", ".join(fallback_ips)) + proxy_url = resolve_proxy_url("TELEGRAM_PROXY", target_hosts=["api.telegram.org", *fallback_ips]) + + def _pair(general_httpx: dict, updates_httpx: dict, **extra) -> tuple: + return (HTTPXRequest(**request_kwargs, **extra, httpx_kwargs=general_httpx), + HTTPXRequest(**request_kwargs, **extra, httpx_kwargs=updates_httpx)) - proxy_targets = ["api.telegram.org", *fallback_ips] - proxy_url = resolve_proxy_url("TELEGRAM_PROXY", target_hosts=proxy_targets) if fallback_ips and not proxy_url and not disable_fallback: logger.info("[%s] Telegram fallback IPs active: %s", self.name, ", ".join(fallback_ips)) - # Separate request/update pools reduce contention during polling - # reconnect + bootstrap/delete_webhook calls. httpx ignores the - # client-level `limits` kwarg when a custom `transport` is supplied, so - # this branch MUST pass the tuned limits straight into - # TelegramFallbackTransport — never via `_with_limits`. - _transport_kwargs: dict = {} + # Separate request/update pools reduce contention during polling reconnect + bootstrap calls. + _transport_kwargs: dict = {"socket_options": tcp_keepalive_socket_options()} if _pool_limits is not None: _transport_kwargs["limits"] = _pool_limits - _transport_kwargs["socket_options"] = tcp_keepalive_socket_options() _updates_transport_kwargs = dict(_transport_kwargs) if _updates_limits is not None: _updates_transport_kwargs["limits"] = _updates_limits - request = HTTPXRequest( - **request_kwargs, - httpx_kwargs={ - "transport": TelegramFallbackTransport(fallback_ips, **_transport_kwargs) - }, - ) - get_updates_request = HTTPXRequest( - **request_kwargs, - httpx_kwargs={ - "transport": TelegramFallbackTransport( - fallback_ips, **_updates_transport_kwargs - ) - }, - ) + request, get_updates_request = _pair( + {"transport": TelegramFallbackTransport(fallback_ips, **_transport_kwargs)}, + {"transport": TelegramFallbackTransport(fallback_ips, **_updates_transport_kwargs)}) elif proxy_url: logger.info("[%s] Proxy detected; passing explicitly to HTTPXRequest: %s", self.name, proxy_url) - request = HTTPXRequest(**request_kwargs, proxy=proxy_url, httpx_kwargs=_with_limits()) - get_updates_request = HTTPXRequest( - **request_kwargs, proxy=proxy_url, httpx_kwargs={"limits": _updates_limits} - ) + request, get_updates_request = _pair(_with_limits(), {"limits": _updates_limits}, proxy=proxy_url) else: if disable_fallback: logger.info("[%s] Telegram fallback-IP transport disabled via env", self.name) - request = HTTPXRequest(**request_kwargs, httpx_kwargs=_with_limits()) - get_updates_request = HTTPXRequest( - **request_kwargs, httpx_kwargs={"limits": _updates_limits} - ) - - get_updates_request = self._instrument_polling_request(get_updates_request) - return request, get_updates_request + request, get_updates_request = _pair(_with_limits(), {"limits": _updates_limits}) + return request, self._instrument_polling_request(get_updates_request) async def _initialize_app_with_retries(self, builder) -> None: - """Run ``app.initialize()`` with a bounded retry ladder for transient errors. - - Rebuilds ``self._app``/``self._bot`` from ``builder`` after each failed - attempt; raises OSError when the per-attempt or total watchdog expires. - """ - # Each attempt is capped by _init_timeout so one unreachable fallback-IP - # chain can't block startup indefinitely. + """``app.initialize()`` with a bounded retry ladder; rebuilds ``self._app``/``self._bot`` from + ``builder`` after each failed attempt; OSError when the per-attempt or total watchdog expires.""" _max_connect = 8 - _init_timeout = env_float("HERMES_TELEGRAM_INIT_TIMEOUT", 30.0) - # Total watchdog: upper bound on the whole connect loop even if the retry - # loop itself silently stalls (per-attempt timeout plus margin for sleeps). - _total_deadline = ( - asyncio.get_running_loop().time() - + _init_timeout * _max_connect - + 120.0 # extra margin for between-attempt sleeps + overhead - ) + _init_timeout = env_float("HERMES_TELEGRAM_INIT_TIMEOUT", 30.0) # per attempt + # Total watchdog: bounds the whole connect loop even if the retry loop silently stalls. + _total_deadline = asyncio.get_running_loop().time() + _init_timeout * _max_connect + 120.0 + _timed_out = f"Telegram initialization timed out after {_max_connect} attempts ({_init_timeout:.0f}s each)" for _attempt in range(_max_connect): rebuild_app = False try: - # Total watchdog: the ladder must yield even if no attempt raised. if asyncio.get_running_loop().time() >= _total_deadline: raise OSError( - f"Telegram initialization timed out after {_max_connect} attempts " - f"({_init_timeout:.0f}s each) — total connect watchdog " - f"deadline ({_init_timeout * _max_connect + 120.0:.0f}s) exceeded. " - f"Check network connectivity to api.telegram.org " - f"or set HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT / " - f"HERMES_TELEGRAM_INIT_TIMEOUT to a lower value." - ) - logger.warning( - "[%s] Connecting to Telegram (attempt %d/%d)…", - self.name, _attempt + 1, _max_connect, - ) + f"{_timed_out} — total connect watchdog deadline ({_init_timeout * _max_connect + 120.0:.0f}s) exceeded. " + f"Check network connectivity to api.telegram.org or set HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT / " + f"HERMES_TELEGRAM_INIT_TIMEOUT to a lower value.") + logger.warning("[%s] Connecting to Telegram (attempt %d/%d)…", self.name, _attempt + 1, _max_connect) + # On timeout the (possibly shielded) initialize() task is abandoned; release the half-built + # app's httpx client so it isn't leaked across the ladder. await _await_with_thread_deadline( - self._app.initialize(), - timeout=_init_timeout, - # On timeout the initialize() task is abandoned (it may be wedged - # in a shielded scope); best-effort release the half-built app's - # httpx client so it isn't leaked across the retry ladder. - on_abandon=lambda app=self._app: _shutdown_abandoned_app(app), - ) + self._app.initialize(), timeout=_init_timeout, on_abandon=lambda app=self._app: _shutdown_abandoned_app(app)) break except asyncio.TimeoutError: rebuild_app = True - if _attempt < _max_connect - 1: - wait = min(2 ** _attempt, 15) - logger.warning( - "[%s] Connect attempt %d/%d timed out after %.0fs — retrying in %ds", - self.name, _attempt + 1, _max_connect, _init_timeout, wait, - ) - await asyncio.sleep(wait) - else: + if _attempt >= _max_connect - 1: raise OSError( - f"Telegram initialization timed out after {_max_connect} attempts " - f"({_init_timeout:.0f}s each). Check network connectivity to api.telegram.org " - f"or set HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT to a lower value." - ) + f"{_timed_out}. Check network connectivity to api.telegram.org " + f"or set HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT to a lower value.") + wait = min(2 ** _attempt, 15) + logger.warning( + "[%s] Connect attempt %d/%d timed out after %.0fs — retrying in %ds", self.name, _attempt + 1, + _max_connect, _init_timeout, wait) + await asyncio.sleep(wait) except Exception as init_err: # OSError always retries; anything else only when it looks like a network error. rebuild_app = True - if not isinstance(init_err, OSError) and not self._looks_like_network_error(init_err): + if (not isinstance(init_err, OSError) and not self._looks_like_network_error(init_err)) or _attempt >= _max_connect - 1: raise - if _attempt < _max_connect - 1: - wait = min(2 ** _attempt, 15) - logger.warning( - "[%s] Connect attempt %d/%d failed: %s — retrying in %ds", - self.name, _attempt + 1, _max_connect, init_err, wait, - ) - await asyncio.sleep(wait) - else: - raise - except BaseException: - # CancelledError etc.: log for the operator, then reraise to preserve - # cancellation semantics. Placed LAST so the Exception handlers win. + wait = min(2 ** _attempt, 15) logger.warning( - "[%s] Connect attempt %d/%d interrupted by %s — propagating", - self.name, _attempt + 1, _max_connect, - "CancelledError" - if isinstance(sys.exc_info()[1], asyncio.CancelledError) - else type(sys.exc_info()[1]).__name__, - ) + "[%s] Connect attempt %d/%d failed: %s — retrying in %ds", self.name, _attempt + 1, _max_connect, init_err, wait) + await asyncio.sleep(wait) + except BaseException: + # CancelledError etc.: log for the operator, then reraise. LAST so the Exception handlers win. + logger.warning( + "[%s] Connect attempt %d/%d interrupted by %s — propagating", self.name, _attempt + 1, _max_connect, + "CancelledError" if isinstance(sys.exc_info()[1], asyncio.CancelledError) else type(sys.exc_info()[1]).__name__) raise finally: - # A failed attempt may leave the app half-initialized (closed - # transports, half-built handlers): rebuild a fresh Application from - # the same builder for the next attempt and discard the old one. + # A failed attempt may leave the app half-initialized: rebuild a fresh Application from the + # same builder for the next attempt and discard the old one. if rebuild_app and _attempt < _max_connect - 1: old_app = self._app self._app = builder.build() self._bot = self._app.bot - # Keep core and observer handlers in lockstep after a rebuild. - self._register_handlers(self._app) - try: + self._register_handlers(self._app) # keep core and observer handlers in lockstep + with contextlib.suppress(Exception): await _shutdown_abandoned_app(old_app) - except Exception: - pass async def _start_webhook_mode(self, webhook_url: str, *, is_reconnect: bool) -> None: - """Start PTB's webhook server (Telegram pushes updates to us). - - Lets cloud platforms (Fly.io, Railway) auto-wake suspended machines on - inbound HTTP. SECURITY: TELEGRAM_WEBHOOK_SECRET is REQUIRED — without it PTB - passes secret_token=None and the endpoint accepts forged updates from anyone - (GHSA-3vpc-7q5r-276h). Refuse to start rather than run fail-open. - """ + """Start PTB's webhook server (Telegram pushes updates; lets cloud platforms auto-wake suspended + machines). SECURITY: TELEGRAM_WEBHOOK_SECRET is REQUIRED — without it the endpoint accepts forged + updates (GHSA-3vpc-7q5r-276h); refuse to start rather than run fail-open.""" webhook_port = env_int("TELEGRAM_WEBHOOK_PORT", 8443) - # Bind host. Default "" → tornado opens one listening socket per address - # family (IPv4 + IPv6); "0.0.0.0" would be unreachable over IPv6-only - # private networks (e.g. Fly.io 6PN). - webhook_host = ( - os.getenv("TELEGRAM_WEBHOOK_HOST", "").strip() - or str((self.config.extra or {}).get("webhook_host") or "").strip() - ) - # Profile-scoped read: honors the profile's own secret; only an UNSCOPED - # read under multiplex (default-profile startup) falls back to process env. + # Default "" → tornado listens on IPv4 + IPv6; "0.0.0.0" is unreachable on IPv6-only networks. + webhook_host = (os.getenv("TELEGRAM_WEBHOOK_HOST", "").strip() or str((self.config.extra or {}).get("webhook_host") or "").strip()) + # Profile-scoped read; only an UNSCOPED read under multiplex falls back to process env. from agent.secret_scope import UnscopedSecretError, get_secret - try: webhook_secret = (get_secret("TELEGRAM_WEBHOOK_SECRET") or "").strip() except UnscopedSecretError: webhook_secret = os.getenv("TELEGRAM_WEBHOOK_SECRET", "").strip() if not webhook_secret: raise RuntimeError( - "TELEGRAM_WEBHOOK_SECRET is required when " - "TELEGRAM_WEBHOOK_URL is set. Without it, the " - "webhook endpoint accepts forged updates from " - "anyone who can reach it — see " - "https://github.com/NousResearch/hermes-agent/" - "security/advisories/GHSA-3vpc-7q5r-276h.\n\n" - "Generate a secret and set it in your .env:\n" - " export TELEGRAM_WEBHOOK_SECRET=\"$(openssl rand -hex 32)\"\n\n" - "Then register it with Telegram when setting the " - "webhook via setWebhook's secret_token parameter." - ) + "TELEGRAM_WEBHOOK_SECRET is required when TELEGRAM_WEBHOOK_URL is set. Without it, the " + "webhook endpoint accepts forged updates from anyone who can reach it — see " + "https://github.com/NousResearch/hermes-agent/security/advisories/GHSA-3vpc-7q5r-276h.\n\n" + "Generate a secret and set it in your .env:\n export TELEGRAM_WEBHOOK_SECRET=\"$(openssl rand -hex 32)\"\n\n" + "Then register it with Telegram when setting the webhook via setWebhook's secret_token parameter.") from urllib.parse import urlparse webhook_path = urlparse(webhook_url).path or "/telegram" - await self._app.updater.start_webhook( - listen=webhook_host, - port=webhook_port, - url_path=webhook_path, - webhook_url=webhook_url, - secret_token=webhook_secret, - allowed_updates=Update.ALL_TYPES, - # Webhooks are push-based (no server-side getUpdates queue), so this is - # a no-op in practice; mirrors the polling path's reconnect semantics. - drop_pending_updates=not is_reconnect, - ) + listen=webhook_host, port=webhook_port, url_path=webhook_path, webhook_url=webhook_url, + secret_token=webhook_secret, allowed_updates=Update.ALL_TYPES, + drop_pending_updates=not is_reconnect, # push-based ⇒ practically a no-op; mirrors polling + ) self._webhook_mode = True self._polling_progress_accepting = False self._send_path_degraded = False logger.info( - "[%s] Webhook server listening on %s:%d%s", - self.name, webhook_host or "* (all interfaces, IPv4+IPv6)", webhook_port, webhook_path, - ) + "[%s] Webhook server listening on %s:%d%s", self.name, webhook_host or "* (all interfaces, IPv4+IPv6)", + webhook_port, webhook_path) async def _start_polling_mode(self, *, is_reconnect: bool) -> None: """Clear any stale webhook and start resilient long polling.""" - # Clear any stale webhook so polling doesn't inherit it and silently stop - # receiving updates. Best-effort: a transient Bot API error must not fail - # gateway startup — degrade to background polling recovery instead. + # Best-effort: a transient Bot API error must not fail gateway startup — degrade to recovery. await self._delete_webhook_best_effort(require_success=not is_reconnect) - loop = asyncio.get_running_loop() def _polling_error_callback(error: Exception) -> None: - if self._teardown_started: - return - if self._polling_error_task and not self._polling_error_task.done(): + if self._teardown_started or self._recovery_in_flight(): return if self._looks_like_polling_conflict(error): - # Stop PTB's network_retry_loop synchronously BEFORE scheduling the - # async recovery task: PTB calls this callback inside its loop and - # keeps polling, so PTB's retry and our stop->restart would overlap - # and produce a fresh 409. Disarming now lets recovery own polling. + # Stop PTB's network_retry_loop synchronously BEFORE scheduling async recovery, else PTB's + # retry and our stop->restart overlap and produce a fresh 409. self._disarm_ptb_retry_loop() self._spawn_polling_recovery(loop, self._handle_polling_conflict(error)) elif self._looks_like_network_error(error): @@ -3686,48 +2687,25 @@ class TelegramAdapter(BasePlatformAdapter): else: logger.error("[%s] Telegram polling _redact_telegram_error_text(error): %s", self.name, error, exc_info=True) - # Store reference for retry use in _handle_polling_conflict - self._polling_error_callback_ref = _polling_error_callback - + self._polling_error_callback_ref = _polling_error_callback # reused by _handle_polling_conflict polling_started = await self._start_polling_resilient( - # Cold first boot drops the stale Bot API queue; a watcher reconnect - # preserves it so messages sent while offline are delivered. - drop_pending_updates=not is_reconnect, - error_callback=_polling_error_callback, - require_progress=not is_reconnect, - ) + # Cold first boot drops the stale Bot API queue; a watcher reconnect preserves it. + drop_pending_updates=not is_reconnect, error_callback=_polling_error_callback, require_progress=not is_reconnect) if not polling_started: logger.warning( - "[%s] Connected in degraded Telegram mode: gateway is alive, " - "polling will be retried in the background", - self.name, - ) + "[%s] Connected in degraded Telegram mode: gateway is alive, polling will be retried in the background", self.name) async def connect(self, *, is_reconnect: bool = False) -> bool: - """Connect to Telegram via long polling, or a webhook server if - ``TELEGRAM_WEBHOOK_URL`` is set (cloud deployments where inbound HTTP wakes - a suspended machine). + """Connect via long polling, or a webhook server if ``TELEGRAM_WEBHOOK_URL`` is set. - ``is_reconnect``: False = cold boot (drop the stale Bot API queue); True = - watcher reconnect after an outage (preserve queued updates, otherwise every - message sent during the outage is silently lost — matching the network-error - ladder and 409 handler, which already pass ``drop_pending_updates=False``). - - Webhook env: TELEGRAM_WEBHOOK_URL (public HTTPS URL), TELEGRAM_WEBHOOK_PORT - (default 8443), TELEGRAM_WEBHOOK_HOST (default: dual-stack all interfaces), - TELEGRAM_WEBHOOK_SECRET (update verification token). - """ - # Explicit connect() is the only operation allowed to reopen polling after a - # completed, serialized teardown. Background recovery never clears this fence. + ``is_reconnect``: False = cold boot (drop the stale Bot API queue); True = watcher reconnect (preserve queued + updates, else every message sent during the outage is lost). Webhook env: TELEGRAM_WEBHOOK_URL, + TELEGRAM_WEBHOOK_PORT (8443), TELEGRAM_WEBHOOK_HOST, TELEGRAM_WEBHOOK_SECRET.""" + # Explicit connect() is the only operation allowed to reopen polling after a completed teardown. self._polling_teardown_started = False - # Mode is re-evaluated on every explicit connection. - self._webhook_mode = False - + self._webhook_mode = False # re-evaluated on every explicit connection if not TELEGRAM_AVAILABLE: - logger.error( - "[%s] python-telegram-bot not installed. Run: pip install python-telegram-bot", - self.name, - ) + logger.error("[%s] python-telegram-bot not installed. Run: pip install python-telegram-bot", self.name) self._set_fatal_error("missing_dependency", "python-telegram-bot not installed", retryable=False) return False if not self.config.token: @@ -3737,237 +2715,161 @@ class TelegramAdapter(BasePlatformAdapter): try: if not self._acquire_platform_lock('telegram-bot-token', self.config.token, 'Telegram bot token'): return False - builder = Application.builder().token(self.config.token) custom_base_url = self.config.extra.get("base_url") if custom_base_url: builder = builder.base_url(custom_base_url) - builder = builder.base_file_url( - self.config.extra.get("base_file_url", custom_base_url) - ) + builder = builder.base_file_url(self.config.extra.get("base_file_url", custom_base_url)) logger.info("[%s] Using custom Telegram base_url: %s", self.name, custom_base_url) - # Local-mode telegram-bot-api returns absolute server-side file paths; - # PTB needs local_mode=True so download_*() reads from disk instead of - # issuing an HTTP GET that would 404 (path must be readable by Hermes). + # Local-mode telegram-bot-api returns absolute server-side file paths; PTB needs local_mode=True + # so download_*() reads from disk instead of a 404ing HTTP GET. if self.config.extra.get("local_mode"): builder = builder.local_mode(True) logger.info("[%s] Using Telegram local_mode (read files from disk)", self.name) - request, get_updates_request = await self._build_ptb_requests() builder = builder.request(request).get_updates_request(get_updates_request) self._app = builder.build() self._bot = self._app.bot - - # Plugin PTB handlers go BEFORE the core handlers: PTB dispatches the - # first matching handler per group, so pattern-scoped plugin handlers win - # for their own updates and everything else falls through to core. + # Plugin PTB handlers go BEFORE core: PTB dispatches the first matching handler per group. self._wire_plugin_handlers(self._app) self._register_handlers(self._app) - await self._initialize_app_with_retries(builder) await self._app.start() - webhook_url = os.getenv("TELEGRAM_WEBHOOK_URL", "").strip() if webhook_url: await self._start_webhook_mode(webhook_url, is_reconnect=is_reconnect) else: await self._start_polling_mode(is_reconnect=is_reconnect) - self._mark_connected() - mode = "webhook" if self._webhook_mode else "polling" - # WARNING, not INFO: the "Connecting…" line above is WARNING and reaches - # the terminal (default stderr handler is WARNING-only); an INFO success - # line made healthy startups look stalled at "attempt 1/8". A real hang - # must be the *absence* of this line, not ambiguity. - logger.warning("[%s] Connected to Telegram (%s mode)", self.name, mode) - - # Heartbeat loop only in polling mode: webhook mode has no long-poll - # socket to wedge in CLOSE-WAIT. + # WARNING, not INFO: "Connecting…" above is WARNING and reaches the terminal; an INFO success + # line made healthy startups look stalled at "attempt 1/8". + logger.warning("[%s] Connected to Telegram (%s mode)", self.name, "webhook" if self._webhook_mode else "polling") + # Heartbeat only in polling mode: webhook mode has no long-poll socket to wedge in CLOSE-WAIT. if not self._webhook_mode: - if self._polling_heartbeat_task and not self._polling_heartbeat_task.done(): - self._polling_heartbeat_task.cancel() - self._polling_heartbeat_task = asyncio.ensure_future(self._polling_heartbeat_loop()) - - # Seed the live identity from PTB's initialize() cache, then keep it - # fresh: polling rides the heartbeat's get_me() probe; webhook mode has no - # probe, so it gets a low-frequency refresh loop — otherwise a BotFather - # rename breaks mention routing until restart. + self._restart_task_attr("_polling_heartbeat_task", self._polling_heartbeat_loop()) + # Seed the live identity from PTB's initialize() cache; polling rides the heartbeat's get_me(), + # webhook mode gets a low-frequency refresh loop (else a BotFather rename breaks routing). self._note_bot_username(getattr(self._bot, "username", None)) self._bot_identity_checked_at = time.monotonic() if self._webhook_mode: - identity_task = getattr(self, "_bot_identity_refresh_task", None) - if identity_task and not identity_task.done(): - identity_task.cancel() - self._bot_identity_refresh_task = asyncio.ensure_future( - self._bot_identity_refresh_loop() - ) - - # Command-menu registration, DM-topic setup and the status indicator make - # Bot API calls that can stall for some tokens; inside connect() (which - # the gateway wraps in a timeout) one slow call would sink the whole - # connect even though transport is live. Defer to a cancellable task. + self._restart_task_attr("_bot_identity_refresh_task", self._bot_identity_refresh_loop()) + # Command menu / DM topics / status indicator can stall for some tokens: defer to a cancellable + # task so one slow call can't sink the (gateway-timed) connect while transport is live. self._start_post_connect_housekeeping() - return True except Exception as e: self._release_platform_lock() safe_error = _redact_telegram_error_text(e) - # Classify by exception TYPE (never message text): auth failures - # (InvalidToken / Forbidden) can never self-heal, so marking them - # retryable put agents into a silent eternal reconnect loop. Reuse the - # runtime polling path's discriminator so both agree on what's transient. + # Classify by exception TYPE (never message text): auth failures can never self-heal, so + # marking them retryable put agents into a silent eternal reconnect loop. if self._looks_like_auth_error(e): message = ( f"Telegram bot token rejected: {safe_error}. " "The token is invalid or was revoked — generate a new one " - "with @BotFather and update TELEGRAM_BOT_TOKEN." - ) + "with @BotFather and update TELEGRAM_BOT_TOKEN.") self._set_fatal_error("telegram_auth_error", message, retryable=False) else: - message = f"Telegram startup failed: {safe_error}" - self._set_fatal_error("telegram_connect_error", message, retryable=True) + self._set_fatal_error("telegram_connect_error", f"Telegram startup failed: {safe_error}", retryable=True) logger.error("[%s] Failed to connect to Telegram: %s", self.name, safe_error) return False async def _set_status_indicator(self, online: bool) -> None: - """Set the bot's short description (profile line) to the online/offline text. - - Closest Bot API surface to presence — bots have no real online dot. No-op - unless ``extra.status_indicator`` is enabled; best-effort, failures are - logged at debug so they never block connect/disconnect. - """ + """Set the bot's short description to the online/offline text (closest Bot API surface to + presence). No-op unless ``extra.status_indicator``; failures are debug-logged.""" if not getattr(self, "_status_indicator_enabled", False): return bot = self._bot if bot is None: return - text = self._status_online_text if online else self._status_offline_text - # Telegram caps short_description at 120 chars. - text = text[:120] + text = (self._status_online_text if online else self._status_offline_text)[:120] # Telegram cap try: await bot.set_my_short_description(short_description=text) logger.info("[%s] Set bot status indicator to %r", self.name, text) except Exception as e: - logger.debug( - "[%s] Failed to set bot status indicator to %r: %s", - self.name, text, _redact_telegram_error_text(e), - ) + logger.debug("[%s] Failed to set bot status indicator to %r: %s", self.name, text, _redact_telegram_error_text(e)) + + @staticmethod + def _collect_live_tasks(candidates, current_task) -> list: + """Unique, unfinished tasks from ``candidates`` excluding ``current_task`` (so teardown never cancels itself).""" + seen: set[int] = set() + out: list[asyncio.Task] = [] + for task in candidates: + if not task or task.done() or task is current_task or id(task) in seen: + continue + seen.add(id(task)) + out.append(task) + return out + + def _clear_task_attrs_except(self, current_task, *attrs: str) -> None: + for attr in attrs: + if getattr(self, attr, None) is not current_task: + setattr(self, attr, None) async def _cancel_pending_delivery_tasks(self) -> None: - """Cancel every delayed-delivery task family before disconnect completes. - - Media-group, photo-batch, text-batch flush tasks plus the polling-error - recovery task all sit behind ``asyncio.sleep()``; left running they'd - dispatch ``handle_message`` into a torn-down session. Skips the current - task so the teardown coroutine doesn't cancel itself. - """ + """Cancel every delayed-delivery task family before disconnect completes (media-group, photo-batch, text-batch flushes plus + polling recovery all sit behind ``asyncio.sleep()`` and would dispatch ``handle_message`` into a torn-down session).""" current_task = asyncio.current_task() - pending_tasks: list[asyncio.Task] = [] - awaitable_tasks: list[asyncio.Task] = [] - seen: set[int] = set() - - def collect(task: Optional[asyncio.Task]) -> None: - if not task or task.done() or task is current_task: - return - marker = id(task) - if marker in seen: - return - seen.add(marker) - pending_tasks.append(task) - if asyncio.isfuture(task) or asyncio.iscoroutine(task): - awaitable_tasks.append(task) - - for task in list(self._media_group_tasks.values()): - collect(task) - for task in list(self._pending_photo_batch_tasks.values()): - collect(task) - for task in list(self._pending_text_batch_tasks.values()): - collect(task) - collect(getattr(self, "_polling_error_task", None)) - collect(getattr(self, "_polling_progress_verifier_task", None)) - # Hold-queue redispatch must be cancellable+awaitable on teardown so it - # cannot dispatch handle_message into a torn-down session. - collect(getattr(self, "_held_inbound_redispatch_task", None)) - + pending_tasks = self._collect_live_tasks( + [ + *self._media_group_tasks.values(), *self._pending_photo_batch_tasks.values(), *self._pending_text_batch_tasks.values(), + getattr(self, "_polling_error_task", None), getattr(self, "_polling_progress_verifier_task", None), + # Hold-queue redispatch must be cancellable+awaitable on teardown too. + getattr(self, "_held_inbound_redispatch_task", None), + ], + current_task) + awaitable_tasks = [t for t in pending_tasks if asyncio.isfuture(t) or asyncio.iscoroutine(t)] for task in pending_tasks: task.cancel() if awaitable_tasks: await asyncio.gather(*awaitable_tasks, return_exceptions=True) - - # Salvage buffered inbound events before clearing maps — unless permanent - # fatal, where no reconnect can drain and hold would re-orphan them. + # Salvage buffered inbound events before clearing maps — unless permanent fatal, where no + # reconnect can drain and hold would re-orphan them. if self._is_permanent_fatal(): - n_pending = ( - len(self._pending_text_batches) - + len(self._pending_photo_batches) - + len(self._media_group_events) - ) + n_pending = len(self._pending_text_batches) + len(self._pending_photo_batches) + len(self._media_group_events) if n_pending: - logger.warning( - "[Telegram] Non-retryable fatal teardown; discarding %d pending inbound batch(es)", - n_pending, - ) + logger.warning("[Telegram] Non-retryable fatal teardown; discarding %d pending inbound batch(es)", n_pending) else: - for event in list(self._pending_text_batches.values()): - self._hold_inbound_event(event, where="text-batch-teardown") - for event in list(self._pending_photo_batches.values()): - self._hold_inbound_event(event, where="photo-batch-teardown") - for event in list(self._media_group_events.values()): - self._hold_inbound_event(event, where="media-group-teardown") + for events, where in ( + (self._pending_text_batches, "text-batch-teardown"), (self._pending_photo_batches, "photo-batch-teardown"), + (self._media_group_events, "media-group-teardown")): + for event in list(events.values()): + self._hold_inbound_event(event, where=where) + for d in ( + self._media_group_tasks, self._media_group_events, self._pending_photo_batch_tasks, + self._pending_photo_batches, self._pending_text_batch_tasks, self._pending_text_batches): + d.clear() + self._clear_task_attrs_except( + current_task, "_polling_error_task", "_polling_progress_verifier_task", "_held_inbound_redispatch_task") - self._media_group_tasks.clear() - self._media_group_events.clear() - self._pending_photo_batch_tasks.clear() - self._pending_photo_batches.clear() - self._pending_text_batch_tasks.clear() - self._pending_text_batches.clear() - if getattr(self, "_polling_error_task", None) is not current_task: - self._polling_error_task = None - if getattr(self, "_polling_progress_verifier_task", None) is not current_task: - self._polling_progress_verifier_task = None - if getattr(self, "_held_inbound_redispatch_task", None) is not current_task: - self._held_inbound_redispatch_task = None async def _await_disconnect_step(self, awaitable, timeout: float, step: str) -> bool: - """Await one disconnect step; detach on timeout so teardown advances. - - ``asyncio.wait_for`` cancels an overdue child but then waits for it to exit, - so PTB close paths that swallow ``CancelledError`` on a half-dead socket - could wedge disconnect forever. The abandoned task is observed via - ``_consume_abandoned_task``. - """ + """Await one disconnect step; detach on timeout so teardown advances (``wait_for`` would wait for a + PTB close that swallows ``CancelledError`` on a half-dead socket). Abandoned tasks are observed.""" task = asyncio.ensure_future(awaitable) try: - if timeout <= 0: - done, _pending = await asyncio.wait({task}) - else: - done, _pending = await asyncio.wait({task}, timeout=timeout) + done, _pending = await asyncio.wait({task}, timeout=timeout if timeout > 0 else None) except asyncio.CancelledError: - # asyncio.wait does NOT cancel its futures when itself cancelled; don't - # orphan the inner task on outer cancellation. + # asyncio.wait does NOT cancel its futures when itself cancelled; don't orphan the inner task. task.cancel() task.add_done_callback(_consume_abandoned_task) raise if task in done: - # Intentional cancels (heartbeat / identity / lifecycle) surface as - # CancelledError — swallow so disconnect keeps advancing. - try: + with contextlib.suppress(asyncio.CancelledError): await task - except asyncio.CancelledError: - pass return True task.cancel() task.add_done_callback(_consume_abandoned_task) - logger.warning( - "[%s] %s timed out after %.1fs during disconnect; continuing teardown", - self.name, step, timeout, - ) + logger.warning("[%s] %s timed out after %.1fs during disconnect; continuing teardown", self.name, step, timeout) return False - async def _cancel_task_attr(self, attr: str, label: str) -> None: - """Cancel + bounded-await the task stored at ``self.``, then clear it. + def _restart_task_attr(self, attr: str, coro) -> None: + """Cancel any live task stored at ``self.`` and start ``coro`` in its place.""" + prior = getattr(self, attr, None) + if prior and not prior.done(): + prior.cancel() + setattr(self, attr, asyncio.ensure_future(coro)) - getattr guards the object.__new__ test pattern (attribute may be missing). - """ + async def _cancel_task_attr(self, attr: str, label: str) -> None: + """Cancel + bounded-await the task stored at ``self.`` (may be missing: object.__new__ tests), then clear it.""" task = getattr(self, attr, None) if task and not task.done(): task.cancel() @@ -3976,111 +2878,59 @@ class TelegramAdapter(BasePlatformAdapter): async def disconnect(self) -> None: """Stop polling/webhook, cancel pending delayed deliveries, and disconnect.""" - # Mark disconnected first so the drop guard short-circuits any flush that - # wins the race against teardown, and late handlers can't schedule tasks. + # Mark disconnected first so the drop guard short-circuits any flush that wins the race. self._mark_disconnected() self._polling_teardown_started = True self._polling_progress_accepting = False self._polling_generation = getattr(self, "_polling_generation", 0) + 1 self._polling_progress_event = asyncio.Event() self._send_path_degraded = True - - # Release the bot-token lock immediately so a wedged close cannot block the - # reconnect watcher. The rest of teardown is best-effort. + # Release the bot-token lock immediately so a wedged close cannot block the reconnect watcher. self._release_platform_lock() - - # Cancel and await both polling lifecycle owners right after the fence, - # before any other teardown await lets them start a new generation. + # Cancel and await both polling lifecycle owners right after the fence, before any other teardown + # await lets them start a new generation. current_task = asyncio.current_task() - lifecycle_tasks: list[asyncio.Task] = [] - lifecycle_seen: set[int] = set() - for task in ( - getattr(self, "_polling_error_task", None), - getattr(self, "_polling_progress_verifier_task", None), - ): - if not task or task.done() or task is current_task: - continue - marker = id(task) - if marker in lifecycle_seen: - continue - lifecycle_seen.add(marker) + lifecycle_tasks = self._collect_live_tasks( + [getattr(self, "_polling_error_task", None), getattr(self, "_polling_progress_verifier_task", None)], current_task) + for task in lifecycle_tasks: task.cancel() - if asyncio.isfuture(task) or asyncio.iscoroutine(task): - lifecycle_tasks.append(task) + lifecycle_tasks = [t for t in lifecycle_tasks if asyncio.isfuture(t) or asyncio.iscoroutine(t)] if lifecycle_tasks: await self._await_disconnect_step( - asyncio.gather(*lifecycle_tasks, return_exceptions=True), - _DISCONNECT_STEP_TIMEOUT, "lifecycle-task cancel", - ) - if getattr(self, "_polling_error_task", None) is not current_task: - self._polling_error_task = None - if getattr(self, "_polling_progress_verifier_task", None) is not current_task: - self._polling_progress_verifier_task = None - + asyncio.gather(*lifecycle_tasks, return_exceptions=True), _DISCONNECT_STEP_TIMEOUT, "lifecycle-task cancel") + self._clear_task_attrs_except(current_task, "_polling_error_task", "_polling_progress_verifier_task") # Cancellation callbacks may have run while awaited; the fence stays authoritative. self._polling_progress_accepting = False self._send_path_degraded = True - - # Cancel deferred post-connect housekeeping so it cannot fire into a - # half-torn-down bot client. + # Cancel deferred post-connect housekeeping so it cannot fire into a half-torn-down bot client. post_connect_task = getattr(self, "_post_connect_task", None) if post_connect_task and not post_connect_task.done(): post_connect_task.cancel() await self._await_disconnect_step( - asyncio.gather(post_connect_task, return_exceptions=True), - _DISCONNECT_STEP_TIMEOUT, "post-connect cancel", - ) + asyncio.gather(post_connect_task, return_exceptions=True), _DISCONNECT_STEP_TIMEOUT, "post-connect cancel") self._post_connect_task = None - # Cancel the heartbeat before tearing down the app so its probe cannot fire - # get_me() into a half-shutdown bot client; same fence for the webhook-mode - # identity refresh loop. + # Cancel the heartbeat (and webhook-mode identity loop) before tearing down the app. await self._cancel_task_attr("_polling_heartbeat_task", "heartbeat cancel") await self._cancel_task_attr("_bot_identity_refresh_task", "identity-refresh cancel") - - # Mark the bot "Offline" while its HTTP client is still alive (before app - # shutdown closes it). Opt-in, non-fatal; a hard crash leaves the - # last-known status — the expected limitation of a profile-text indicator. - try: - await self._await_disconnect_step( - self._set_status_indicator(online=False), - _DISCONNECT_STEP_TIMEOUT, "status-indicator update", - ) - except Exception: - pass - - await self._await_disconnect_step( - self._cancel_pending_delivery_tasks(), - _DISCONNECT_STEP_TIMEOUT, "pending-delivery cancel", - ) - + # Mark the bot "Offline" while its HTTP client is still alive. Opt-in, non-fatal. + with contextlib.suppress(Exception): + await self._await_disconnect_step(self._set_status_indicator(online=False), _DISCONNECT_STEP_TIMEOUT, "status-indicator update") + await self._await_disconnect_step(self._cancel_pending_delivery_tasks(), _DISCONNECT_STEP_TIMEOUT, "pending-delivery cancel") if self._app: try: - # Bounded: a CLOSE-WAIT socket can wedge updater.stop() on epoll - # forever; on timeout fall through to app.stop()/shutdown(). + # Bounded: a CLOSE-WAIT socket can wedge updater.stop() forever; fall through on timeout. if self._app.updater and self._app.updater.running: try: - await self._await_disconnect_step( - self._app.updater.stop(), _UPDATER_STOP_TIMEOUT, "updater.stop()" - ) + await self._await_disconnect_step(self._app.updater.stop(), _UPDATER_STOP_TIMEOUT, "updater.stop()") except Exception as stop_error: logger.warning( - "[%s] updater.stop() failed during disconnect: %s", - self.name, _redact_telegram_error_text(stop_error), - ) + "[%s] updater.stop() failed during disconnect: %s", self.name, _redact_telegram_error_text(stop_error)) # app.stop()/shutdown() can also block on a half-dead httpx pool. if self._app.running: - await self._await_disconnect_step( - self._app.stop(), _DISCONNECT_STEP_TIMEOUT, "app.stop()" - ) - await self._await_disconnect_step( - self._app.shutdown(), _DISCONNECT_STEP_TIMEOUT, "app.shutdown()" - ) + await self._await_disconnect_step(self._app.stop(), _DISCONNECT_STEP_TIMEOUT, "app.stop()") + await self._await_disconnect_step(self._app.shutdown(), _DISCONNECT_STEP_TIMEOUT, "app.shutdown()") except Exception as e: - logger.warning( - "[%s] Error during Telegram disconnect: %s", - self.name, _redact_telegram_error_text(e), - ) - + logger.warning("[%s] Error during Telegram disconnect: %s", self.name, _redact_telegram_error_text(e)) self._app = None self._bot = None logger.info("[%s] Disconnected from Telegram", self.name) @@ -4092,309 +2942,216 @@ class TelegramAdapter(BasePlatformAdapter): mode = self._reply_to_mode if mode == "off": return False - elif mode == "all": + if mode == "all": return True - else: # "first" (default) - return chunk_index == 0 + return chunk_index == 0 # "first" (default) + + @staticmethod + def _telegram_error_types() -> tuple: + """``(NetworkError, BadRequest, TimedOut)`` from PTB, with import-failure fallbacks + (``OSError``, ``None``, ``None``) so send() still classifies without the SDK.""" + try: + from telegram.error import NetworkError as _NetErr + except ImportError: + _NetErr = OSError # type: ignore[misc,assignment] + try: + from telegram.error import BadRequest as _BadReq + except ImportError: + _BadReq = None # type: ignore[assignment,misc] + try: + from telegram.error import TimedOut as _TimedOut + except (ImportError, AttributeError): + _TimedOut = None # type: ignore[assignment,misc] + return _NetErr, _BadReq, _TimedOut + + async def _send_chunk_markdown_or_plain(self, chunk: str, send_kwargs: Dict[str, Any]): + """MarkdownV2 first; on a parse/markdown rejection resend as stripped plain text.""" + try: + return await self._bot.send_message(text=chunk, parse_mode=ParseMode.MARKDOWN_V2, **send_kwargs) + except Exception as md_error: + if "parse" in str(md_error).lower() or "markdown" in str(md_error).lower(): + logger.warning("[%s] MarkdownV2 parse failed, falling back to plain text: %s", self.name, md_error) + return await self._bot.send_message(text=_strip_mdv2(chunk), parse_mode=None, **send_kwargs) + raise + + async def _send_chunk_with_retries( + self, chat_id: str, chunk: str, index: int, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], + thread_id: Optional[str], used_thread_fallback: bool, error_types: tuple): + """Deliver one chunk: routing, up to 3 attempts, thread-not-found / deleted-anchor / flood handling. + + Returns ``(msg, used_thread_fallback)`` on success or a ``SendResult`` to return verbatim (fail-loud DM-topic + cases, flood cap); raises anything the caller's classifier should see.""" + _NetErr, _BadReq, _TimedOut = error_types + retried_thread_not_found = False + private_dm_topic_send, dm_topic_reply_to_off, reply_to_id = self._chunk_reply_routing(chat_id, reply_to, metadata, thread_id, index) + if private_dm_topic_send and reply_to_id is None and not dm_topic_reply_to_off: + return SendResult(success=False, error=self._dm_topic_missing_anchor_error(), retryable=False) + thread_kwargs = self._thread_kwargs_for_send( + chat_id, thread_id, metadata, reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode) + if used_thread_fallback and thread_kwargs.get("message_thread_id") is not None: + thread_kwargs = dict(thread_kwargs) + thread_kwargs["message_thread_id"] = None + effective_thread_id = thread_kwargs.get("message_thread_id") + for _send_attempt in range(3): + try: + send_kwargs = { + "chat_id": normalize_telegram_chat_id(chat_id), "reply_to_message_id": reply_to_id, **thread_kwargs, + **self._link_preview_kwargs(), **self._notification_kwargs(metadata)} + return await self._send_chunk_markdown_or_plain(chunk, send_kwargs), used_thread_fallback + except _NetErr as send_err: + # BadRequest subclasses NetworkError in PTB but is permanent; handle specific cases. + if _BadReq and isinstance(send_err, _BadReq): + if self._is_thread_not_found_error(send_err) and effective_thread_id is not None: + if private_dm_topic_send or (metadata and metadata.get("telegram_dm_topic_created_for_send")): + return SendResult(success=False, error=str(send_err), retryable=False) + # One-off "thread not found" flakes recover on immediate retry: same thread_id once. + if not retried_thread_not_found: + retried_thread_not_found = True + logger.warning("[%s] Thread %s not found, retrying once with same thread_id", self.name, effective_thread_id) + continue + # Thread is genuinely gone: retry without it and prune the stale binding. + logger.warning("[%s] Thread %s not found, retrying without message_thread_id", self.name, effective_thread_id) + self._prune_stale_dm_topic_binding(chat_id, effective_thread_id, metadata=metadata) + used_thread_fallback = True + effective_thread_id = None + thread_kwargs = {"message_thread_id": None} + continue + if "message to be replied not found" in str(send_err).lower() and reply_to_id is not None: + safe_send_error = _redact_telegram_error_text(send_err) + if private_dm_topic_send: + return SendResult(success=False, error=safe_send_error, retryable=False) + # Reply target deleted; private-topic fallback sends drop anchor + topic id together. + logger.warning("[%s] Reply target deleted, retrying without reply_to: %s", self.name, safe_send_error) + reply_to_id = None + if self._dm_topic_fallback(metadata): + thread_kwargs = {} + else: + thread_kwargs = self._thread_kwargs_for_send( + chat_id, thread_id, metadata, reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode) + effective_thread_id = thread_kwargs.get("message_thread_id") + continue + raise # other BadRequest errors are permanent + # TimedOut also subclasses NetworkError: a generic timeout may have reached Telegram (don't + # retry); a wrapped ConnectTimeout or an httpx pool timeout is safe to retry. + is_pool_timeout = self._looks_like_pool_timeout(send_err) + if ( + _TimedOut and isinstance(send_err, _TimedOut) + and not self._looks_like_connect_timeout(send_err) and not is_pool_timeout): + raise + if is_pool_timeout: + await self._drain_general_connections_after_pool_timeout() + if _send_attempt >= 2: + raise + wait = 2 ** _send_attempt + logger.warning("[%s] Network error on send (attempt %d/3), retrying in %ds: %s", + self.name, _send_attempt + 1, wait, _redact_telegram_error_text(send_err)) + await asyncio.sleep(wait) + except Exception as send_err: + retry_after = getattr(send_err, "retry_after", None) + if retry_after is not None or "retry after" in str(send_err).lower(): + wait = float(retry_after) if retry_after is not None else 1.0 + safe_send_error = _redact_telegram_error_text(send_err) + # Never sleep a long server RetryAfter verbatim — it once pinned send() for 97 minutes. + if wait > _FLOOD_INLINE_WAIT_CAP_SECS: + logger.warning( + "[%s] Telegram flood control on send (retry_after=%.1fs > %.0fs); failing closed instead of sleeping: %s", + self.name, wait, _FLOOD_INLINE_WAIT_CAP_SECS, safe_send_error) + return _flood_cap_result(wait) + if _send_attempt < 2: + logger.warning( + "[%s] Telegram flood control on send (attempt %d/3), retrying in %.1fs: %s", self.name, + _send_attempt + 1, wait, safe_send_error) + await asyncio.sleep(wait) + continue + raise + + async def _retrigger_typing(self, chat_id: str, metadata: Optional[Dict[str, Any]]) -> None: + """Re-arm typing after an intermediate send (Telegram clears it when a message lands). Skipped on + the FINAL reply (``metadata["notify"]``): the refresh loop is gone and no API cancels the bubble.""" + if (metadata or {}).get("notify"): + return + with contextlib.suppress(Exception): + await self.send_typing(chat_id, metadata=metadata) async def send( - self, - chat_id: str, - content: str, - reply_to: Optional[str] = None, - metadata: Optional[Dict[str, Any]] = None - ) -> SendResult: + self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> SendResult: """Send a message to a Telegram chat.""" if not self._bot: live = self._replacement_telegram_adapter() if live is not None: return await live.send(chat_id, content, reply_to, metadata) if self._is_permanent_fatal() or not await self._wait_for_reconnection(): - return SendResult( - success=False, error="Not connected", retryable=not self._is_permanent_fatal() - ) + return SendResult(success=False, error="Not connected", retryable=not self._is_permanent_fatal()) live = self._replacement_telegram_adapter() if not self._bot and live is not None: return await live.send(chat_id, content, reply_to, metadata) if not self._bot: return SendResult(success=False, error="Not connected", retryable=True) - # getattr() — tests build adapters via object.__new__() (no __init__). if getattr(self, "_send_path_degraded", False): return SendResult(success=False, error="send_path_degraded", retryable=True) - # Skip whitespace-only text to prevent Telegram 400 empty-text errors. if not content or not content.strip(): return SendResult(success=True, message_id=None) - + error_types = self._telegram_error_types() try: - # Bot API 10.1 rich fast-path (sendRichMessage renders tables/task lists - # natively). Falls through to legacy MarkdownV2 on permanent/capability - # errors or DM-topic routing skips; returns directly on success or on a - # transient failure (which must NOT be legacy-resent). + # Bot API 10.1 rich fast-path; falls through to legacy MarkdownV2 on permanent/capability + # errors or DM-topic skips; returns directly on success or transient failure (no legacy resend). if self._should_attempt_rich(content, metadata=metadata): rich_result = await self._try_send_rich(chat_id, content, reply_to, metadata) if rich_result is not None: - # Re-trigger typing ONLY for intermediate sends; on the final - # reply (metadata["notify"]) the refresh loop is already torn - # down and re-arming Telegram's ~5s timer leaves the bubble - # lingering (no Bot API call cancels it). - if rich_result.success and not (metadata or {}).get("notify"): - try: - await self.send_typing(chat_id, metadata=metadata) - except Exception: - pass # Typing failures are non-fatal + if rich_result.success: + await self._retrigger_typing(chat_id, metadata) return rich_result - - formatted = self.format_message(content) - chunks = self.truncate_message(formatted, self.MAX_MESSAGE_LENGTH, len_fn=utf16_len) + chunks = self.truncate_message(self.format_message(content), self.MAX_MESSAGE_LENGTH, len_fn=utf16_len) if len(chunks) > 1: - # truncate_message appends a raw " (1/2)" suffix; escape the - # MarkdownV2-special parentheses so Telegram doesn't reject the chunk. + # truncate_message appends a raw " (1/2)" suffix; escape the MarkdownV2-special parentheses. chunks = [ - _separate_chunk_indicator_from_fence( - re.sub(r" \((\d+)/(\d+)\)$", r" \\(\1/\2\\)", chunk) - ) + _separate_chunk_indicator_from_fence(re.sub(r" \((\d+)/(\d+)\)$", r" \\(\1/\2\\)", chunk)) for chunk in chunks - ] - + ] message_ids = [] thread_id = self._metadata_thread_id(metadata) requested_thread_id = self._message_thread_id_for_send(thread_id) used_thread_fallback = False - - try: - from telegram.error import NetworkError as _NetErr - except ImportError: - _NetErr = OSError # type: ignore[misc,assignment] - try: - from telegram.error import BadRequest as _BadReq - except ImportError: - _BadReq = None # type: ignore[assignment,misc] - try: - from telegram.error import TimedOut as _TimedOut - except (ImportError, AttributeError): - _TimedOut = None # type: ignore[assignment,misc] - for i, chunk in enumerate(chunks): - retried_thread_not_found = False - private_dm_topic_send, dm_topic_reply_to_off, reply_to_id = self._chunk_reply_routing( - chat_id, reply_to, metadata, thread_id, i - ) - if private_dm_topic_send and reply_to_id is None and not dm_topic_reply_to_off: - return SendResult( - success=False, error=self._dm_topic_missing_anchor_error(), retryable=False - ) - thread_kwargs = self._thread_kwargs_for_send( - chat_id, thread_id, metadata, - reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode, - ) - if used_thread_fallback and thread_kwargs.get("message_thread_id") is not None: - thread_kwargs = dict(thread_kwargs) - thread_kwargs["message_thread_id"] = None - effective_thread_id = thread_kwargs.get("message_thread_id") - - msg = None - for _send_attempt in range(3): - try: - # Try Markdown first, fall back to plain text if it fails - send_kwargs = { - "chat_id": normalize_telegram_chat_id(chat_id), - "reply_to_message_id": reply_to_id, - **thread_kwargs, - **self._link_preview_kwargs(), - **self._notification_kwargs(metadata), - } - try: - msg = await self._bot.send_message( - text=chunk, parse_mode=ParseMode.MARKDOWN_V2, **send_kwargs, - ) - except Exception as md_error: - if "parse" in str(md_error).lower() or "markdown" in str(md_error).lower(): - logger.warning("[%s] MarkdownV2 parse failed, falling back to plain text: %s", self.name, md_error) - msg = await self._bot.send_message( - text=_strip_mdv2(chunk), parse_mode=None, **send_kwargs, - ) - else: - raise - break # success - except _NetErr as send_err: - # BadRequest subclasses NetworkError in PTB but is permanent; - # handle specific cases instead of blindly retrying. - if _BadReq and isinstance(send_err, _BadReq): - if self._is_thread_not_found_error(send_err) and effective_thread_id is not None: - if private_dm_topic_send or (metadata and metadata.get("telegram_dm_topic_created_for_send")): - return SendResult( - success=False, error=str(send_err), retryable=False - ) - # Telegram returns one-off "thread not found" flakes that - # recover on immediate retry: try the same thread_id once - # (no sleep) before falling back to a plain send. - if not retried_thread_not_found: - retried_thread_not_found = True - logger.warning( - "[%s] Thread %s not found, retrying once with same thread_id", - self.name, effective_thread_id, - ) - continue - # Second failure: thread is genuinely gone. Retry without - # message_thread_id and prune the stale binding so future - # inbound messages aren't redirected back to it. - logger.warning( - "[%s] Thread %s not found, retrying without message_thread_id", - self.name, effective_thread_id, - ) - self._prune_stale_dm_topic_binding( - chat_id, effective_thread_id, metadata=metadata - ) - used_thread_fallback = True - effective_thread_id = None - thread_kwargs = {"message_thread_id": None} - continue - err_lower = str(send_err).lower() - if "message to be replied not found" in err_lower and reply_to_id is not None: - if private_dm_topic_send: - safe_send_error = _redact_telegram_error_text(send_err) - return SendResult( - success=False, error=safe_send_error, retryable=False - ) - # Reply target deleted before we could reply. For private- - # topic fallback sends, message_thread_id is only valid with - # the reply anchor, so drop both together. - safe_send_error = _redact_telegram_error_text(send_err) - logger.warning( - "[%s] Reply target deleted, retrying without reply_to: %s", - self.name, safe_send_error, - ) - reply_to_id = None - if metadata and metadata.get("telegram_dm_topic_reply_fallback"): - thread_kwargs = {} - effective_thread_id = None - else: - thread_kwargs = self._thread_kwargs_for_send( - chat_id, thread_id, metadata, - reply_to_message_id=reply_to_id, - reply_to_mode=self._reply_to_mode, - ) - effective_thread_id = thread_kwargs.get("message_thread_id") - continue - # Other BadRequest errors are permanent — don't retry - raise - # TimedOut also subclasses NetworkError. A generic timeout may have - # reached Telegram, so don't retry; a wrapped ConnectTimeout (no - # connection) or an httpx pool timeout (explicitly not sent) is - # safe to retry and prevents silent drops. - is_pool_timeout = self._looks_like_pool_timeout(send_err) - if ( - _TimedOut - and isinstance(send_err, _TimedOut) - and not self._looks_like_connect_timeout(send_err) - and not is_pool_timeout - ): - raise - if is_pool_timeout: - await self._drain_general_connections_after_pool_timeout() - if _send_attempt < 2: - wait = 2 ** _send_attempt - safe_send_error = _redact_telegram_error_text(send_err) - logger.warning("[%s] Network error on send (attempt %d/3), retrying in %ds: %s", - self.name, _send_attempt + 1, wait, safe_send_error) - await asyncio.sleep(wait) - else: - raise - except Exception as send_err: - retry_after = getattr(send_err, "retry_after", None) - if retry_after is not None or "retry after" in str(send_err).lower(): - wait = float(retry_after) if retry_after is not None else 1.0 - safe_send_error = _redact_telegram_error_text(send_err) - # Mirror the edit path: never sleep a long server RetryAfter - # verbatim — it once pinned send() for 97 minutes and froze - # inbound on every platform from the gateway boot path. - if wait > _FLOOD_INLINE_WAIT_CAP_SECS: - logger.warning( - "[%s] Telegram flood control on send " - "(retry_after=%.1fs > %.0fs); failing closed " - "instead of sleeping: %s", - self.name, wait, _FLOOD_INLINE_WAIT_CAP_SECS, safe_send_error, - ) - return _flood_cap_result(wait) - if _send_attempt < 2: - logger.warning( - "[%s] Telegram flood control on send (attempt %d/3), retrying in %.1fs: %s", - self.name, _send_attempt + 1, wait, safe_send_error, - ) - await asyncio.sleep(wait) - continue - raise + outcome = await self._send_chunk_with_retries( + chat_id, chunk, i, reply_to, metadata, thread_id, used_thread_fallback, error_types) + if isinstance(outcome, SendResult): + return outcome + msg, used_thread_fallback = outcome message_ids.append(str(msg.message_id)) - - # Re-trigger typing: Telegram clears typing state when a message lands, - # so the bubble would vanish mid-response after intermediate progress - # messages. Skip on the FINAL reply (metadata["notify"]): the refresh - # loop is already cancelled, so re-arming Telegram's ~5s timer would - # leave the indicator lingering (no stop-typing API exists). - if not (metadata or {}).get("notify"): - try: - await self.send_typing(chat_id, metadata=metadata) - except Exception: - pass # Typing failures are non-fatal - + await self._retrigger_typing(chat_id, metadata) return SendResult( - success=True, - message_id=message_ids[0] if message_ids else None, + success=True, message_id=message_ids[0] if message_ids else None, raw_response={ - "message_ids": message_ids, - "requested_thread_id": requested_thread_id, - "thread_fallback": used_thread_fallback, - }, - ) + "message_ids": message_ids, "requested_thread_id": requested_thread_id, "thread_fallback": used_thread_fallback}) except Exception as e: safe_error = _redact_telegram_error_text(e) logger.error("[%s] Failed to send Telegram message: %s", self.name, safe_error) err_str = str(e).lower() error_kind = classify_send_error(e) - # Content exceeded 4096 chars: fail so the stream consumer enters - # fallback mode and sends the remainder. + # Content exceeded 4096 chars: fail so the stream consumer enters fallback mode. if "message_too_long" in err_str or "too long" in err_str: - logger.debug( - "[%s] send() content too long, falling back to new-message continuation", - self.name, - ) + logger.debug("[%s] send() content too long, falling back to new-message continuation", self.name) return SendResult(success=False, error="message_too_long", error_kind="too_long") - # TimedOut usually means the request may have reached Telegram — mark - # non-retryable so _send_with_retry() doesn't re-send. Exceptions: a - # wrapped ConnectTimeout and an httpx pool timeout are safe to re-send. - _to = locals().get("_TimedOut") + # TimedOut may have reached Telegram — non-retryable so _send_with_retry() doesn't re-send, + # except a wrapped ConnectTimeout or an httpx pool timeout (safe to re-send). + _to = error_types[2] is_timeout = (_to and isinstance(e, _to)) or "timed out" in err_str - is_connect_timeout = self._looks_like_connect_timeout(e) - is_pool_timeout = self._looks_like_pool_timeout(e) return SendResult( - success=False, - error=safe_error, - retryable=(is_connect_timeout or is_pool_timeout or not is_timeout), - error_kind=error_kind, - ) + success=False, error=safe_error, + retryable=(self._looks_like_connect_timeout(e) or self._looks_like_pool_timeout(e) or not is_timeout), + error_kind=error_kind) async def send_or_update_status( - self, - chat_id: str, - status_key: str, - content: str, - *, - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: - """Send a status message, or edit the previous one with the same key. - - First call sends and remembers the message id; later calls with the same - (chat_id, status_key) edit it in place. If the edit fails (deleted, too - old, …) the cached id is dropped and a fresh message is sent. - """ + self, chat_id: str, status_key: str, content: str, *, metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Send a status message, or edit the previous one with the same ``(chat_id, status_key)``; if the + edit fails (deleted, too old, …) the cached id is dropped and a fresh message is sent.""" key = (str(chat_id), str(status_key)) cached_id = self._status_message_ids.get(key) if cached_id is not None: - result = await self.edit_message( - chat_id, cached_id, content, finalize=True, metadata=metadata - ) + result = await self.edit_message(chat_id, cached_id, content, finalize=True, metadata=metadata) if result.success: if result.message_id: self._status_message_ids[key] = str(result.message_id) @@ -4404,119 +3161,89 @@ class TelegramAdapter(BasePlatformAdapter): if result.success and result.message_id: self._status_message_ids[key] = str(result.message_id) return result + async def _edit_text(self, chat_id: str, message_id: str, text: str, parse_mode: Any = None) -> None: """``editMessageText`` with normalized ids; ``parse_mode=None`` sends plain text.""" - kwargs: Dict[str, Any] = { - "chat_id": normalize_telegram_chat_id(chat_id), "message_id": int(message_id), "text": text, - } + kwargs: Dict[str, Any] = {"chat_id": normalize_telegram_chat_id(chat_id), "message_id": int(message_id), "text": text} if parse_mode is not None: kwargs["parse_mode"] = parse_mode await self._bot.edit_message_text(**kwargs) + async def _edit_markdown_or_plain(self, chat_id: str, message_id: str, formatted: str, plain: str, warn_fmt: str) -> bool: + """MarkdownV2 edit with plain-text fallback. Returns True on a "not modified" no-op (caller may + skip further work); the fallback edit's exceptions propagate.""" + try: + await self._edit_text(chat_id, message_id, formatted, ParseMode.MARKDOWN_V2) + except Exception as fmt_err: + if "not modified" in str(fmt_err).lower(): + return True + logger.warning(warn_fmt, self.name, _redact_telegram_error_text(fmt_err)) + await self._edit_text(chat_id, message_id, plain) + return False + async def edit_message( - self, - chat_id: str, - message_id: str, - content: str, - *, - finalize: bool = False, - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: + self, chat_id: str, message_id: str, content: str, *, finalize: bool = False, metadata: Optional[Dict[str, Any]] = None, + ) -> SendResult: """Edit a previously sent Telegram message. - Telegram caps a message at 4096 UTF-16 codeunits. Streaming replies that - outgrow it must NOT be truncated silently nor fail (the consumer would - re-send a duplicate): edit with the first chunk, send the rest as - continuations, and return the final chunk's id as the next edit target. - """ + Telegram caps a message at 4096 UTF-16 codeunits. Streaming replies that outgrow it must NOT be truncated + silently nor fail (the consumer would re-send a duplicate): edit with the first chunk, send the rest as + continuations, and return the final chunk's id as the next edit target.""" if not self._bot: return SendResult(success=False, error="Not connected") - - # Rich finalize (Bot API 10.1): when content has constructs the MarkdownV2 - # edit degrades (tables, task lists,
, block math), edit the preview - # IN PLACE via rich_message — no fresh send + delete, so no duplicate - # preview. Done before the 4,096 pre-flight because the rich cap is 32,768; - # a rich table over the MarkdownV2 limit must not be split into legacy - # chunks. Falls back to the legacy path on capability/permanent rejection. + # Rich finalize (Bot API 10.1): edit the preview IN PLACE via rich_message — no fresh send + delete. + # Before the 4,096 pre-flight because the rich cap is 32,768; falls back to legacy on rejection. if finalize and self._rich_eligible(content): rich_result = await self._try_edit_rich(chat_id, message_id, content, metadata=metadata) if rich_result is not None: return rich_result - - # Pre-flight: if content already exceeds the limit, split-and-deliver - # without a doomed edit. Mid-stream (finalize=False) we truncate instead: - # splitting moves the edit target to a continuation, and the next token - # chunk re-edits the full text into it → infinite duplication loop. Full - # content is delivered when finalize=True. + # Pre-flight: over-limit content is split-and-delivered on finalize; mid-stream we truncate instead + # (splitting moves the edit target to a continuation → infinite duplication loop). _preview_key = (str(chat_id), str(message_id)) _saturated_preview = False if finalize: - # The final edit always delivers real (full) content. - self._last_overflow_preview.pop(_preview_key, None) + self._last_overflow_preview.pop(_preview_key, None) # the final edit always delivers full content if utf16_len(content) > self.MAX_MESSAGE_LENGTH: if finalize: - return await self._edit_overflow_split( - chat_id, message_id, content, finalize=finalize, metadata=metadata - ) + return await self._edit_overflow_split(chat_id, message_id, content, finalize=finalize, metadata=metadata) content = self._truncate_stream_overflow_preview(content) _saturated_preview = True - # Saturated-preview dedup: past the cap every progressive edit truncates - # to the same text; re-sending is a visual no-op that still burns flood - # budget (~1 edit/0.8s trips 200s+ penalties and hangs final delivery). + # Saturated-preview dedup: past the cap every progressive edit truncates to the same text; + # re-sending is a visual no-op that still burns flood budget (200s+ penalties). if self._last_overflow_preview.get(_preview_key) == content: return SendResult(success=True, message_id=message_id) elif not finalize: - # Content shrank back under the cap — clear stale saturation state so - # dedup can't mask a real edit later. + # Content shrank back under the cap — clear stale saturation state so dedup can't mask an edit. self._last_overflow_preview.pop(_preview_key, None) - try: if not finalize: await self._edit_text(chat_id, message_id, content) if _saturated_preview: self._last_overflow_preview[_preview_key] = content return SendResult(success=True, message_id=message_id) - - formatted = self.format_message(content) - try: - await self._edit_text(chat_id, message_id, formatted, ParseMode.MARKDOWN_V2) - except Exception as fmt_err: - # "Message is not modified" is a no-op, not an error - if "not modified" in str(fmt_err).lower(): - return SendResult(success=True, message_id=message_id) - safe_format_error = _redact_telegram_error_text(fmt_err) - logger.warning( - "[%s] MarkdownV2 edit failed, falling back to plain text: %s", - self.name, safe_format_error, - ) - _plain = _strip_mdv2(content) if content else content - await self._edit_text(chat_id, message_id, _plain) + await self._edit_markdown_or_plain( + chat_id, message_id, self.format_message(content), _strip_mdv2(content) if content else content, + "[%s] MarkdownV2 edit failed, falling back to plain text: %s") return SendResult(success=True, message_id=message_id) except Exception as e: err_str = str(e).lower() if "not modified" in err_str: return SendResult(success=True, message_id=message_id) - # Reactive split-and-deliver: parse_mode formatting (MarkdownV2 escapes) - # can inflate the payload past the limit even when raw text was under. + # Reactive split: MarkdownV2 escapes can inflate the payload past the limit even when raw text fit. if "message_too_long" in err_str or "too long" in err_str: logger.debug( - "[%s] edit_message overflow (%d UTF-16 > %d), splitting", - self.name, utf16_len(content), self.MAX_MESSAGE_LENGTH, - ) + "[%s] edit_message overflow (%d UTF-16 > %d), splitting", self.name, utf16_len(content), self.MAX_MESSAGE_LENGTH) if finalize: - return await self._edit_overflow_split( - chat_id, message_id, content, finalize=finalize, metadata=metadata - ) - # Mid-stream: truncate and retry instead of splitting. + return await self._edit_overflow_split(chat_id, message_id, content, finalize=finalize, metadata=metadata) + # Mid-stream: truncate and retry instead of splitting (saturated-preview dedup as above). truncated = self._truncate_stream_overflow_preview(content) if self._last_overflow_preview.get(_preview_key) == truncated: - # Saturated-preview dedup (see pre-flight path above). return SendResult(success=True, message_id=message_id) await self._edit_text(chat_id, message_id, truncated) self._last_overflow_preview[_preview_key] = truncated return SendResult(success=True, message_id=message_id) - # Flood control: short waits retry inline; long waits fail immediately so - # streaming falls back to a normal final send instead of a clipped partial. + # Flood control: short waits retry inline; long waits fail immediately so streaming falls back + # to a normal final send instead of a clipped partial. retry_after = getattr(e, "retry_after", None) if retry_after is not None or "retry after" in err_str: wait = retry_after if retry_after else 1.0 @@ -4529,340 +3256,181 @@ class TelegramAdapter(BasePlatformAdapter): return SendResult(success=True, message_id=message_id) except Exception as retry_err: safe_retry_error = _redact_telegram_error_text(retry_err) - logger.error( - "[%s] Edit retry failed after flood wait: %s", self.name, safe_retry_error - ) + logger.error("[%s] Edit retry failed after flood wait: %s", self.name, safe_retry_error) return SendResult(success=False, error=safe_retry_error) - # Transient network errors must not permanently disable progress-message - # editing: mark retryable so the caller keeps trying next update cycle. - _transient_markers = ( - "connecterror", "connect error", "connection error", "networkerror", - "network error", "timed out", "readtimeout", "writetimeout", - "server disconnected", "temporarily unavailable", "temporary failure", "httpx", - ) - _is_transient = any(m in err_str for m in _transient_markers) - if _is_transient: - safe_error = _redact_telegram_error_text(e) - logger.warning( - "[%s] Transient network error editing message %s (will retry): %s", - self.name, message_id, safe_error, - ) - return SendResult(success=False, error=safe_error, retryable=True) safe_error = _redact_telegram_error_text(e) - logger.error( - "[%s] Failed to edit Telegram message %s: %s", self.name, message_id, safe_error - ) + # Transient network errors must not permanently disable progress-message editing. + _transient_markers = ( + "connecterror", "connect error", "connection error", "networkerror", "network error", "timed out", "readtimeout", + "writetimeout", "server disconnected", "temporarily unavailable", "temporary failure", "httpx") + if any(m in err_str for m in _transient_markers): + logger.warning("[%s] Transient network error editing message %s (will retry): %s", self.name, message_id, safe_error) + return SendResult(success=False, error=safe_error, retryable=True) + logger.error("[%s] Failed to edit Telegram message %s: %s", self.name, message_id, safe_error) return SendResult(success=False, error=safe_error) def _truncate_stream_overflow_preview(self, content: str) -> str: - """One-message preview for oversized streaming edits. - - Streaming edits must keep targeting the original message; splitting - mid-stream would move the active id and repeat the overflow cycle. Final - edits use ``_edit_overflow_split`` to deliver the complete response. - """ + """One-message preview for oversized streaming edits (edits must keep targeting the original id; + final edits use ``_edit_overflow_split``).""" return self.truncate_message(content, self.MAX_MESSAGE_LENGTH, len_fn=utf16_len)[0] - async def _edit_overflow_split( - self, - chat_id: str, - message_id: str, - content: str, - *, - finalize: bool, - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: - """Split an oversized edit across the existing message + continuations. + async def _send_overflow_continuation( + self, chat_id: str, chunk: str, reply_to_id: Optional[int], thread_kwargs: Dict[str, Any], + thread_id: Optional[str], metadata: Optional[Dict[str, Any]], finalize: bool): + """Send one continuation chunk (MarkdownV2 then plain on finalize; raw when streaming); drops the + reply anchor once on 'reply message not found'. Returns the sent message or None.""" + base = {**self._link_preview_kwargs(), **self._notification_kwargs(metadata)} + for use_markdown in (True, False) if finalize else (False,): + try: + if use_markdown: + text = _separate_chunk_indicator_from_fence(self.format_message(chunk)) + else: + # Degrade to stripped text on finalize (raw ** / ``` would render literally); previews stay raw. + text = _strip_mdv2(chunk) if finalize else chunk + return await self._bot.send_message( + chat_id=normalize_telegram_chat_id(chat_id), text=text, parse_mode=ParseMode.MARKDOWN_V2 if use_markdown else None, + reply_to_message_id=reply_to_id, **thread_kwargs, **base) + except Exception as send_err: + if "reply message not found" in str(send_err).lower(): + # Private DM topic fallback needs anchor + topic id together; forum topics keep thread id. + retry_thread_kwargs = ( + {} if self._dm_topic_fallback(metadata) + else self._thread_kwargs_for_send(chat_id, thread_id, metadata, reply_to_message_id=None)) + try: + return await self._bot.send_message( + chat_id=normalize_telegram_chat_id(chat_id), text=_strip_mdv2(chunk) if finalize else chunk, + **retry_thread_kwargs, **base) + except Exception as _retry_err: + logger.warning( + "[%s] Overflow continuation no-reply retry failed: %s", self.name, _redact_telegram_error_text(_retry_err)) + return None + if use_markdown: + continue # try plain text on next loop iteration + logger.warning("[%s] Overflow continuation send failed: %s", self.name, _redact_telegram_error_text(send_err)) + return None + return None - Edit ``message_id`` with chunk 1 (``(1/N)`` suffix preserved), then send - the remaining chunks as replies to the previous chunk. Returns - ``SendResult(success=True, message_id=, - continuation_message_ids=(...))`` so the consumer keeps editing the most - recent visible message. ``success=False`` only if the first-chunk edit - itself fails — a real adapter problem, not an overflow. - """ + async def _edit_overflow_split( + self, chat_id: str, message_id: str, content: str, *, finalize: bool, metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Split an oversized edit across the existing message + continuations: edit ``message_id`` with + chunk 1, send the rest as replies to the previous chunk, return ``message_id=`` so + the consumer keeps editing the newest message. ``success=False`` only if the first-chunk edit fails.""" chunks = self.truncate_message(content, self.MAX_MESSAGE_LENGTH, len_fn=utf16_len) if len(chunks) <= 1: - # Defensive: caller pre-flighted, but a single chunk just edits normally. - chunks = [content] - - # Step 1 — edit the existing message with the first chunk. + chunks = [content] # defensive: a single chunk just edits normally first_chunk = chunks[0] try: if finalize: - # Mirror edit_message's happy path: format_message + parse_mode. - formatted = _separate_chunk_indicator_from_fence(self.format_message(first_chunk)) - try: - await self._edit_text(chat_id, message_id, formatted, ParseMode.MARKDOWN_V2) - except Exception as fmt_err: - if "not modified" not in str(fmt_err).lower(): - logger.warning( - "[%s] Overflow split: MarkdownV2 first-chunk edit " - "failed, falling back to plain text: %s", - self.name, _redact_telegram_error_text(fmt_err), - ) - await self._edit_text(chat_id, message_id, _strip_mdv2(first_chunk)) + await self._edit_markdown_or_plain( + chat_id, message_id, _separate_chunk_indicator_from_fence(self.format_message(first_chunk)), _strip_mdv2(first_chunk), + "[%s] Overflow split: MarkdownV2 first-chunk edit failed, falling back to plain text: %s") else: await self._edit_text(chat_id, message_id, first_chunk) except Exception as e: - err_str = str(e).lower() - if "not modified" in err_str: - # First chunk identical to current text — still send continuations. - pass - else: - logger.error( - "[%s] Overflow split: first-chunk edit failed: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) + if "not modified" not in str(e).lower(): # identical first chunk still sends continuations + logger.error("[%s] Overflow split: first-chunk edit failed: %s", self.name, _redact_telegram_error_text(e), exc_info=True) return SendResult(success=False, error=_redact_telegram_error_text(e)) - - # Step 2 — send remaining chunks as reply-threaded continuations. Calls - # self._bot.send_message directly to skip self.send's pre-chunking (chunks - # are already sized). Best-effort MarkdownV2 with plain fallback, like send(). + # Continuations call self._bot.send_message directly to skip self.send's pre-chunking. continuation_ids: list[str] = [] delivered_chunks = [first_chunk] prev_id = message_id thread_id = self._metadata_thread_id(metadata) for chunk in chunks[1:]: - sent_msg = None reply_to_id = int(prev_id) if prev_id else None - thread_kwargs = self._thread_kwargs_for_send( - chat_id, thread_id, metadata, reply_to_message_id=reply_to_id - ) - for use_markdown in (True, False) if finalize else (False,): - try: - if use_markdown: - text = _separate_chunk_indicator_from_fence(self.format_message(chunk)) - else: - # On finalize the MarkdownV2 attempt failed: degrade to stripped - # text, never the raw chunk (raw ** / ``` would render - # literally); streaming previews stay raw. - text = _strip_mdv2(chunk) if finalize else chunk - sent_msg = await self._bot.send_message( - chat_id=normalize_telegram_chat_id(chat_id), - text=text, - parse_mode=ParseMode.MARKDOWN_V2 if use_markdown else None, - reply_to_message_id=reply_to_id, - **thread_kwargs, - **self._link_preview_kwargs(), - **self._notification_kwargs(metadata), - ) - break - except Exception as send_err: - if "reply message not found" in str(send_err).lower(): - # Drop the reply anchor and retry. Private DM topic fallback - # needs anchor + topic id together; forum topics keep thread id. - retry_thread_kwargs = ( - {} - if metadata and metadata.get("telegram_dm_topic_reply_fallback") - else self._thread_kwargs_for_send( - chat_id, thread_id, metadata, reply_to_message_id=None - ) - ) - try: - sent_msg = await self._bot.send_message( - chat_id=normalize_telegram_chat_id(chat_id), - text=_strip_mdv2(chunk) if finalize else chunk, - **retry_thread_kwargs, - **self._link_preview_kwargs(), - **self._notification_kwargs(metadata), - ) - break - except Exception as _retry_err: - logger.warning( - "[%s] Overflow continuation no-reply retry failed: %s", - self.name, _redact_telegram_error_text(_retry_err), - ) - sent_msg = None - break - if use_markdown: - continue # try plain text on next loop iteration - logger.warning( - "[%s] Overflow continuation send failed: %s", - self.name, _redact_telegram_error_text(send_err), - ) - sent_msg = None - break + thread_kwargs = self._thread_kwargs_for_send(chat_id, thread_id, metadata, reply_to_message_id=reply_to_id) + sent_msg = await self._send_overflow_continuation(chat_id, chunk, reply_to_id, thread_kwargs, thread_id, metadata, finalize) if sent_msg is None: - # Partial delivery: do NOT report success — the stream consumer treats - # a successful edit as final delivery on got_done, which would suppress - # fallback delivery and leave the topic clipped. - logger.warning( - "[%s] Overflow split: stopped at %d/%d chunks delivered", - self.name, 1 + len(continuation_ids), len(chunks), - ) - delivered_prefix = "".join( - re.sub(r" \(\d+/\d+\)$", "", delivered) for delivered in delivered_chunks - ) + # Partial delivery: do NOT report success — the consumer would treat it as final delivery. + logger.warning("[%s] Overflow split: stopped at %d/%d chunks delivered", self.name, 1 + len(continuation_ids), len(chunks)) + delivered_prefix = "".join(re.sub(r" \(\d+/\d+\)$", "", delivered) for delivered in delivered_chunks) return SendResult( - success=False, - message_id=prev_id, - error="overflow_continuation_failed", - retryable=True, + success=False, message_id=prev_id, error="overflow_continuation_failed", retryable=True, raw_response={ - "partial_overflow": True, - "delivered_chunks": 1 + len(continuation_ids), - "total_chunks": len(chunks), - "last_message_id": prev_id, - "delivered_prefix": delivered_prefix, - "continuation_message_ids": tuple(continuation_ids), - }, - continuation_message_ids=tuple(continuation_ids), - ) + "partial_overflow": True, "delivered_chunks": 1 + len(continuation_ids), + "total_chunks": len(chunks), "last_message_id": prev_id, "delivered_prefix": delivered_prefix, + "continuation_message_ids": tuple(continuation_ids)}, + continuation_message_ids=tuple(continuation_ids)) new_id = str(getattr(sent_msg, "message_id", "")) or prev_id continuation_ids.append(new_id) delivered_chunks.append(chunk) prev_id = new_id - last_id = continuation_ids[-1] if continuation_ids else message_id - logger.debug( - "[%s] Overflow split delivered %d chunks; last_id=%s", - self.name, 1 + len(continuation_ids), last_id, - ) - return SendResult( - success=True, message_id=last_id, continuation_message_ids=tuple(continuation_ids) - ) - async def delete_message(self, chat_id: str, message_id: str) -> bool: - """Delete a bot-posted message (Bot API allows it within 48h). + logger.debug("[%s] Overflow split delivered %d chunks; last_id=%s", self.name, 1 + len(continuation_ids), last_id) + return SendResult(success=True, message_id=last_id, continuation_message_ids=tuple(continuation_ids)) - Used by the stream consumer's fresh-final cleanup to remove long-lived - previews. Failures are non-fatal — the caller leaves the preview in place. - """ + async def delete_message(self, chat_id: str, message_id: str) -> bool: + """Delete a bot-posted message (Bot API allows it within 48h); failures are non-fatal.""" if not self._bot: return False try: - await self._bot.delete_message( - chat_id=normalize_telegram_chat_id(chat_id), message_id=int(message_id) - ) + await self._bot.delete_message(chat_id=normalize_telegram_chat_id(chat_id), message_id=int(message_id)) return True except Exception as e: - logger.debug( - "[%s] Failed to delete Telegram message %s: %s", - self.name, message_id, _redact_telegram_error_text(e), - ) + logger.debug("[%s] Failed to delete Telegram message %s: %s", self.name, message_id, _redact_telegram_error_text(e)) return False - def supports_draft_streaming( - self, - chat_type: Optional[str] = None, - metadata: Optional[Dict[str, Any]] = None, - ) -> bool: - """Telegram supports sendMessageDraft for private chats only (Bot API 9.5); - groups/supergroups/channels use the edit-based path. Also requires PTB >= 22.6 - (``send_message_draft``); older installs fall back to edits even on DMs. - - ``rich_drafts`` controls draft *format*, not availability: with rich final - delivery but no rich drafts, keep the preview ephemeral and persist via - ``sendRichMessage`` — an in-place edit can't be relied on to upgrade through - ``rich_message``, and the fallback formatter turns tables into bullets. - """ + def supports_draft_streaming(self, chat_type: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> bool: + """sendMessageDraft works for private chats only (Bot API 9.5) and needs PTB >= 22.6; groups and + older installs use the edit-based path. ``rich_drafts`` controls draft *format*, not availability.""" if not self._bot or not hasattr(self._bot, "send_message_draft"): return False return (chat_type or "").lower() in {"dm", "private"} - async def send_draft( - self, - chat_id: str, - draft_id: int, - content: str, - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: - """Stream a partial message via Telegram's native draft API. - - Uses ``sendRichMessageDraft`` (Bot API 10.1) when rich is enabled and - supported, else plain ``sendMessageDraft``. Reusing ``draft_id`` animates - the preview. The caller sends the final text via ``send``; the draft clears - on the client (no Bot API "promotes" a draft to a real message). - """ + async def send_draft(self, chat_id: str, draft_id: int, content: str, metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Stream a partial message via ``sendRichMessageDraft`` (when rich is enabled and supported) else + ``sendMessageDraft``; reusing ``draft_id`` animates the preview. The caller sends the final text.""" if not self._bot: return SendResult(success=False, error="not_connected") - - # Rich draft fast-path: preview with the same raw markdown the final - # sendRichMessage persists. Any failure degrades to the plain draft below. - if self._should_attempt_rich_draft(content) and await self._try_send_rich_draft( - chat_id, draft_id, content, metadata - ): - # Drafts have no message_id; report success without one. + # Rich draft fast-path; any failure degrades to the plain draft below. Drafts have no message_id. + if self._should_attempt_rich_draft(content) and await self._try_send_rich_draft(chat_id, draft_id, content, metadata): return SendResult(success=True, message_id=None) - if not hasattr(self._bot, "send_message_draft"): return SendResult(success=False, error="api_unavailable") - # Drafts share the regular-send UTF-16 length contract. - text = content if len(content) <= self.MAX_MESSAGE_LENGTH else \ - self.truncate_message(content, self.MAX_MESSAGE_LENGTH, len_fn=utf16_len)[0] - - # Apply the same MarkdownV2 conversion as ``send`` so the draft doesn't snap - # from raw to formatted at the end; try MarkdownV2 then plain so one bad - # token never kills draft streaming. Exception: when the persistent - # response will be a Rich Message but rich drafts are disabled, send a raw - # preview — the legacy formatter would rewrite pipe tables into bullets. + text = content if len( + content) <= self.MAX_MESSAGE_LENGTH else self.truncate_message(content, self.MAX_MESSAGE_LENGTH, len_fn=utf16_len)[0] + # Same MarkdownV2 conversion as ``send`` (MarkdownV2 then plain) so the draft doesn't snap at the end. Exception: a Rich + # final with rich drafts disabled previews raw — the legacy formatter would turn pipe tables into bullets. plain_rich_preview = bool( - getattr(self, "_rich_messages_enabled", False) - and not getattr(self, "_rich_drafts_enabled", False) - and self._needs_rich_rendering(text) - ) - draft_modes = (False,) if plain_rich_preview else (True, False) + getattr(self, "_rich_messages_enabled", False) and not getattr(self, "_rich_drafts_enabled", False) + and self._needs_rich_rendering(text)) draft_thread_kwargs = self._thread_kwargs_for_draft(chat_id, metadata) - for use_markdown in draft_modes: + for use_markdown in ((False,) if plain_rich_preview else (True, False)): kwargs: Dict[str, Any] = { - "chat_id": normalize_telegram_chat_id(chat_id), - "draft_id": int(draft_id), - "text": self.format_message(text) if use_markdown else text, - } + "chat_id": normalize_telegram_chat_id(chat_id), "draft_id": int(draft_id), + "text": self.format_message(text) if use_markdown else text} if use_markdown: kwargs["parse_mode"] = ParseMode.MARKDOWN_V2 kwargs.update(draft_thread_kwargs) - try: - ok = await self._bot.send_message_draft(**kwargs) - if ok: - # Drafts have no message_id; success means the frame landed. + if await self._bot.send_message_draft(**kwargs): return SendResult(success=True, message_id=None) return SendResult(success=False, error="draft_rejected") except Exception as e: - # MarkdownV2 parse failure (BadRequest) → retry once as plain text. - # Anything else, or a plain-text failure, returns to the caller, + # MarkdownV2 parse failure → retry once as plain text; anything else returns to the caller, # which falls back to edit-based streaming for this response. if use_markdown and self._is_bad_request_error(e): logger.debug( - "[%s] sendMessageDraft MarkdownV2 rejected, retrying " - "as plain text (chat=%s draft_id=%s): %s", - self.name, chat_id, draft_id, _redact_telegram_error_text(e), - ) + "[%s] sendMessageDraft MarkdownV2 rejected, retrying as plain text (chat=%s draft_id=%s): %s", + self.name, chat_id, draft_id, _redact_telegram_error_text(e)) continue - logger.debug( - "[%s] sendMessageDraft failed (chat=%s draft_id=%s): %s", - self.name, chat_id, draft_id, e, - ) + logger.debug("[%s] sendMessageDraft failed (chat=%s draft_id=%s): %s", self.name, chat_id, draft_id, e) return SendResult(success=False, error=_redact_telegram_error_text(e)) - return SendResult(success=False, error="draft_rejected") async def _send_message_with_thread_fallback(self, **kwargs): - """Send a message, retrying once without message_thread_id on 'Message - thread not found'. For control-style sends (approval prompts, pickers, - update prompts) that can carry a stale thread_id; ``send`` has its own. - """ + """Send a control-style message (approval prompts, pickers), retrying once without + message_thread_id on 'Message thread not found' (stale thread_id); ``send`` has its own.""" if not self._bot: raise RuntimeError("Not connected") - message_thread_id = kwargs.get("message_thread_id") try: return await self._bot.send_message(**kwargs) except Exception as send_err: - if ( - message_thread_id is not None - and self._is_bad_request_error(send_err) - and self._is_thread_not_found_error(send_err) - ): + if (message_thread_id is not None and self._is_bad_request_error(send_err) and self._is_thread_not_found_error(send_err)): logger.warning( - "[%s] Thread %s not found for control message, retrying without message_thread_id", - self.name, message_thread_id, - ) - # Same prune as the streaming send path: the topic is gone, so the - # state.db binding must go too. Control sends carry no gateway - # metadata, so the prune namespaces by this adapter's profile stamp. + "[%s] Thread %s not found for control message, retrying without message_thread_id", self.name, message_thread_id) + # Same prune as the streaming send path; control sends carry no gateway metadata. self._prune_stale_dm_topic_binding(kwargs.get("chat_id"), message_thread_id) retry_kwargs = dict(kwargs) retry_kwargs.pop("message_thread_id", None) @@ -4870,59 +3438,57 @@ class TelegramAdapter(BasePlatformAdapter): raise async def _send_control_message( - self, - chat_id: str, - text: str, - *, - parse_mode: Any, - thread_id: Optional[str], - metadata: Optional[Dict[str, Any]], - reply_markup: Any = None, - reply_to_mode: Optional[str] = None, - ): + self, chat_id: str, text: str, *, parse_mode: Any, thread_id: Optional[str], metadata: Optional[Dict[str, Any]], + reply_markup: Any = None, reply_to_mode: Optional[str] = None): """Send a control-style message (prompt/picker) with topic routing + thread fallback.""" reply_to_id = self._reply_to_message_id_for_send(None, metadata, reply_to_mode=reply_to_mode) kwargs: Dict[str, Any] = { - "chat_id": normalize_telegram_chat_id(chat_id), - "text": text, - "parse_mode": parse_mode, - **self._link_preview_kwargs(), - } + "chat_id": normalize_telegram_chat_id(chat_id), "text": text, "parse_mode": parse_mode, **self._link_preview_kwargs()} if reply_markup is not None: kwargs["reply_markup"] = reply_markup kwargs["reply_to_message_id"] = reply_to_id - kwargs.update( - self._thread_kwargs_for_send( - chat_id, thread_id, metadata, - reply_to_message_id=reply_to_id, reply_to_mode=reply_to_mode, - ) - ) + kwargs.update(self._thread_kwargs_for_send( + chat_id, thread_id, metadata, reply_to_message_id=reply_to_id, reply_to_mode=reply_to_mode)) return await self._send_message_with_thread_fallback(**kwargs) - async def send_update_prompt( - self, chat_id: str, prompt: str, default: str = "", - session_key: str = "", - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: - """Send an inline-keyboard Yes/No prompt for the gateway ``/update`` watcher.""" + async def _send_prompt(self, what: str, chat_id: str, metadata: Optional[Dict[str, Any]], build, *, + parse_mode: Any = None, thread_id: Any = None, reply_to_mode: Any = None) -> SendResult: + """Shared control-prompt shell: not-connected guard, ``build()`` → ``(text, keyboard, on_sent)`` (or a + SendResult to return as-is), routed send, state hook, redacted failure log.""" if not self._bot: return SendResult(success=False, error="Not connected") try: + built = build() + if isinstance(built, SendResult): + return built + text, keyboard, on_sent = built + msg = await self._send_control_message( + chat_id, text, parse_mode=parse_mode if parse_mode is not None else ParseMode.MARKDOWN_V2, + reply_markup=keyboard, thread_id=thread_id, metadata=metadata, reply_to_mode=reply_to_mode) + if on_sent is not None: + on_sent(msg) + return SendResult(success=True, message_id=str(msg.message_id)) + except Exception as e: + logger.warning("[%s] %s failed: %s", self.name, what, _redact_telegram_error_text(e)) + return SendResult(success=False, error=_redact_telegram_error_text(e)) + + @staticmethod + def _rows_of_two(buttons: list) -> list: + """2-per-row layout keeps labels readable on mobile (a 4-button row truncates).""" + return [buttons[i:i + 2] for i in range(0, len(buttons), 2)] + + async def send_update_prompt( + self, chat_id: str, prompt: str, default: str = "", session_key: str = "", metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Send an inline-keyboard Yes/No prompt for the gateway ``/update`` watcher.""" + def build(): default_hint = f" (default: {default})" if default else "" text = self.format_message(f"⚕ *Update needs your input:*\n\n{prompt}{default_hint}") keyboard = InlineKeyboardMarkup([[ InlineKeyboardButton("✓ Yes", callback_data="update_prompt:y"), - InlineKeyboardButton("✗ No", callback_data="update_prompt:n"), - ]]) - msg = await self._send_control_message( - chat_id, text, parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard, - thread_id=self._metadata_thread_id(metadata), metadata=metadata, - reply_to_mode=self._reply_to_mode, - ) - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] send_update_prompt failed: %s", self.name, _redact_telegram_error_text(e)) - return SendResult(success=False, error=_redact_telegram_error_text(e)) + InlineKeyboardButton("✗ No", callback_data="update_prompt:n")]]) + return text, keyboard, None + return await self._send_prompt( + "send_update_prompt", chat_id, metadata, build, thread_id=self._metadata_thread_id(metadata), reply_to_mode=self._reply_to_mode) # Template attrs for the shared _format_exec_approval core (HTML mode). _EA_HEADER = "⚠️ Command Approval Required\n\n" @@ -4935,190 +3501,101 @@ class TelegramAdapter(BasePlatformAdapter): return _html.escape(text) async def send_exec_approval( - self, chat_id: str, command: str, session_key: str, - description: str = "dangerous command", - metadata: Optional[Dict[str, Any]] = None, - allow_permanent: bool = True, - allow_session: bool = True, - smart_denied: bool = False, - ) -> SendResult: - """Send an inline-keyboard approval prompt; buttons call - ``resolve_gateway_approval()`` like the text ``/approve`` flow.""" - if not self._bot: - return SendResult(success=False, error="Not connected") - - try: + self, chat_id: str, command: str, session_key: str, description: str = "dangerous command", + metadata: Optional[Dict[str, Any]] = None, allow_permanent: bool = True, allow_session: bool = True, + smart_denied: bool = False) -> SendResult: + """Send an inline-keyboard approval prompt; buttons call ``resolve_gateway_approval()`` like the + text ``/approve`` flow.""" + def build(): text = self._format_exec_approval(command, description, smart_denied) - thread_id = self._metadata_thread_id(metadata) - # Short monotonic ids in callback_data map back to session_key. import itertools if not hasattr(self, "_approval_counter"): self._approval_counter = itertools.count(1) approval_id = next(self._approval_counter) - buttons = [InlineKeyboardButton("✅ Allow Once", callback_data=f"ea:once:{approval_id}")] if not smart_denied and allow_session: - buttons.append( - InlineKeyboardButton("✅ Session", callback_data=f"ea:session:{approval_id}") - ) + buttons.append(InlineKeyboardButton("✅ Session", callback_data=f"ea:session:{approval_id}")) if allow_permanent: - buttons.append( - InlineKeyboardButton("✅ Always", callback_data=f"ea:always:{approval_id}") - ) + buttons.append(InlineKeyboardButton("✅ Always", callback_data=f"ea:always:{approval_id}")) buttons.append(InlineKeyboardButton("❌ Deny", callback_data=f"ea:deny:{approval_id}")) - # 2x2 rows keep labels readable on mobile (a 4-button row truncates). - rows = [buttons[i:i + 2] for i in range(0, len(buttons), 2)] - keyboard = InlineKeyboardMarkup(rows) - - msg = await self._send_control_message( - chat_id, text, parse_mode=ParseMode.HTML, reply_markup=keyboard, - thread_id=thread_id, metadata=metadata, reply_to_mode=self._reply_to_mode, - ) - self._approval_state[approval_id] = session_key - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] send_exec_approval failed: %s", self.name, _redact_telegram_error_text(e)) - return SendResult(success=False, error=_redact_telegram_error_text(e)) + return text, InlineKeyboardMarkup( + self._rows_of_two(buttons)), lambda msg: self._approval_state.__setitem__(approval_id, session_key) + return await self._send_prompt( + "send_exec_approval", chat_id, metadata, build, parse_mode=ParseMode.HTML, + thread_id=self._metadata_thread_id(metadata), reply_to_mode=self._reply_to_mode) 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: + self, chat_id: str, title: str, message: str, session_key: str, confirm_id: str, + metadata: Optional[Dict[str, Any]] = None) -> SendResult: """Render a three-button slash-command confirmation prompt.""" - if not self._bot: - return SendResult(success=False, error="Not connected") - - try: - preview = self.format_message(self._truncate_preview(message, 3800)) + def build(): keyboard = InlineKeyboardMarkup([ [ InlineKeyboardButton("✅ Approve Once", callback_data=f"sc:once:{confirm_id}"), - InlineKeyboardButton("🔒 Always Approve", callback_data=f"sc:always:{confirm_id}"), - ], + InlineKeyboardButton("🔒 Always Approve", callback_data=f"sc:always:{confirm_id}")], [InlineKeyboardButton("❌ Cancel", callback_data=f"sc:cancel:{confirm_id}")], - ]) - msg = await self._send_control_message( - chat_id, preview, parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard, - thread_id=self._metadata_thread_id(metadata), metadata=metadata, - reply_to_mode=self._reply_to_mode, - ) - self._slash_confirm_state[confirm_id] = session_key - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] send_slash_confirm failed: %s", self.name, _redact_telegram_error_text(e)) - return SendResult(success=False, error=_redact_telegram_error_text(e)) + ]) + preview = self.format_message(self._truncate_preview(message, 3800)) + return preview, keyboard, lambda msg: self._slash_confirm_state.__setitem__(confirm_id, session_key) + return await self._send_prompt( + "send_slash_confirm", chat_id, metadata, build, thread_id=self._metadata_thread_id(metadata), reply_to_mode=self._reply_to_mode) 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: - """Render a clarify prompt. - - With ``choices``: one numbered button per option plus "✏️ Other (type - answer)", which flips the entry into text-capture mode. Without: plain - question, no buttons; the gateway's text-intercept captures the next message. - """ - if not self._bot: - return SendResult(success=False, error="Not connected") - - try: + self, chat_id: str, question: str, choices: Optional[list], clarify_id: str, session_key: str, + metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Render a clarify prompt: numbered buttons per choice plus "✏️ Other (type answer)" (flips to + text-capture mode); without choices, plain question and the gateway text-intercept captures.""" + def build(): text = f"❓ {_html.escape(question)}" - thread_id = self._metadata_thread_id(metadata) - - if choices: - # Full option text goes in the body (mobile truncates button labels); - # buttons keep short numeric labels. - option_lines = "\n".join( - f"{i + 1}. {_html.escape(str(c))}" for i, c in enumerate(choices) - ) - text += f"\n\n{option_lines}" - keyboard = None if choices: + # Full option text in the body (mobile truncates button labels); buttons keep numeric labels. + text += "\n\n" + "\n".join(f"{i + 1}. {_html.escape(str(c))}" for i, c in enumerate(choices)) # Telegram caps callback_data at 64 bytes; keep "cl::" short. - rows = [ - [InlineKeyboardButton(str(idx + 1), callback_data=f"cl:{clarify_id}:{idx}")] - for idx in range(len(choices)) - ] + rows = [[InlineKeyboardButton(str(idx + 1), callback_data=f"cl:{clarify_id}:{idx}")] for idx in range(len(choices))] rows.append([InlineKeyboardButton("✏️ Other (type answer)", callback_data=f"cl:{clarify_id}:other")]) keyboard = InlineKeyboardMarkup(rows) + return text, keyboard, lambda msg: self._clarify_state.__setitem__(clarify_id, session_key) + return await self._send_prompt( + "send_clarify", chat_id, metadata, build, parse_mode=ParseMode.HTML, thread_id=self._metadata_thread_id(metadata)) - msg = await self._send_control_message( - chat_id, text, parse_mode=ParseMode.HTML, reply_markup=keyboard, - thread_id=thread_id, metadata=metadata, - ) - self._clarify_state[clarify_id] = session_key - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] send_clarify failed: %s", self.name, _redact_telegram_error_text(e)) - return SendResult(success=False, error=_redact_telegram_error_text(e)) - - async def send_model_picker( - self, - chat_id: str, - providers: list, - current_model: str, - current_provider: str, - session_key: str, - on_model_selected, - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: - """Send an inline-keyboard model picker: provider → model drill-down, edited in place.""" - if not self._bot: - return SendResult(success=False, error="Not connected") + @staticmethod + def _provider_get_label(): try: from hermes_cli.providers import get_label except ImportError: def get_label(slug): return slug - try: + return get_label + + async def send_model_picker( + self, chat_id: str, providers: list, current_model: str, current_provider: str, session_key: str, + on_model_selected, metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Send an inline-keyboard model picker: provider → model drill-down, edited in place.""" + def build(): keyboard, provider_page_info = self._build_provider_keyboard(providers, 0) - provider_label = get_label(current_provider) text = self.format_message( - f"⚙ *Model Configuration*\n\n" - f"Current model: `{current_model or 'unknown'}`\n" - f"Provider: {provider_label}\n\n" - f"Select a provider:{provider_page_info}" + self._provider_list_text(current_model, self._provider_get_label()(current_provider), provider_page_info) ) - msg = await self._send_control_message( - chat_id, text, parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard, - thread_id=metadata.get("thread_id") if metadata else None, metadata=metadata, - reply_to_mode=self._reply_to_mode, - ) - self._model_picker_state[str(chat_id)] = { - "msg_id": msg.message_id, "providers": providers, "session_key": session_key, - "on_model_selected": on_model_selected, "current_model": current_model, - "current_provider": current_provider, "provider_page": 0, - } - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] send_model_picker failed: %s", self.name, _redact_telegram_error_text(e)) - return SendResult(success=False, error=_redact_telegram_error_text(e)) + + def _remember(msg): + self._model_picker_state[str(chat_id)] = { + "msg_id": msg.message_id, "providers": providers, "session_key": session_key, "on_model_selected": on_model_selected, + "current_model": current_model, "current_provider": current_provider, "provider_page": 0} + return text, keyboard, _remember + return await self._send_prompt( + "send_model_picker", chat_id, metadata, build, thread_id=metadata.get("thread_id") if metadata else None, + reply_to_mode=self._reply_to_mode) _PROVIDER_PAGE_SIZE = 10 async def send_choice_picker( - self, - chat_id: str, - title: str, - choices: list, - session_key: str, - on_choice_selected, - metadata: Optional[Dict[str, Any]] = None, - ) -> SendResult: - """Flat inline-keyboard picker (one tap → one value) for /reasoning, /fast, etc. - - Each choice dict: ``{"value": str, "label": str, "is_current": bool}``. - """ - if not self._bot: - return SendResult(success=False, error="Not connected") - try: + self, chat_id: str, title: str, choices: list, session_key: str, on_choice_selected, + metadata: Optional[Dict[str, Any]] = None) -> SendResult: + """Flat inline-keyboard picker (one tap → one value) for /reasoning, /fast, etc. Each choice dict: + ``{"value": str, "label": str, "is_current": bool}``.""" + def build(): buttons = [] for i, choice in enumerate(choices): label = str(choice.get("label") or choice.get("value") or "") @@ -5127,21 +3604,23 @@ class TelegramAdapter(BasePlatformAdapter): buttons.append(InlineKeyboardButton(label, callback_data=f"cp:{i}")) if not buttons: return SendResult(success=False, error="No choices") - # Two buttons per row keeps labels readable on mobile. - keyboard = InlineKeyboardMarkup([buttons[i:i + 2] for i in range(0, len(buttons), 2)]) - msg = await self._send_control_message( - chat_id, self.format_message(title), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard, - thread_id=metadata.get("thread_id") if metadata else None, metadata=metadata, - reply_to_mode=self._reply_to_mode, - ) - self._choice_picker_state[str(chat_id)] = { - "msg_id": msg.message_id, "choices": choices, "session_key": session_key, - "on_choice_selected": on_choice_selected, - } - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] send_choice_picker failed: %s", self.name, _redact_telegram_error_text(e)) - return SendResult(success=False, error=_redact_telegram_error_text(e)) + keyboard = InlineKeyboardMarkup(self._rows_of_two(buttons)) + + def _remember(msg): + self._choice_picker_state[str(chat_id)] = { + "msg_id": msg.message_id, "choices": choices, "session_key": session_key, "on_choice_selected": on_choice_selected} + return self.format_message(title), keyboard, _remember + return await self._send_prompt( + "send_choice_picker", chat_id, metadata, build, thread_id=metadata.get("thread_id") if metadata else None, + reply_to_mode=self._reply_to_mode) + + async def _edit_result_text(self, query, result_text: str) -> None: + """Replace a picker message with ``result_text`` (MarkdownV2, then plain, then give up), keyboard removed.""" + try: + await query.edit_message_text(text=self.format_message(result_text), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=None) + except Exception: + with contextlib.suppress(Exception): + await query.edit_message_text(text=result_text, parse_mode=None, reply_markup=None) async def _handle_choice_picker_callback(self, query, data: str, chat_id: str) -> None: """Handle choice picker button taps (cp:).""" @@ -5149,15 +3628,11 @@ class TelegramAdapter(BasePlatformAdapter): if not state: await query.answer(text="Picker expired — run the command again.") return - # Same auth gate as approval buttons: strangers in a shared group must not - # flip session/config state via someone else's picker message. - if not await self._callback_authorized( - query, self._callback_ctx(query), "⛔ You are not authorized to change this setting." - ): + # Same auth gate as approval buttons: strangers in a shared group must not flip session state. + if not await self._callback_authorized(query, self._callback_ctx(query), "⛔ You are not authorized to change this setting."): return try: - idx = int(data[3:]) - choice = state["choices"][idx] + choice = state["choices"][int(data[3:])] except (ValueError, IndexError): await query.answer(text="Invalid selection.") return @@ -5170,15 +3645,7 @@ class TelegramAdapter(BasePlatformAdapter): except Exception as exc: logger.error("Choice picker selection failed: %s", exc) result_text = f"Error applying selection: {exc}" - try: - await query.edit_message_text( - text=self.format_message(result_text), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=None - ) - except Exception: - try: - await query.edit_message_text(text=result_text, parse_mode=None, reply_markup=None) - except Exception: - pass + await self._edit_result_text(query, result_text) await query.answer() self._choice_picker_state.pop(chat_id, None) @@ -5205,18 +3672,18 @@ class TelegramAdapter(BasePlatformAdapter): @staticmethod def _picker_back_cancel_row() -> list: - return [ - InlineKeyboardButton("◀ Back", callback_data="mb"), - InlineKeyboardButton("✗ Cancel", callback_data="mx"), - ] + return [InlineKeyboardButton("◀ Back", callback_data="mb"), InlineKeyboardButton("✗ Cancel", callback_data="mx")] + + def _paged_keyboard(self, buttons: list, page_meta: dict, nav_prefix: str, tail_row: list) -> tuple: + rows = self._rows_of_two(buttons) + if page_meta["total_pages"] > 1: + rows.append(self._picker_nav_row(page_meta["page"], page_meta["total_pages"], nav_prefix)) + rows.append(tail_row) + return InlineKeyboardMarkup(rows), page_meta["page_info"] def _build_provider_keyboard(self, providers: list, page: int = 0) -> tuple: - """Paginated top-level provider keyboard, folding provider families. - - Families (Kimi/Moonshot, MiniMax, xAI...) become one ``mpg:`` button that - drills into members; singles (and one-member groups) are direct ``mp:``. - Uses the shared ``group_providers`` fold so it matches the CLI picker. - """ + """Paginated top-level provider keyboard folding provider families (Kimi/Moonshot, MiniMax, xAI…) + into one ``mpg:`` button via the shared ``group_providers`` fold; singles are ``mp:``.""" try: from hermes_cli.models import group_providers except Exception: @@ -5237,15 +3704,9 @@ class TelegramAdapter(BasePlatformAdapter): if p is not None: buttons.append(self._provider_button(p)) else: - for p in providers: - buttons.append(self._provider_button(p)) - + buttons = [self._provider_button(p) for p in providers] page_buttons, page_meta = self._format_choice_page(buttons, page, self._PROVIDER_PAGE_SIZE) - rows = [page_buttons[i : i + 2] for i in range(0, len(page_buttons), 2)] - if page_meta["total_pages"] > 1: - rows.append(self._picker_nav_row(page_meta["page"], page_meta["total_pages"], "mpv")) - rows.append([InlineKeyboardButton("✗ Cancel", callback_data="mx")]) - return InlineKeyboardMarkup(rows), page_meta["page_info"] + return self._paged_keyboard(page_buttons, page_meta, "mpv", [InlineKeyboardButton("✗ Cancel", callback_data="mx")]) def _build_model_keyboard(self, models: list, page: int) -> tuple: """Build paginated model buttons. Returns (keyboard, page_info_text).""" @@ -5257,17 +3718,11 @@ class TelegramAdapter(BasePlatformAdapter): if len(short) > 38: short = short[:35] + "..." buttons.append(InlineKeyboardButton(short, callback_data=f"mm:{start + i}")) - rows = [buttons[i : i + 2] for i in range(0, len(buttons), 2)] - if page_meta["total_pages"] > 1: - rows.append(self._picker_nav_row(page_meta["page"], page_meta["total_pages"], "mg")) - rows.append(self._picker_back_cancel_row()) - return InlineKeyboardMarkup(rows), page_meta["page_info"] + return self._paged_keyboard(buttons, page_meta, "mg", self._picker_back_cancel_row()) async def _picker_edit(self, query, text_md: str, keyboard) -> None: """Re-render the picker message in place (MarkdownV2) and ack the tap.""" - await query.edit_message_text( - text=self.format_message(text_md), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard, - ) + await query.edit_message_text(text=self.format_message(text_md), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard) await query.answer() async def _picker_show_models(self, query, state: dict, page: int) -> None: @@ -5281,11 +3736,12 @@ class TelegramAdapter(BasePlatformAdapter): total = provider.get("total_models", len(models)) if provider else len(models) shown = len(models) extra = f"\n_{total - shown} more available — type `/model ` directly_" if total > shown else "" - await self._picker_edit( - query, - f"⚙ *Model Configuration*\n\nProvider: *{pname}*{page_info}\nSelect a model:{extra}", - keyboard, - ) + await self._picker_edit(query, f"⚙ *Model Configuration*\n\nProvider: *{pname}*{page_info}\nSelect a model:{extra}", keyboard) + + @staticmethod + def _provider_list_text(current_model: str, provider_label: str, page_info: str) -> str: + return (f"⚙ *Model Configuration*\n\nCurrent model: `{current_model or 'unknown'}`\n" + f"Provider: {provider_label}\n\nSelect a provider:{page_info}") async def _picker_show_providers(self, query, state: dict, page: int, get_label) -> None: """Render the (folded, paginated) provider list.""" @@ -5294,14 +3750,7 @@ class TelegramAdapter(BasePlatformAdapter): provider_label = get_label(state["current_provider"]) except Exception: provider_label = state["current_provider"] - await self._picker_edit( - query, - f"⚙ *Model Configuration*\n\n" - f"Current model: `{state['current_model'] or 'unknown'}`\n" - f"Provider: {provider_label}\n\n" - f"Select a provider:{provider_page_info}", - keyboard, - ) + await self._picker_edit(query, self._provider_list_text(state["current_model"], provider_label, provider_page_info), keyboard) async def _picker_selection(self, query, state: dict, raw_idx: str) -> Optional[tuple]: """Resolve ``mm:``/``mc:`` index → ``(idx, model_id, provider_slug, callback)``; answers + None on error.""" @@ -5329,33 +3778,26 @@ class TelegramAdapter(BasePlatformAdapter): logger.error("Model picker switch failed: %s", exc) result_text = f"Error switching model: {exc}" switch_failed = True - try: - await query.edit_message_text( - text=self.format_message(result_text), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=None - ) - except Exception: - # Markdown parse failure — retry as plain text - try: - await query.edit_message_text(text=result_text, parse_mode=None, reply_markup=None) - except Exception: - pass + await self._edit_result_text(query, result_text) await query.answer(text="Switch failed." if switch_failed else "Model switched!") self._model_picker_state.pop(chat_id, None) + @staticmethod + async def _parse_page(query, raw: str) -> Optional[int]: + try: + return int(raw) + except ValueError: + await query.answer(text="Invalid page.") + return None + async def _handle_model_picker_callback(self, query, data: str, chat_id: str) -> None: """Handle model picker callbacks (mp:/mpg:/mpv:/mm:/mc:/mb/mx/mg:).""" state = self._model_picker_state.get(chat_id) if not state: await query.answer(text="Picker expired — use /model again.") return - try: - from hermes_cli.providers import get_label - except ImportError: - def get_label(slug): - return slug - - if data.startswith("mp:"): - # Provider selected: show model buttons (page 0) + get_label = self._provider_get_label() + if data.startswith("mp:"): # provider selected: show model buttons (page 0) provider_slug = data[3:] provider = next((p for p in state["providers"] if p["slug"] == provider_slug), None) if not provider: @@ -5365,36 +3807,21 @@ class TelegramAdapter(BasePlatformAdapter): state["selected_provider_name"] = provider.get("name", provider_slug) state["model_list"] = provider.get("models", []) await self._picker_show_models(query, state, 0) - - elif data.startswith("mg:"): - # Model page navigation - try: - page = int(data[3:]) - except ValueError: - await query.answer(text="Invalid page.") - return - await self._picker_show_models(query, state, page) - - elif data.startswith("mpv:"): - # Provider page navigation - try: - page = int(data[4:]) - except ValueError: - await query.answer(text="Invalid page.") - return - state["provider_page"] = page - await self._picker_show_providers(query, state, page, get_label) - - elif data.startswith("mc:"): - # Expensive model confirmed: perform the switch + elif data.startswith("mg:"): # model page navigation + page = await self._parse_page(query, data[3:]) + if page is not None: + await self._picker_show_models(query, state, page) + elif data.startswith("mpv:"): # provider page navigation + page = await self._parse_page(query, data[4:]) + if page is not None: + state["provider_page"] = page + await self._picker_show_providers(query, state, page, get_label) + elif data.startswith("mc:"): # expensive model confirmed: perform the switch sel = await self._picker_selection(query, state, data[3:]) - if sel is None: - return - _idx, model_id, provider_slug, callback = sel - await self._picker_switch(query, chat_id, model_id, provider_slug, callback) - - elif data.startswith("mm:"): - # Model selected: warn if expensive, else perform the switch + if sel is not None: + _idx, model_id, provider_slug, callback = sel + await self._picker_switch(query, chat_id, model_id, provider_slug, callback) + elif data.startswith("mm:"): # model selected: warn if expensive, else perform the switch sel = await self._picker_selection(query, state, data[3:]) if sel is None: return @@ -5402,27 +3829,19 @@ class TelegramAdapter(BasePlatformAdapter): try: from hermes_cli.model_selection_guards import combined_selection_warning # Pricing lookup may hit models.dev on a cache miss — keep it off the event loop. - warning = await asyncio.to_thread( - combined_selection_warning, model_id, provider=provider_slug - ) + warning = await asyncio.to_thread(combined_selection_warning, model_id, provider=provider_slug) except Exception: warning = None if warning is not None: keyboard = InlineKeyboardMarkup([ - [InlineKeyboardButton("Switch anyway", callback_data=f"mc:{idx}")], - self._picker_back_cancel_row(), - ]) + [InlineKeyboardButton("Switch anyway", callback_data=f"mc:{idx}")], self._picker_back_cancel_row()]) await query.edit_message_text( text=self.format_message(f"⚠ *{warning.title}*\n\n{warning.message}"), - parse_mode=ParseMode.MARKDOWN_V2, - reply_markup=keyboard, - ) + parse_mode=ParseMode.MARKDOWN_V2, reply_markup=keyboard) await query.answer(text="Confirm model selection") return await self._picker_switch(query, chat_id, model_id, provider_slug, callback) - - elif data.startswith("mpg:"): - # Provider group selected: show member providers + elif data.startswith("mpg:"): # provider group selected: show member providers group_id = data[4:] try: from hermes_cli.models import PROVIDER_GROUPS @@ -5434,60 +3853,44 @@ class TelegramAdapter(BasePlatformAdapter): if not members: await query.answer(text="Group not found.") return - buttons = [self._provider_button(p) for p in members] - rows = [buttons[i : i + 2] for i in range(0, len(buttons), 2)] + rows = self._rows_of_two([self._provider_button(p) for p in members]) rows.append(self._picker_back_cancel_row()) await self._picker_edit( - query, - f"⚙ *Model Configuration*\n\nProvider family: *{_label or group_id}*\n\nSelect a provider:", - InlineKeyboardMarkup(rows), - ) - - elif data == "mb": - # Back to provider list (folds groups) - page = int(state.get("provider_page", 0) or 0) - await self._picker_show_providers(query, state, page, get_label) - + query, f"⚙ *Model Configuration*\n\nProvider family: *{_label or group_id}*\n\nSelect a provider:", + InlineKeyboardMarkup(rows)) + elif data == "mb": # back to provider list (folds groups) + await self._picker_show_providers(query, state, int(state.get("provider_page", 0) or 0), get_label) elif data == "mx": self._model_picker_state.pop(chat_id, None) await query.edit_message_text(text="Model selection cancelled.", reply_markup=None) await query.answer() - else: await query.answer() # e.g. page-counter button "mx:noop" async def _notify_clarify_expired(self, query, user_display: str) -> None: - """Tell the user a clarify tap arrived too late (entry evicted by ``clarify_timeout`` - or gateway restarted) — otherwise the tap leaves a misleading ✓ the agent never sees.""" - try: + """Tell the user a clarify tap arrived too late (entry evicted or gateway restarted) — otherwise + the tap leaves a misleading ✓ the agent never sees.""" + with contextlib.suppress(Exception): await query.answer(text="⚠️ This prompt expired — please /retry.") - except Exception: - pass - try: - await query.edit_message_text( - text=( - f"❓ {_html.escape(query.message.text or '')}\n\n" - "⚠️ This question expired or the session reset — please /retry." - ), - parse_mode=ParseMode.HTML, - reply_markup=None, - ) - except Exception: - pass + await self._edit_html_quiet( + query, f"❓ {_html.escape(query.message.text or '')}\n\n⚠️ This question expired or the session reset — please /retry.") + + @staticmethod + async def _edit_html_quiet(query, text: str) -> None: + """HTML edit with the keyboard removed; failures ignored (non-fatal).""" + with contextlib.suppress(Exception): + await query.edit_message_text(text=text, parse_mode=ParseMode.HTML, reply_markup=None) + + async def _edit_md_quiet(self, query, text_md: str) -> None: + """MarkdownV2 edit with the keyboard removed; failures ignored (non-fatal).""" + with contextlib.suppress(Exception): + await query.edit_message_text(text=self.format_message(text_md), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=None) async def _handle_inline_query(self, update: "Update", context: "ContextTypes.DEFAULT_TYPE") -> None: - """Answer ``@botname `` with a searchable command/skill picker. - - The BotCommand menu is capped (100/scope, ~4KB; 60-slot Hermes default), so most - skill commands never fit the ``/`` menu. Inline mode is uncapped: results are computed - per keystroke, paginated 50 at a time (Telegram's per-answer max). Tapping a result - sends the command text into the chat as the user, so dispatch flows through the normal - command path — this handler only *offers* text and is read-only by construction. - - Inline queries arrive from ANY chat (even ones the bot isn't in), so results are only - served to users passing the same auth as inline-button callbacks; unauthorized users - get an empty list so the installed-skill catalog is not leaked. - """ + """Answer ``@botname `` with a searchable command/skill picker (the ``/`` menu is capped at + 60 slots). Results are computed per keystroke, 50 per page; tapping sends ``/cmd`` text as the + user, so dispatch flows through the normal command path. Inline queries arrive from ANY chat, so + unauthorized users get an empty list (the skill catalog is not leaked).""" inline_query = getattr(update, "inline_query", None) if inline_query is None: return @@ -5496,8 +3899,7 @@ class TelegramAdapter(BasePlatformAdapter): try: # No chat context on inline queries — authorize on user identity alone, DM-shaped. authorized = bool(user_id) and self._is_callback_user_authorized( - user_id, chat_id=user_id, chat_type="private", user_name=getattr(from_user, "username", None) - ) + user_id, chat_id=user_id, chat_type="private", user_name=getattr(from_user, "username", None)) except Exception: logger.debug("[%s] inline picker auth check failed", self.name, exc_info=True) authorized = False @@ -5510,19 +3912,15 @@ class TelegramAdapter(BasePlatformAdapter): return try: from telegram import InlineQueryResultArticle, InputTextMessageContent - from plugins.platforms.telegram.inline_picker import ( - CACHE_TIME_SECONDS as _CACHE, build_inline_results, - ) + from plugins.platforms.telegram.inline_picker import CACHE_TIME_SECONDS as _CACHE, build_inline_results results, next_offset = build_inline_results( - getattr(inline_query, "query", "") or "", offset=getattr(inline_query, "offset", "") or "" - ) + getattr(inline_query, "query", "") or "", offset=getattr(inline_query, "offset", "") or "") articles = [ InlineQueryResultArticle( id=r["id"], title=r["title"], description=r["description"], - input_message_content=InputTextMessageContent(r["message_text"]), - ) + input_message_content=InputTextMessageContent(r["message_text"])) for r in results - ] + ] # is_personal: catalogs differ per user (auth, disabled skills) — never share cached pages. await inline_query.answer(articles, cache_time=_CACHE, is_personal=True, next_offset=next_offset) except Exception: @@ -5534,22 +3932,15 @@ class TelegramAdapter(BasePlatformAdapter): query_message = getattr(query, "message", None) query_chat = getattr(query_message, "chat", None) return { - "chat_id": getattr(query_message, "chat_id", None), - "chat_type": getattr(query_chat, "type", None), - "thread_id": getattr(query_message, "message_thread_id", None), - "user_name": getattr(query.from_user, "first_name", None), - } + "chat_id": getattr(query_message, "chat_id", None), "chat_type": getattr(query_chat, "type", None), + "thread_id": getattr(query_message, "message_thread_id", None), "user_name": getattr(query.from_user, "first_name", None)} async def _callback_authorized(self, query, cb: Dict[str, Any], denial_text: str) -> bool: """Gate a button tap on the callback allowlist; answers ``denial_text`` when refused.""" - caller_id = str(getattr(query.from_user, "id", "")) if self._is_callback_user_authorized( - caller_id, - chat_id=cb["chat_id"], + str(getattr(query.from_user, "id", "")), chat_id=cb["chat_id"], chat_type=str(cb["chat_type"]) if cb["chat_type"] is not None else None, - thread_id=str(cb["thread_id"]) if cb["thread_id"] is not None else None, - user_name=cb["user_name"], - ): + thread_id=str(cb["thread_id"]) if cb["thread_id"] is not None else None, user_name=cb["user_name"]): return True await query.answer(text=denial_text) return False @@ -5562,27 +3953,31 @@ class TelegramAdapter(BasePlatformAdapter): data = query.data cb = self._callback_ctx(query) # Model picker / generic choice picker (/reasoning, /fast) need a chat id. - if data.startswith(("mp:", "mpg:", "mpv:", "mm:", "mc:", "mb", "mx", "mg:")): - chat_id = str(query.message.chat_id) if query.message else None - if chat_id: - await self._handle_model_picker_callback(query, data, chat_id) - return - if data.startswith("cp:"): - chat_id = str(query.message.chat_id) if query.message else None - if chat_id: - await self._handle_choice_picker_callback(query, data, chat_id) - return + for prefixes, handler in ( + (("mp:", "mpg:", "mpv:", "mm:", "mc:", "mb", "mx", "mg:"), self._handle_model_picker_callback), + (("cp:",), self._handle_choice_picker_callback)): + if data.startswith(prefixes): + chat_id = str(query.message.chat_id) if query.message else None + if chat_id: + await handler(query, data, chat_id) + return for prefix, handler in ( - ("gt:", self._handle_gmail_triage_callback), - ("ea:", self._handle_exec_approval_callback), - ("sc:", self._handle_slash_confirm_callback), - ("cl:", self._handle_clarify_callback), - ("update_prompt:", self._handle_update_prompt_callback), - ): + ("gt:", self._handle_gmail_triage_callback), ("ea:", self._handle_exec_approval_callback), + ("sc:", self._handle_slash_confirm_callback), ("cl:", self._handle_clarify_callback), + ("update_prompt:", self._handle_update_prompt_callback)): if data.startswith(prefix): await handler(query, data, cb) return + async def _claim_callback_state(self, query, cb: Dict[str, Any], state: dict, key, denial: str, resolved: str, *, pop: bool = True): + """Auth-gate a button tap, then claim its pending entry; None (after answering) when refused or expired.""" + if not await self._callback_authorized(query, cb, denial): + return None + session_key = state.pop(key, None) if pop else state.get(key) + if not session_key: + await query.answer(text=resolved) + return session_key + async def _handle_exec_approval_callback(self, query, data: str, cb: Dict[str, Any]) -> None: """``ea::`` — resolve a pending exec approval.""" parts = data.split(":", 2) @@ -5594,47 +3989,34 @@ class TelegramAdapter(BasePlatformAdapter): except (ValueError, IndexError): await query.answer(text="Invalid approval data.") return - if not await self._callback_authorized(query, cb, "⛔ You are not authorized to approve commands."): - return - session_key = self._approval_state.pop(approval_id, None) + session_key = await self._claim_callback_state( + query, cb, self._approval_state, approval_id, "⛔ You are not authorized to approve commands.", + "This approval has already been resolved.") if not session_key: - await query.answer(text="This approval has already been resolved.") return user_display = getattr(query.from_user, "first_name", "User") - # Resolve FIRST (unblocks the agent thread), render after: a tap landing after the - # wait timed out (count == 0) must NOT claim "Approved" — the command was already denied. + # Resolve FIRST (unblocks the agent thread), render after: a tap landing after the wait timed out + # (count == 0) must NOT claim "Approved" — the command was already denied. try: from tools.approval import resolve_gateway_approval count = resolve_gateway_approval(session_key, choice) logger.info( - "Telegram button resolved %d approval(s) for session %s (choice=%s, user=%s)", - count, session_key, choice, user_display, - ) + "Telegram button resolved %d approval(s) for session %s (choice=%s, user=%s)", count, session_key, choice, user_display) except Exception as exc: logger.error("Failed to resolve gateway approval from Telegram button: %s", exc) count = 0 if count: label_map = { - "once": "✅ Approved once", "session": "✅ Approved for session", - "always": "✅ Approved permanently", "deny": "❌ Denied", + "once": "✅ Approved once", "session": "✅ Approved for session", "always": "✅ Approved permanently", "deny": "❌ Denied", } label = label_map.get(choice, "Resolved") edit_text = f"{label} by {user_display}" else: label = "⌛ Approval expired" - edit_text = ( - f"{label} — no command was waiting. " - f"It already timed out (and was denied) or was resolved elsewhere." - ) + edit_text = f"{label} — no command was waiting. It already timed out (and was denied) or was resolved elsewhere." await query.answer(text=label) - try: - await query.edit_message_text( - text=self.format_message(edit_text), parse_mode=ParseMode.MARKDOWN_V2, reply_markup=None - ) - except Exception: - pass # non-fatal if edit fails - # Typing was paused when the approval was sent (gateway/run.py); the text /approve - # and /deny paths resume it too — without this, typing stays paused for the turn. + await self._edit_md_quiet(query, edit_text) + # Typing was paused when the approval was sent; the text /approve and /deny paths resume it too. if count and cb["chat_id"] is not None: self.resume_typing_for_chat(str(cb["chat_id"])) @@ -5645,60 +4027,41 @@ class TelegramAdapter(BasePlatformAdapter): return choice = parts[1] # once, always, cancel confirm_id = parts[2] - if not await self._callback_authorized(query, cb, "⛔ You are not authorized to answer this prompt."): - return - session_key = self._slash_confirm_state.pop(confirm_id, None) + session_key = await self._claim_callback_state( + query, cb, self._slash_confirm_state, confirm_id, "⛔ You are not authorized to answer this prompt.", + "This prompt has already been resolved.") if not session_key: - await query.answer(text="This prompt has already been resolved.") return label_map = {"once": "✅ Approved once", "always": "🔒 Always approve", "cancel": "❌ Cancelled"} user_display = getattr(query.from_user, "first_name", "User") label = label_map.get(choice, "Resolved") await query.answer(text=label) - try: - await query.edit_message_text( - text=self.format_message(f"{label} by {user_display}"), - parse_mode=ParseMode.MARKDOWN_V2, - reply_markup=None, - ) - except Exception: - pass - # The runner stored a handler keyed by session_key; run it and, if it returns a - # string, send that as a follow-up in the same chat. + await self._edit_md_quiet(query, f"{label} by {user_display}") + # The runner stored a handler keyed by session_key; run it and send any returned text as a follow-up. try: from tools import slash_confirm as _slash_confirm_mod result_text = await _slash_confirm_mod.resolve(session_key, confirm_id, choice) if result_text and query.message: - # Inherit the prompt's topic: forums use message_thread_id; private DM-topic - # lanes need both the topic id and the prompt reply anchor. + # Inherit the prompt's topic: forums use message_thread_id; private DM-topic lanes need + # both the topic id and the prompt reply anchor. thread_id = getattr(query.message, "message_thread_id", None) - chat = getattr(query.message, "chat", None) - chat_type = getattr(chat, "type", None) + chat_type = getattr(getattr(query.message, "chat", None), "type", None) prompt_message_id = getattr(query.message, "message_id", None) send_kwargs: Dict[str, Any] = { - "chat_id": int(query.message.chat_id), - "text": self.format_message(result_text), - "parse_mode": ParseMode.MARKDOWN_V2, - **self._link_preview_kwargs(), - } - chat_type_value = getattr(chat_type, "value", chat_type) - is_private_chat = str(chat_type_value).lower() in { - "private", str(ChatType.PRIVATE).lower(), - str(getattr(ChatType.PRIVATE, "value", ChatType.PRIVATE)).lower(), - } - if thread_id is not None and is_private_chat and prompt_message_id is not None: - reply_to_id = int(prompt_message_id) - send_kwargs["reply_to_message_id"] = reply_to_id + "chat_id": int(query.message.chat_id), "text": self.format_message(result_text), + "parse_mode": ParseMode.MARKDOWN_V2, **self._link_preview_kwargs()} + is_private_chat = str(getattr(chat_type, "value", chat_type)).lower() in { + "private", str(ChatType.PRIVATE).lower(), str(getattr(ChatType.PRIVATE, "value", ChatType.PRIVATE)).lower()} + if thread_id is not None: + meta: Dict[str, Any] = {"thread_id": str(thread_id)} + reply_to_id = None + if is_private_chat and prompt_message_id is not None: + reply_to_id = send_kwargs["reply_to_message_id"] = int(prompt_message_id) + meta["telegram_dm_topic_reply_fallback"] = True send_kwargs.update(self._thread_kwargs_for_send( - str(query.message.chat_id), str(thread_id), - {"thread_id": str(thread_id), "telegram_dm_topic_reply_fallback": True}, - reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode, - )) - elif thread_id is not None: - send_kwargs.update(self._thread_kwargs_for_send( - str(query.message.chat_id), str(thread_id), {"thread_id": str(thread_id)}, - reply_to_mode=self._reply_to_mode, - )) + str( + query.message.chat_id + ), str(thread_id), meta, reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode)) await self._send_message_with_thread_fallback(**send_kwargs) except Exception as exc: logger.error("[%s] slash-confirm callback failed: %s", self.name, exc, exc_info=True) @@ -5710,18 +4073,15 @@ class TelegramAdapter(BasePlatformAdapter): return clarify_id = parts[1] choice_token = parts[2] - if not await self._callback_authorized(query, cb, "⛔ You are not authorized to answer this prompt."): - return - session_key = self._clarify_state.get(clarify_id) + session_key = await self._claim_callback_state( + query, cb, self._clarify_state, clarify_id, "⛔ You are not authorized to answer this prompt.", + "This prompt has already been resolved.", pop=False) if not session_key: - await query.answer(text="This prompt has already been resolved.") return user_display = getattr(query.from_user, "first_name", "User") - if choice_token == "other": - # Flip to text-capture: the gateway's text-intercept resolves the clarify with the - # next message in this session. Do NOT pop _clarify_state yet — still needed if - # the user is slow and the entry gets cleared by something else. + # Flip to text-capture: the gateway's text-intercept resolves the clarify with the next message. + # Do NOT pop _clarify_state yet — still needed if the entry gets cleared by something else. flipped = False try: from tools.clarify_gateway import mark_awaiting_text @@ -5734,16 +4094,9 @@ class TelegramAdapter(BasePlatformAdapter): await self._notify_clarify_expired(query, user_display) return await query.answer(text="✏️ Type your answer in the chat.") - try: - await query.edit_message_text( - text=f"❓ {query.message.text or ''}\n\nAwaiting typed response from {_html.escape(user_display)}…", - parse_mode=ParseMode.HTML, - reply_markup=None, - ) - except Exception: - pass + await self._edit_html_quiet( + query, f"❓ {query.message.text or ''}\n\nAwaiting typed response from {_html.escape(user_display)}…") return - # Numeric choice → resolve immediately with the chosen text try: idx = int(choice_token) @@ -5759,8 +4112,7 @@ class TelegramAdapter(BasePlatformAdapter): except Exception: resolved_text = None if resolved_text is None: - # Race (timeout / session reset): entry vanished. Echo the index so the agent - # at least sees an intentional response rather than nothing. + # Race (timeout / session reset): echo the index so the agent sees an intentional response. resolved_text = f"choice {idx + 1}" self._clarify_state.pop(clarify_id, None) try: @@ -5771,24 +4123,13 @@ class TelegramAdapter(BasePlatformAdapter): resolved = False if resolved: await query.answer(text=f"✓ {resolved_text[:60]}") - try: - await query.edit_message_text( - text=f"❓ {_html.escape(query.message.text or '')}\n\n{_html.escape(user_display)}: {_html.escape(resolved_text)}", - parse_mode=ParseMode.HTML, - reply_markup=None, - ) - except Exception: - pass - logger.info( - "Telegram clarify button resolved (id=%s, choice=%r, user=%s)", - clarify_id, resolved_text, user_display, - ) + await self._edit_html_quiet( + query, f"❓ {_html.escape(query.message.text or '')}\n\n{_html.escape(user_display)}: {_html.escape(resolved_text)}") + logger.info("Telegram clarify button resolved (id=%s, choice=%r, user=%s)", clarify_id, resolved_text, user_display) else: # Entry evicted / gateway restarted between ask and tap. await self._notify_clarify_expired(query, user_display) - logger.warning( - "Telegram clarify button: resolve_gateway_clarify returned False (id=%s)", clarify_id - ) + logger.warning("Telegram clarify button: resolve_gateway_clarify returned False (id=%s)", clarify_id) async def _handle_update_prompt_callback(self, query, data: str, cb: Dict[str, Any]) -> None: """``update_prompt:`` — forward the answer to the update process.""" @@ -5796,32 +4137,20 @@ class TelegramAdapter(BasePlatformAdapter): if not await self._callback_authorized(query, cb, "⛔ You are not authorized to answer update prompts."): return await query.answer(text=f"Sent '{answer}' to the update process.") - label = "Yes" if answer == "y" else "No" - try: - await query.edit_message_text( - text=self.format_message(f"⚕ Update prompt answered: *{label}*"), - parse_mode=ParseMode.MARKDOWN_V2, - reply_markup=None, - ) - except Exception: - pass # non-fatal if edit fails + await self._edit_md_quiet(query, f"⚕ Update prompt answered: *{'Yes' if answer == 'y' else 'No'}*") try: from hermes_constants import get_hermes_home - home = get_hermes_home() - response_path = home / ".update_response" + response_path = get_hermes_home() / ".update_response" tmp = response_path.with_suffix(".tmp") tmp.write_text(answer, encoding="utf-8") tmp.replace(response_path) - logger.info( - "Telegram update prompt answered '%s' by user %s", - answer, getattr(query.from_user, "id", "unknown"), - ) + logger.info("Telegram update prompt answered '%s' by user %s", answer, getattr(query.from_user, "id", "unknown")) except Exception as exc: logger.error("Failed to write update response from callback: %s", exc) - # `gt:` -> (script in ~/.hermes/scripts/gmail-triage/, extra-args, success-label, is_state). - # The callback `arg` is always the first positional arg. is_state=True = sticky sender-rule - # change that keeps the keyboard tappable; False = per-email one-shot that strips it on success. + # `gt:` -> (script in ~/.hermes/scripts/gmail-triage/, extra-args, success-label, is_state). The callback + # `arg` is always the first positional arg. is_state=True keeps the keyboard tappable (sticky sender rule); + # False strips it on success (per-email one-shot). _GT_VERB_DISPATCH = { "send": ("send-draft.sh", [], "✓ sent draft", False), "archive": ("archive.sh", [], "✓ archived", False), @@ -5832,8 +4161,7 @@ class TelegramAdapter(BasePlatformAdapter): "trust": ("trusted-ops-add.sh", ["email"], "✓ trusted", True), "trust-domain": ("trusted-ops-add.sh", ["domain"], "✓ trusted domain", True), "vip": ("vip-add.sh", ["email"], "✓ marked VIP", True), - "vip-domain": ("vip-add.sh", ["domain"], "✓ marked VIP domain", True), - } + "vip-domain": ("vip-add.sh", ["domain"], "✓ marked VIP domain", True)} async def _handle_gmail_triage_callback(self, query, data: str, cb: Dict[str, Any]) -> None: """Dispatch a gmail-triage inline-button callback (gt:verb:arg).""" @@ -5854,12 +4182,10 @@ class TelegramAdapter(BasePlatformAdapter): await query.answer(text=f"❌ {script_name} missing") logger.error("[%s] gmail-triage script missing: %s", self.name, script_path) return - cmd = [str(script_path), arg, *extra_args] success = False try: proc = await asyncio.create_subprocess_exec( - *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE - ) + str(script_path), arg, *extra_args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE) _stdout_bytes, stderr_bytes = await asyncio.wait_for(proc.communicate(), timeout=60) if proc.returncode == 0: label = success_label @@ -5870,34 +4196,21 @@ class TelegramAdapter(BasePlatformAdapter): last_line = stderr_text.splitlines()[-1] if stderr_text else f"exit {proc.returncode}" label = f"❌ {verb} failed: {last_line[:80]}" logger.error( - "[%s] gmail-triage callback failed: verb=%s arg=%s rc=%s stderr=%s", - self.name, verb, arg, proc.returncode, stderr_text, - ) + "[%s] gmail-triage callback failed: verb=%s arg=%s rc=%s stderr=%s", self.name, verb, arg, proc.returncode, stderr_text) except asyncio.TimeoutError: label = f"❌ {verb} timed out" logger.error("[%s] gmail-triage callback timed out: verb=%s arg=%s", self.name, verb, arg) except Exception as exc: label = f"❌ {verb} error: {exc}" - logger.error( - "[%s] gmail-triage callback exception: verb=%s arg=%s err=%s", - self.name, verb, arg, exc, exc_info=True, - ) - + logger.error("[%s] gmail-triage callback exception: verb=%s arg=%s err=%s", self.name, verb, arg, exc, exc_info=True) await query.answer(text=label) if not success: return - user_display = getattr(query.from_user, "first_name", "User") original_text = (query.message.text or "") if query.message else "" - appended = f"{original_text}\n— {label} by {user_display}" - try: - if is_state_verb: - # Sticky state change: KEEP keyboard so further actions can stack on this email. - await query.edit_message_text(text=appended) - else: - # One-shot: strip keyboard so the action can't fire twice. - await query.edit_message_text(text=appended, reply_markup=None) - except Exception: - pass + appended = f"{original_text}\n— {label} by {getattr(query.from_user, 'first_name', 'User')}" + # Sticky state verbs keep the keyboard so further actions can stack; one-shots strip it (can't fire twice). + with contextlib.suppress(Exception): + await query.edit_message_text(text=appended, **({} if is_state_verb else {"reply_markup": None})) def _missing_media_path_error(self, label: str, path: str) -> str: """File-not-found error for MEDIA delivery; /workspace-style paths often exist only in the sandbox.""" @@ -5905,68 +4218,88 @@ class TelegramAdapter(BasePlatformAdapter): if path.startswith(("/workspace/", "/output/", "/outputs/")): error += ( " (path may only exist inside the Docker sandbox. " - "Bind-mount a host directory and emit the host-visible " - "path in MEDIA: for gateway file delivery.)" - ) + "Bind-mount a host directory and emit the host-visible path in MEDIA: for gateway file delivery.)") return error def _telegram_media_too_large_note(self, label: str, file_size: Any, max_bytes: int) -> str: limit_mb = max(1, max_bytes // (1024 * 1024)) try: - size_mb = int(file_size or 0) / (1024 * 1024) - size_text = f"{size_mb:.1f} MB" + size_text = f"{int(file_size or 0) / (1024 * 1024):.1f} MB" except (TypeError, ValueError): size_text = "unknown size" - return ( - f"[Telegram {label} skipped: file size {size_text} exceeds the " - f"{limit_mb} MB limit. Ask the user to send a smaller file.]" - ) + return f"[Telegram {label} skipped: file size {size_text} exceeds the {limit_mb} MB limit. Ask the user to send a smaller file.]" + + @staticmethod + def _int_or_zero(value: Any) -> int: + try: + return int(value or 0) + except (TypeError, ValueError): + return 0 def _telegram_media_size_allowed(self, source: Any, label: str) -> tuple[bool, Optional[str]]: """Validate Telegram media size before downloading into memory.""" max_bytes = int(getattr(self, "_max_doc_bytes", 20 * 1024 * 1024) or 20 * 1024 * 1024) - file_size = getattr(source, "file_size", None) - try: - size = int(file_size or 0) - except (TypeError, ValueError): - size = 0 - if size <= 0: - return True, None - if size <= max_bytes: + size = self._int_or_zero(getattr(source, "file_size", None)) + if size <= 0 or size <= max_bytes: return True, None return False, self._telegram_media_too_large_note(label, size, max_bytes) def _media_send_kwargs( - self, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], - ) -> tuple[Optional[int], Dict[str, Any]]: + self, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]]) -> tuple[Optional[int], Dict[str, Any]]: """Return ``(reply_to_id, base_kwargs)`` shared by every native media send.""" reply_to_id = self._reply_to_message_id_for_send(reply_to, metadata, reply_to_mode=self._reply_to_mode) thread_kwargs = self._thread_kwargs_for_send( - chat_id, self._metadata_thread_id(metadata), metadata, - reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode, - ) + chat_id, self._metadata_thread_id(metadata), metadata, reply_to_message_id=reply_to_id, reply_to_mode=self._reply_to_mode) return reply_to_id, { - "chat_id": normalize_telegram_chat_id(chat_id), - "reply_to_message_id": reply_to_id, - "read_timeout": _MEDIA_SEND_READ_TIMEOUT, - **thread_kwargs, - **self._notification_kwargs(metadata), - } + "chat_id": normalize_telegram_chat_id(chat_id), "reply_to_message_id": reply_to_id, + "read_timeout": _MEDIA_SEND_READ_TIMEOUT, **thread_kwargs, **self._notification_kwargs(metadata)} async def _send_media( - self, send_fn: Any, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], - media_label: str, reset_media: Optional[Any] = None, **media_kwargs: Any, - ) -> Any: + self, send_fn: Any, chat_id: str, reply_to: Optional[str], metadata: Optional[Dict[str, Any]], media_label: str, + reset_media: Optional[Any] = None, **media_kwargs: Any) -> Any: """Send one native media payload with thread routing + DM-topic anchor retry.""" reply_to_id, kwargs = self._media_send_kwargs(chat_id, reply_to, metadata) return await self._send_with_dm_topic_reply_anchor_retry( - send_fn, {**kwargs, **media_kwargs}, metadata, reply_to_id, media_label, reset_media=reset_media, - ) + send_fn, {**kwargs, **media_kwargs}, metadata, reply_to_id, media_label, reset_media=reset_media) + + @staticmethod + def _caption_1024(caption: Optional[str]) -> Optional[str]: + return caption[:1024] if caption else None + + async def _send_voice_bubble(self, audio_file, chat_id, reply_to, metadata, caption, duration_secs): + """sendVoice with caption variants: MarkdownV2 when it fits 1024 chars, plain fallback when the + Bot API rejects the entities; anything else is a real error.""" + _caption_variants: List[tuple] = [] + if caption: + try: + _formatted_caption = self.format_message(caption) + if utf16_len(_formatted_caption) <= 1024: + _caption_variants.append((_formatted_caption, ParseMode.MARKDOWN_V2)) + except Exception: + logger.debug("[%s] voice caption MarkdownV2 formatting failed; sending plain caption", self.name, exc_info=True) + _caption_variants.append((caption[:1024], None)) + else: + _caption_variants.append((None, None)) + _last_parse_error: Optional[Exception] = None + for _cap_text, _cap_parse_mode in _caption_variants: + try: + return await self._send_media( + self._bot.send_voice, chat_id, reply_to, metadata, "voice", reset_media=lambda: audio_file.seek(0), + voice=audio_file, caption=_cap_text, parse_mode=_cap_parse_mode, duration=duration_secs) + except Exception as _cap_error: + err = str(_cap_error).lower() + if _cap_parse_mode is not None and ("parse" in err or "entit" in err): + logger.warning( + "[%s] voice caption MarkdownV2 rejected, retrying plain: %s", self.name, _redact_telegram_error_text(_cap_error)) + _last_parse_error = _cap_error + audio_file.seek(0) + continue + raise + raise _last_parse_error or RuntimeError("Telegram send_voice failed for all caption variants") 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: + metadata: Optional[Dict[str, Any]] = None, **kwargs) -> SendResult: """Send audio as a native Telegram voice message or audio file.""" if not self._bot: return SendResult(success=False, error="Not connected") @@ -5974,124 +4307,56 @@ class TelegramAdapter(BasePlatformAdapter): try: if not os.path.exists(audio_path): return SendResult(success=False, error=self._missing_media_path_error("Audio", audio_path)) - # sendVoice only accepts Ogg/Opus: an explicit voice-bubble request (is_voice) transcodes - # via ffmpeg; otherwise route by extension (.mp3/.m4a → sendAudio, others → document). - _voice_ext = os.path.splitext(audio_path)[1].lower() - if kwargs.get("is_voice") and _voice_ext not in (".ogg", ".opus"): + # sendVoice only accepts Ogg/Opus: an explicit voice-bubble request (is_voice) transcodes via + # ffmpeg; otherwise route by extension (.mp3/.m4a → sendAudio, others → document). + if kwargs.get("is_voice") and os.path.splitext(audio_path)[1].lower() not in (".ogg", ".opus"): from gateway.platforms.base import transcode_to_ogg_opus _transcoded_voice_path = await asyncio.to_thread(transcode_to_ogg_opus, audio_path) if _transcoded_voice_path: audio_path = _transcoded_voice_path else: logger.warning( - "[%s] voice transcode unavailable for %s — sending " - "original format (install ffmpeg for voice bubbles)", - self.name, os.path.basename(audio_path), - ) + "[%s] voice transcode unavailable for %s — sending original format (install ffmpeg for voice bubbles)", + self.name, os.path.basename(audio_path)) # Telegram drops duration for long clips (~5 min+, shows 0:00). _duration_secs = await asyncio.to_thread(_probe_voice_duration_seconds, audio_path) - # Auto-TTS captions carry the agent's markdown reply: MarkdownV2 when it fits the - # 1024-char cap, plain text fallback when it overflows or Bot API rejects it. - _caption_variants: List[tuple] = [] - if caption: - try: - _formatted_caption = self.format_message(caption) - if utf16_len(_formatted_caption) <= 1024: - _caption_variants.append((_formatted_caption, ParseMode.MARKDOWN_V2)) - except Exception: - logger.debug( - "[%s] voice caption MarkdownV2 formatting failed; sending plain caption", - self.name, exc_info=True, - ) - _caption_variants.append((caption[:1024], None)) - else: - _caption_variants.append((None, None)) with open(audio_path, "rb") as audio_file: ext = os.path.splitext(audio_path)[1].lower() - if ext in {".ogg", ".opus"}: - # Round playable voice bubble. - msg = None - _last_parse_error: Optional[Exception] = None - for _cap_text, _cap_parse_mode in _caption_variants: - try: - msg = await self._send_media( - self._bot.send_voice, chat_id, reply_to, metadata, "voice", - reset_media=lambda: audio_file.seek(0), voice=audio_file, caption=_cap_text, - parse_mode=_cap_parse_mode, duration=_duration_secs, - ) - break - except Exception as _cap_error: - # Only retry plain on entity-parse failures; anything else is a real error. - if (_cap_parse_mode is not None - and ("parse" in str(_cap_error).lower() - or "entit" in str(_cap_error).lower())): - logger.warning( - "[%s] voice caption MarkdownV2 rejected, retrying plain: %s", - self.name, _redact_telegram_error_text(_cap_error), - ) - _last_parse_error = _cap_error - audio_file.seek(0) - continue - raise - if msg is None: - raise _last_parse_error or RuntimeError( - "Telegram send_voice failed for all caption variants" - ) - elif ext in {".mp3", ".m4a"}: - # Bot API sendAudio only accepts MP3 / M4A. + if ext in {".ogg", ".opus"}: # round playable voice bubble + msg = await self._send_voice_bubble(audio_file, chat_id, reply_to, metadata, caption, _duration_secs) + elif ext in {".mp3", ".m4a"}: # Bot API sendAudio only accepts MP3 / M4A msg = await self._send_media( - self._bot.send_audio, chat_id, reply_to, metadata, "audio", - reset_media=lambda: audio_file.seek(0), audio=audio_file, - caption=caption[:1024] if caption else None, duration=_duration_secs, - ) - else: - # Formats Telegram can't play natively (.wav, .flac, ...). + self._bot.send_audio, chat_id, reply_to, metadata, "audio", reset_media=lambda: audio_file.seek(0), + audio=audio_file, caption=self._caption_1024(caption), duration=_duration_secs) + else: # formats Telegram can't play natively (.wav, .flac, ...) return await self.send_document( - chat_id=chat_id, file_path=audio_path, caption=caption, - reply_to=reply_to, metadata=metadata, - ) + chat_id=chat_id, file_path=audio_path, caption=caption, reply_to=reply_to, metadata=metadata) return SendResult(success=True, message_id=str(msg.message_id)) except Exception as e: logger.error( - "[%s] Failed to send Telegram voice/audio, falling back to base adapter: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) + "[%s] Failed to send Telegram voice/audio, falling back to base adapter: %s", self.name, + _redact_telegram_error_text(e), exc_info=True) return await super().send_voice(chat_id, audio_path, caption, reply_to, metadata=metadata) finally: if _transcoded_voice_path: - try: + with contextlib.suppress(OSError): os.unlink(_transcoded_voice_path) - except OSError: - pass async def send_multiple_images( - self, chat_id: str, images: List[tuple], metadata: Optional[Dict[str, Any]] = None, - human_delay: float = 0.0, - ) -> None: - """Send images as Telegram albums (``send_media_group``, 10 per chunk). - - Animated GIFs can't join a media group (need ``send_animation``), so they go via the - base per-image path; a failed chunk also falls back to the base per-image loop. - """ - if not self._bot: - return - if not images: + self, chat_id: str, images: List[tuple], metadata: Optional[Dict[str, Any]] = None, human_delay: float = 0.0) -> None: + """Send images as Telegram albums (``send_media_group``, 10 per chunk). Animated GIFs can't join a + media group (need ``send_animation``) so they go via the base per-image path, as does a failed chunk.""" + if not self._bot or not images: return try: from telegram import InputMediaPhoto except Exception as exc: # pragma: no cover - missing SDK - logger.warning( - "[%s] InputMediaPhoto unavailable, falling back to per-image send: %s", self.name, exc - ) + logger.warning("[%s] InputMediaPhoto unavailable, falling back to per-image send: %s", self.name, exc) await super().send_multiple_images(chat_id, images, metadata, human_delay) return - animations: List[tuple] = [] - photos: List[tuple] = [] - for image_url, alt_text in images: - if not image_url.startswith("file://") and self._is_animation_url(image_url): - animations.append((image_url, alt_text)) - else: - photos.append((image_url, alt_text)) + is_anim = lambda url: not url.startswith("file://") and self._is_animation_url(url) # noqa: E731 + animations = [img for img in images if is_anim(img[0])] + photos = [img for img in images if not is_anim(img[0])] if animations: await super().send_multiple_images(chat_id, animations, metadata, human_delay=human_delay) if not photos: @@ -6106,143 +4371,113 @@ class TelegramAdapter(BasePlatformAdapter): opened_files: List[Any] = [] try: for image_url, alt_text in chunk: - caption = alt_text[:1024] if alt_text else None + source: Any = image_url if image_url.startswith("file://"): local_path = _unquote(image_url[7:]) if not os.path.exists(local_path): - logger.warning( - "[%s] Skipping missing image in media group: %s", self.name, local_path - ) + logger.warning("[%s] Skipping missing image in media group: %s", self.name, local_path) continue - fh = open(local_path, "rb") - opened_files.append(fh) - media.append(InputMediaPhoto(media=fh, caption=caption)) - else: - media.append(InputMediaPhoto(media=image_url, caption=caption)) + source = open(local_path, "rb") + opened_files.append(source) + media.append(InputMediaPhoto(media=source, caption=self._caption_1024(alt_text))) if not media: continue - logger.info( - "[%s] Sending media group of %d photo(s) (chunk %d/%d)", - self.name, len(media), chunk_idx + 1, len(chunks), - ) + logger.info("[%s] Sending media group of %d photo(s) (chunk %d/%d)", self.name, len(media), chunk_idx + 1, len(chunks)) reply_to_id, send_kwargs = self._media_send_kwargs(chat_id, None, metadata) def _reset_opened_files() -> None: for fh in opened_files: - try: + with contextlib.suppress(Exception): fh.seek(0) - except Exception: - pass await self._send_with_dm_topic_reply_anchor_retry( self._bot.send_media_group, {**send_kwargs, "media": media}, metadata, reply_to_id, - "media group", reset_media=_reset_opened_files, - ) + "media group", reset_media=_reset_opened_files) except Exception as e: logger.warning( - "[%s] send_media_group failed (chunk %d/%d), falling back to per-image: %s", - self.name, chunk_idx + 1, len(chunks), _redact_telegram_error_text(e), - exc_info=True, - ) + "[%s] send_media_group failed (chunk %d/%d), falling back to per-image: %s", self.name, + chunk_idx + 1, len(chunks), _redact_telegram_error_text(e), exc_info=True) await super().send_multiple_images(chat_id, chunk, metadata, human_delay=human_delay) finally: for fh in opened_files: - try: + with contextlib.suppress(Exception): fh.close() - except Exception: - pass 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: + metadata: Optional[Dict[str, Any]] = None, **kwargs) -> SendResult: """Send a local image file natively as a Telegram photo.""" - if not self._bot: - return SendResult(success=False, error="Not connected") - try: - if not os.path.exists(image_path): - return SendResult(success=False, error=self._missing_media_path_error("Image", image_path)) - with open(image_path, "rb") as image_file: - msg = await self._send_media( - self._bot.send_photo, chat_id, reply_to, metadata, "photo", - reset_media=lambda: image_file.seek(0), photo=image_file, - caption=caption[:1024] if caption else None, - ) - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: + async def _photo_failed(e: Exception) -> SendResult: error_str = str(e) - # Dimension errors are expected for valid images Telegram refuses as photos - # (screenshots, extreme aspect ratios) → INFO; anything else → WARNING. - is_dim_error = "Photo_invalid_dimensions" in error_str or "PHOTO_INVALID_DIMENSIONS" in error_str - if is_dim_error: - logger.info( - "[%s] Image dimensions exceed Telegram photo limits, sending as document: %s", - self.name, image_path, - ) + # Dimension errors are expected for valid images Telegram refuses as photos → INFO. + if "Photo_invalid_dimensions" in error_str or "PHOTO_INVALID_DIMENSIONS" in error_str: + logger.info("[%s] Image dimensions exceed Telegram photo limits, sending as document: %s", self.name, image_path) else: logger.warning( - "[%s] Failed to send Telegram local image as photo, trying document fallback: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) + "[%s] Failed to send Telegram local image as photo, trying document fallback: %s", self.name, + _redact_telegram_error_text(e), exc_info=True) # Document has no dimension limit (50MB only); if even that fails, base adapter text. try: return await self.send_document( - chat_id=chat_id, file_path=image_path, caption=caption, - file_name=os.path.basename(image_path), reply_to=reply_to, metadata=metadata, - ) + chat_id=chat_id, file_path=image_path, caption=caption, file_name=os.path.basename(image_path), + reply_to=reply_to, metadata=metadata) except Exception as doc_err: logger.error( "[%s] Failed to send Telegram local image as document, falling back to base adapter: %s", - self.name, doc_err, exc_info=True, - ) - return await super().send_image_file(chat_id, image_path, caption, reply_to, metadata=metadata) + self.name, doc_err, exc_info=True) + return await super(TelegramAdapter, self).send_image_file(chat_id, image_path, caption, reply_to, metadata=metadata) + return await self._send_local_file( + "Image", image_path, chat_id, reply_to, metadata, "photo", + lambda f: {"photo": f, "caption": self._caption_1024(caption)}, _photo_failed) + + async def _send_local_file( + self, label: str, path: str, chat_id, reply_to, metadata, media_key: str, build_kwargs, on_error, + ) -> SendResult: + """Shared shell for native local-file sends: existence check, open, send with routing, then + ``await on_error(exc)`` on any failure. ``build_kwargs(f)`` supplies the media kwargs.""" + if not self._bot: + return SendResult(success=False, error="Not connected") + try: + if not os.path.exists(path): + return SendResult(success=False, error=self._missing_media_path_error(label, path)) + with open(path, "rb") as f: + msg = await self._send_media( + getattr(self._bot, f"send_{media_key}"), chat_id, reply_to, metadata, media_key, + reset_media=lambda: f.seek(0), **build_kwargs(f)) + return SendResult(success=True, message_id=str(msg.message_id)) + except Exception as e: + return await on_error(e) + + async def _warn_then(self, media_key: str, e: Exception, fallback) -> SendResult: + logger.warning("[%s] Failed to send %s: %s", self.name, media_key, _redact_telegram_error_text(e)) + return await fallback 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: + reply_to: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> SendResult: """Send a document/file natively as a Telegram file attachment.""" - if not self._bot: - return SendResult(success=False, error="Not connected") - try: - if not os.path.exists(file_path): - return SendResult(success=False, error=self._missing_media_path_error("File", file_path)) - with open(file_path, "rb") as f: - msg = await self._send_media( - self._bot.send_document, chat_id, reply_to, metadata, "document", - reset_media=lambda: f.seek(0), document=f, - filename=file_name or os.path.basename(file_path), - caption=caption[:1024] if caption else None, - ) - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] Failed to send document: %s", self.name, _redact_telegram_error_text(e)) - return await super().send_document(chat_id, file_path, caption, file_name, reply_to, metadata=metadata) + return await self._send_local_file( + "File", file_path, chat_id, reply_to, metadata, "document", + lambda f: {"document": f, "filename": file_name or os.path.basename(file_path), "caption": self._caption_1024(caption)}, + lambda e: self._warn_then( + "document", e, super( + TelegramAdapter, self, + ).send_document(chat_id, file_path, caption, file_name, reply_to, metadata=metadata))) 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: + metadata: Optional[Dict[str, Any]] = None, **kwargs) -> SendResult: """Send a video natively as a Telegram video message.""" - if not self._bot: - return SendResult(success=False, error="Not connected") - try: - if not os.path.exists(video_path): - return SendResult(success=False, error=self._missing_media_path_error("Video", video_path)) - with open(video_path, "rb") as f: - msg = await self._send_media( - self._bot.send_video, chat_id, reply_to, metadata, "video", - reset_media=lambda: f.seek(0), video=f, caption=caption[:1024] if caption else None, - ) - return SendResult(success=True, message_id=str(msg.message_id)) - except Exception as e: - logger.warning("[%s] Failed to send video: %s", self.name, _redact_telegram_error_text(e)) - return await super().send_video(chat_id, video_path, caption, reply_to, metadata=metadata) + return await self._send_local_file( + "Video", video_path, chat_id, reply_to, metadata, "video", + lambda f: {"video": f, "caption": self._caption_1024(caption)}, + lambda e: self._warn_then( + "video", e, super(TelegramAdapter, self).send_video(chat_id, video_path, caption, reply_to, metadata=metadata), + )) 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: + metadata: Optional[Dict[str, Any]] = None) -> SendResult: """Send a URL image as a Telegram photo: URL send (<5MB) → download+upload (≤10MB) → base text.""" if not self._bot: return SendResult(success=False, error="Not connected") @@ -6250,32 +4485,23 @@ class TelegramAdapter(BasePlatformAdapter): if not is_safe_url(image_url): logger.warning("[%s] Blocked unsafe image URL (SSRF protection)", self.name) return await super().send_image(chat_id, image_url, caption, reply_to, metadata=metadata) - - photo_caption = caption[:1024] if caption else None + photo_caption = self._caption_1024(caption) try: msg = await self._send_media( - self._bot.send_photo, chat_id, reply_to, metadata, "URL photo", - photo=image_url, caption=photo_caption, - ) + self._bot.send_photo, chat_id, reply_to, metadata, "URL photo", photo=image_url, caption=photo_caption) return SendResult(success=True, message_id=str(msg.message_id)) except Exception as e: logger.warning( - "[%s] URL-based send_photo failed, trying file upload: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) + "[%s] URL-based send_photo failed, trying file upload: %s", self.name, _redact_telegram_error_text(e), exc_info=True) try: from gateway.platforms.base import _ssrf_redirect_guard from tools.url_safety import create_ssrf_safe_async_client - async with create_ssrf_safe_async_client( - timeout=30.0, event_hooks={"response": [_ssrf_redirect_guard]} - ) as client: + async with create_ssrf_safe_async_client(timeout=30.0, event_hooks={"response": [_ssrf_redirect_guard]}) as client: resp = await client.get(image_url) resp.raise_for_status() image_data = resp.content msg = await self._send_media( - self._bot.send_photo, chat_id, reply_to, metadata, "uploaded photo", - photo=image_data, caption=photo_caption, - ) + self._bot.send_photo, chat_id, reply_to, metadata, "uploaded photo", photo=image_data, caption=photo_caption) return SendResult(success=True, message_id=str(msg.message_id)) except Exception as e2: logger.error("[%s] File upload send_photo also failed: %s", self.name, e2, exc_info=True) @@ -6283,29 +4509,25 @@ class TelegramAdapter(BasePlatformAdapter): 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: + metadata: Optional[Dict[str, Any]] = None) -> SendResult: """Send an animated GIF natively as a Telegram animation (auto-plays inline).""" if not self._bot: return SendResult(success=False, error="Not connected") try: msg = await self._send_media( - self._bot.send_animation, chat_id, reply_to, metadata, "animation", - animation=animation_url, caption=caption[:1024] if caption else None, - ) + self._bot.send_animation, chat_id, reply_to, metadata, "animation", animation=animation_url, + caption=self._caption_1024(caption)) return SendResult(success=True, message_id=str(msg.message_id)) except Exception as e: logger.error( - "[%s] Failed to send Telegram animation, falling back to photo: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) + "[%s] Failed to send Telegram animation, falling back to photo: %s", self.name, + _redact_telegram_error_text(e), exc_info=True) return await self.send_image(chat_id, animation_url, caption, reply_to, metadata=metadata) @staticmethod def _is_transient_typing_error(exc: Exception) -> bool: """Return True for Telegram typing errors worth cooling down.""" - retry_after = getattr(exc, "retry_after", None) - if retry_after is not None: + if getattr(exc, "retry_after", None) is not None: return True status_code = getattr(exc, "status_code", None) or getattr(exc, "code", None) if isinstance(status_code, int) and (status_code == 429 or status_code >= 500): @@ -6319,14 +4541,12 @@ class TelegramAdapter(BasePlatformAdapter): """Suppress Telegram typing refreshes for this chat after transient failures.""" if not hasattr(self, "_telegram_typing_cooldown_until"): self._telegram_typing_cooldown_until = {} - loop = asyncio.get_running_loop() retry_after = getattr(exc, "retry_after", None) try: delay = float(retry_after) if retry_after is not None else self._telegram_typing_cooldown_seconds except (TypeError, ValueError): delay = self._telegram_typing_cooldown_seconds - delay = max(1.0, min(delay, 300.0)) - self._telegram_typing_cooldown_until[str(chat_id)] = loop.time() + delay + self._telegram_typing_cooldown_until[str(chat_id)] = asyncio.get_running_loop().time() + max(1.0, min(delay, 300.0)) def _typing_in_cooldown(self, chat_id: str) -> bool: if not hasattr(self, "_telegram_typing_cooldown_until"): @@ -6346,35 +4566,27 @@ class TelegramAdapter(BasePlatformAdapter): return _is_dm_topic: bool = False message_thread_id: Optional[int] = None - try: - _typing_thread = self._metadata_thread_id(metadata) - _is_dm_topic = bool(metadata and metadata.get("telegram_dm_topic_reply_fallback")) - message_thread_id = self._message_thread_id_for_typing(_typing_thread) - await self._bot.send_chat_action( - chat_id=normalize_telegram_chat_id(chat_id), action="typing", - message_thread_id=message_thread_id, - ) + + async def _action(**kw) -> None: + await self._bot.send_chat_action(chat_id=normalize_telegram_chat_id(chat_id), action="typing", **kw) self._telegram_typing_cooldown_until.pop(str(chat_id), None) + try: + _is_dm_topic = self._dm_topic_fallback(metadata) + message_thread_id = self._message_thread_id_for_typing(self._metadata_thread_id(metadata)) + await _action(message_thread_id=message_thread_id) except Exception as e: - # DM topic lanes: Telegram may reject message_thread_id — retry without it so the - # indicator at least appears in the main DM view. + # DM topic lanes: Telegram may reject message_thread_id — retry without it so the indicator at + # least appears in the main DM view. if _is_dm_topic and message_thread_id is not None: try: - await self._bot.send_chat_action( - chat_id=normalize_telegram_chat_id(chat_id), action="typing" - ) - self._telegram_typing_cooldown_until.pop(str(chat_id), None) + await _action() return except Exception as fallback_exc: if self._is_transient_typing_error(fallback_exc): self._record_typing_cooldown(chat_id, fallback_exc) elif self._is_transient_typing_error(e): self._record_typing_cooldown(chat_id, e) - # Typing failures are non-fatal; debug only. - logger.debug( - "[%s] Failed to send Telegram typing indicator: %s", - self.name, _redact_telegram_error_text(e), exc_info=True, - ) + logger.debug("[%s] Failed to send Telegram typing indicator: %s", self.name, _redact_telegram_error_text(e), exc_info=True) async def get_chat_info(self, chat_id: str) -> Dict[str, Any]: """Get information about a Telegram chat.""" @@ -6386,30 +4598,20 @@ class TelegramAdapter(BasePlatformAdapter): if chat.type == ChatType.GROUP: chat_type = "group" elif chat.type == ChatType.SUPERGROUP: - chat_type = "group" - if chat.is_forum: - chat_type = "forum" + chat_type = "forum" if chat.is_forum else "group" elif chat.type == ChatType.CHANNEL: chat_type = "channel" return { - "name": chat.title or chat.full_name or str(chat_id), - "type": chat_type, - "username": chat.username, - "is_forum": getattr(chat, "is_forum", False), - } + "name": chat.title or chat.full_name or str(chat_id), "type": chat_type, "username": chat.username, + "is_forum": getattr(chat, "is_forum", False)} except Exception as e: - logger.error( - "[%s] Failed to get Telegram chat info for %s: %s", - self.name, chat_id, _redact_telegram_error_text(e), exc_info=True, - ) + logger.error("[%s] Failed to get Telegram chat info for %s: %s", self.name, chat_id, _redact_telegram_error_text( + e), exc_info=True) return {"name": str(chat_id), "type": "dm", "error": str(e)} def format_message(self, content: str) -> str: - """Convert standard markdown to Telegram MarkdownV2. - - Code blocks/inline code are stashed behind placeholders first so they're never - modified; markdown constructs become MarkdownV2 syntax; everything else is escaped. - """ + """Convert standard markdown to Telegram MarkdownV2: code is stashed behind placeholders first (never + modified), markdown constructs become MarkdownV2 syntax, everything else is escaped.""" if not content: return content placeholders: dict = {} @@ -6422,55 +4624,42 @@ class TelegramAdapter(BasePlatformAdapter): placeholders[key] = value return key - text = content - # 0) GFM pipe tables → Telegram-friendly row groups, before the MarkdownV2 conversions. - text = _wrap_markdown_tables(text) + def _ph_wrap(open_: str, close: str): + return lambda m: _ph(f"{open_}{_escape_mdv2(m.group(1))}{close}") + # 0) GFM pipe tables → Telegram-friendly row groups, before the MarkdownV2 conversions. + text = _wrap_markdown_tables(content) # 1) Protect fenced code blocks; per MarkdownV2 spec \ and ` inside pre/code must be escaped. def _protect_fenced(m): raw = m.group(0) - # Split off opening ``` (with optional language) and closing ``` - open_end = raw.index('\n') + 1 if '\n' in raw[3:] else 3 - opening = raw[:open_end] - body_and_close = raw[open_end:] - body = body_and_close[:-3] - body = body.replace('\\', '\\\\').replace('`', '\\`') - return _ph(opening + body + '```') + open_end = raw.index('\n') + 1 if '\n' in raw[3:] else 3 # opening ``` (+ optional language) + body = raw[open_end:][:-3].replace('\\', '\\\\').replace('`', '\\`') + return _ph(raw[:open_end] + body + '```') text = re.sub(r'(```(?:[^\n]*\n)?[\s\S]*?```)', _protect_fenced, text) - # 2) Protect inline code; escape \ inside it per MarkdownV2 spec. text = re.sub(r'(`[^`]+`)', lambda m: _ph(m.group(0).replace('\\', '\\\\')), text) - # 3) Links: escape display text; inside the URL only ')' and '\' need escaping. def _convert_link(m): - display = _escape_mdv2(m.group(1)) url = m.group(2).replace('\\', '\\\\').replace(')', '\\)') - return _ph(f'[{display}]({url})') + return _ph(f'[{_escape_mdv2(m.group(1))}]({url})') text = re.sub(r'\[([^\]]+)\]\(([^()]*(?:\([^()]*\)[^()]*)*)\)', _convert_link, text) - # 4) Headers (## Title) → bold *Title*, stripping redundant ** inside the header def _convert_header(m): - inner = m.group(1).strip() - inner = re.sub(r'\*\*(.+?)\*\*', r'\1', inner) + inner = re.sub(r'\*\*(.+?)\*\*', r'\1', m.group(1).strip()) return _ph(f'*{_escape_mdv2(inner)}*') text = re.sub(r'^#{1,6}\s+(.+)$', _convert_header, text, flags=re.MULTILINE) - # 5) Bold: **text** → *text* - text = re.sub(r'\*\*(.+?)\*\*', lambda m: _ph(f'*{_escape_mdv2(m.group(1))}*'), text) - # 6) Italic: *text* → _text_. [^*\n]+ keeps matches on one line, or * bullet lists corrupt. - text = re.sub(r'\*([^*\n]+)\*', lambda m: _ph(f'_{_escape_mdv2(m.group(1))}_'), text) - # 7) Strikethrough: ~~text~~ → ~text~ - text = re.sub(r'~~(.+?)~~', lambda m: _ph(f'~{_escape_mdv2(m.group(1))}~'), text) - # 8) Spoiler: ||text|| kept as-is (protect from | escaping) - text = re.sub(r'\|\|(.+?)\|\|', lambda m: _ph(f'||{_escape_mdv2(m.group(1))}||'), text) - - # 9) Blockquotes: protect leading > from escaping. Also expandable quotes - # (**> starts, trailing || ends — that || must stay unescaped). + # 5) Bold **text** → *text*; 6) Italic *text* → _text_ ([^*\n]+ keeps matches on one line, or * + # bullet lists corrupt); 7) Strikethrough ~~text~~ → ~text~; 8) Spoiler ||text|| kept as-is. + text = re.sub(r'\*\*(.+?)\*\*', _ph_wrap('*', '*'), text) + text = re.sub(r'\*([^*\n]+)\*', _ph_wrap('_', '_'), text) + text = re.sub(r'~~(.+?)~~', _ph_wrap('~', '~'), text) + text = re.sub(r'\|\|(.+?)\|\|', _ph_wrap('||', '||'), text) + # 9) Blockquotes: protect leading > from escaping; expandable quotes (**> starts, trailing || ends). def _convert_blockquote(m): - prefix = m.group(1) # >, >>, >>>, **>, or **>> etc. - content = m.group(2) + prefix, content = m.group(1), m.group(2) # prefix: >, >>, >>>, **>, **>> … if prefix.startswith('**') and content.endswith('||'): return _ph(f'{prefix} {_escape_mdv2(content[:-2])}||') return _ph(f'{prefix} {_escape_mdv2(content)}') @@ -6482,36 +4671,37 @@ class TelegramAdapter(BasePlatformAdapter): for key in reversed(list(placeholders.keys())): text = text.replace(key, placeholders[key]) # 12) Safety net: escape bare ( ) { } that slipped through, but never inside ``` or ` spans. - _code_split = re.split(r'(```[\s\S]*?```|`[^`]+`)', text) _safe_parts = [] - for _idx, _seg in enumerate(_code_split): + for _idx, _seg in enumerate(re.split(r'(```[\s\S]*?```|`[^`]+`)', text)): if _idx % 2 == 1: _safe_parts.append(_seg) # inside code — untouched else: - def _esc_bare(m, _seg=_seg): - s = m.start() - ch = m.group(0) - if s > 0 and _seg[s - 1] == '\\': # already escaped - return ch - if ch == '(' and s > 0 and _seg[s - 1] == ']': # opens a link [text](url) - return ch - if ch == ')': # closes a link URL? walk back matching depth - before = _seg[:s] - if '](http' in before or '](' in before: - depth = 0 - for j in range(s - 1, max(s - 2000, -1), -1): - if _seg[j] == '(': - depth -= 1 - if depth < 0: - if j > 0 and _seg[j - 1] == ']': - return ch - break - elif _seg[j] == ')': - depth += 1 - return '\\' + ch - _safe_parts.append(re.sub(r'[(){}]', _esc_bare, _seg)) - text = ''.join(_safe_parts) - return text + _safe_parts.append(re.sub(r'[(){}]', lambda m, _seg=_seg: self._escape_bare_bracket(m, _seg), _seg)) + return ''.join(_safe_parts) + + @staticmethod + def _escape_bare_bracket(m, seg: str) -> str: + """Escape a bare ( ) { } unless it is already escaped or delimits a ``[text](url)`` link.""" + s = m.start() + ch = m.group(0) + if s > 0 and seg[s - 1] == '\\': # already escaped + return ch + if ch == '(' and s > 0 and seg[s - 1] == ']': # opens a link [text](url) + return ch + if ch == ')': # closes a link URL? walk back matching depth + before = seg[:s] + if '](http' in before or '](' in before: + depth = 0 + for j in range(s - 1, max(s - 2000, -1), -1): + if seg[j] == '(': + depth -= 1 + if depth < 0: + if j > 0 and seg[j - 1] == ']': + return ch + break + elif seg[j] == ')': + depth += 1 + return '\\' + ch # ── Group mention gating ────────────────────────────────────────────── @@ -6541,12 +4731,10 @@ class TelegramAdapter(BasePlatformAdapter): return self._extra_bool("require_mention", "TELEGRAM_REQUIRE_MENTION", "false") def _telegram_observe_unmentioned_group_messages(self) -> bool: - """Store skipped unmentioned group messages as context (with ``require_mention``: - observe chatter in the transcript, dispatch only when addressed).""" + """Store skipped unmentioned group messages as context (observe chatter, dispatch only when addressed).""" return self._extra_bool( "observe_unmentioned_group_messages", "TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES", "false", - "ingest_unmentioned_group_messages", - ) + "ingest_unmentioned_group_messages") def _telegram_guest_mode(self) -> bool: """Return whether non-allowlisted groups may trigger via direct @mention.""" @@ -6568,16 +4756,14 @@ class TelegramAdapter(BasePlatformAdapter): topics = self._telegram_free_response_topics() if not topics: return False - chat_id = str(getattr(getattr(message, "chat", None), "id", "")) + chat_id = self._chat_id_str(message) if not chat_id: return False - thread_id = self._effective_message_thread_id(message) - topic_id = str(thread_id) if thread_id is not None else self._GENERAL_TOPIC_THREAD_ID - return f"{chat_id}:{topic_id}" in topics + return f"{chat_id}:{self._topic_id_or_general(self._effective_message_thread_id(message))}" in topics def _telegram_allowed_chats(self) -> set[str]: - """Group chat IDs the bot responds in (non-empty: others need ``guest_mode`` + @mention; - DMs never filtered; empty = no restriction).""" + """Group chat IDs the bot responds in (non-empty: others need ``guest_mode`` + @mention; DMs never + filtered; empty = no restriction).""" return self._extra_str_set("allowed_chats", "TELEGRAM_ALLOWED_CHATS") def _telegram_group_allowed_chats(self) -> set[str]: @@ -6585,28 +4771,25 @@ class TelegramAdapter(BasePlatformAdapter): return self._extra_str_set("group_allowed_chats", "TELEGRAM_GROUP_ALLOWED_CHATS") def _telegram_observe_allowed_chats(self) -> set[str]: - """Chats where observed group context may use a shared source: ``group_allowed_chats`` - (auth allowlist for user-less sources) ∩ ``allowed_chats`` (response gate) when set.""" + """Chats where observed group context may use a shared source: ``group_allowed_chats`` ∩ + ``allowed_chats`` (when set).""" group_allowed = self._telegram_group_allowed_chats() if not group_allowed: return set() response_allowed = self._telegram_allowed_chats() - if response_allowed: - return group_allowed & response_allowed - return group_allowed + return group_allowed & response_allowed if response_allowed else group_allowed def _telegram_allowed_topics(self) -> set[str]: - """Forum topic IDs this bot handles (non-empty: other topics ignored; DMs - never filtered; missing ``message_thread_id`` == General topic ``1``).""" + """Forum topic IDs this bot handles (non-empty: other topics ignored; DMs never filtered; missing + ``message_thread_id`` == General topic ``1``).""" return self._extra_str_set("allowed_topics", "TELEGRAM_ALLOWED_TOPICS") def _telegram_ignored_threads(self) -> set[int]: raw = self.config.extra.get("ignored_threads") if raw is None: raw = _scoped_gate_env("TELEGRAM_IGNORED_THREADS") - values = raw if isinstance(raw, list) else str(raw).split(",") ignored: set[int] = set() - for value in values: + for value in (raw if isinstance(raw, list) else str(raw).split(",")): text = str(value).strip() if not text: continue @@ -6630,57 +4813,51 @@ class TelegramAdapter(BasePlatformAdapter): loaded = [part.strip() for part in raw.split(",") if part.strip()] patterns = loaded if patterns is None: - # Return before touching ``self.name``: tests build bare adapters via object.__new__. - return [] - return compile_mention_patterns( - patterns, log_prefix=self.name, platform_label="telegram", - display_label="Telegram", logger_=logger, - ) + return [] # before touching ``self.name``: tests build bare adapters via object.__new__ + return compile_mention_patterns(patterns, log_prefix=self.name, platform_label="telegram", display_label="Telegram", logger_=logger) + + @staticmethod + def _chat_type_str(chat) -> str: + """PTB enum or plain-string ``chat.type`` → bare lowercase name (``supergroup``).""" + return str(getattr(chat, "type", "")).split(".")[-1].lower() if chat else "" + + @staticmethod + def _chat_id_str(message) -> str: + return str(getattr(getattr(message, "chat", None), "id", "")) + + @classmethod + def _topic_id_or_general(cls, thread_id) -> str: + return str(thread_id) if thread_id is not None else cls._GENERAL_TOPIC_THREAD_ID def _is_group_chat(self, message: Message) -> bool: chat = getattr(message, "chat", None) - if not chat: - return False - chat_type = str(getattr(chat, "type", "")).split(".")[-1].lower() - return chat_type in {"group", "supergroup"} + return bool(chat) and self._chat_type_str(chat) in {"group", "supergroup"} @classmethod def _effective_message_thread_id(cls, message: Message) -> Optional[str]: - """Return the routable thread id for a Telegram message. - - Forum General-topic messages arrive with ``message_thread_id=None`` but Telegram - addresses that topic as id ``1``; conversely, plain group/DM replies carry a reply-UI - anchor in ``message_thread_id`` that is NOT a routing id. Gating, skill binding and - outbound routing must all agree on this one normalized value. - """ + """Routable thread id: forum General-topic messages arrive with ``message_thread_id=None`` but + Telegram addresses that topic as ``1``; plain group/DM replies carry a reply-UI anchor that is NOT + a routing id. Gating, skill binding and outbound routing must all agree on this value.""" chat = getattr(message, "chat", None) - chat_type = str(getattr(chat, "type", "")).split(".")[-1].lower() if chat else "" + chat_type = cls._chat_type_str(chat) raw = getattr(message, "message_thread_id", None) is_topic_message = bool(getattr(message, "is_topic_message", False)) - is_forum_group = chat_type in ("group", "supergroup") and getattr(chat, "is_forum", False) is True + is_group = chat_type in ("group", "supergroup") + is_forum_group = is_group and getattr(chat, "is_forum", False) is True if raw is not None: - if is_forum_group or (chat_type in ("group", "supergroup") and is_topic_message): - return str(raw) - if chat_type == "private" and is_topic_message: + if is_forum_group or (is_group and is_topic_message) or (chat_type == "private" and is_topic_message): return str(raw) return None - if is_forum_group: - return cls._GENERAL_TOPIC_THREAD_ID - return None + return cls._GENERAL_TOPIC_THREAD_ID if is_forum_group else None - # Decides only whether a FOREIGN @handle is bot-shaped; our own handle is matched by - # identity, never shape (collectible/Fragment bot usernames need not end in "bot"). + # Decides only whether a FOREIGN @handle is bot-shaped; our own handle is matched by identity, never + # shape (collectible/Fragment bot usernames need not end in "bot"). _FOREIGN_BOT_HANDLE_RE = re.compile(r"[a-z0-9_]{2,29}bot", re.IGNORECASE) - # How long an observed identity is trusted before the heartbeat re-checks. - _BOT_IDENTITY_TTL_SECONDS = 300.0 + _BOT_IDENTITY_TTL_SECONDS = 300.0 # how long an observed identity is trusted before re-check def _current_bot_username(self) -> str: - """Return this bot's live @username (lowercased, no leading ``@``). - - Prefers the last observed handle over PTB's ``get_me()`` cache: ``Bot.username`` is - only refreshed by ``get_me()``, so after a BotFather rename it keeps the stale handle - and every mention comparison silently stops matching. - """ + """This bot's live @username (lowercased, no ``@``): the last observed handle beats PTB's + ``get_me()`` cache, which keeps a stale handle after a BotFather rename.""" observed = getattr(self, "_bot_username_observed", None) if observed: return observed @@ -6698,47 +4875,27 @@ class TelegramAdapter(BasePlatformAdapter): self._bot_identity_checked_at = time.monotonic() if previous: logger.info( - "[%s] Telegram bot username changed: @%s -> @%s (mention routing now follows the new handle)", - self.name, previous, handle, - ) + "[%s] Telegram bot username changed: @%s -> @%s (mention routing now follows the new handle)", self.name, previous, handle) def _observe_bot_identity_from_message(self, message: Message) -> None: - """Learn our own handle from a message Telegram says we authored. - - Telegram stamps the *current* username on our own messages and on ``reply_to_message`` - when a user replies to us, so renames are observable without getMe. Only trusted when - the user id matches this bot, so a foreign handle can never be adopted. - """ + """Learn our own handle from a message Telegram says we authored (own messages and + ``reply_to_message``); only trusted when the user id matches this bot.""" bot_id = getattr(self._bot, "id", None) if bot_id is None: return - for candidate in ( - getattr(message, "from_user", None), - getattr(getattr(message, "reply_to_message", None), "from_user", None), - ): - if candidate is None: - continue - if getattr(candidate, "id", None) != bot_id: - continue - self._note_bot_username(getattr(candidate, "username", None)) + for candidate in (getattr(message, "from_user", None), getattr(getattr(message, "reply_to_message", None), "from_user", None)): + if candidate is not None and getattr(candidate, "id", None) == bot_id: + self._note_bot_username(getattr(candidate, "username", None)) def _bot_identity_is_fresh(self) -> bool: - """True when identity was re-read within the TTL. - - ``None`` (never checked) is always stale. Do not fold it into ``0.0``: monotonic - clocks have an arbitrary epoch that can be smaller than the TTL on a fresh host. - """ + """True when identity was re-read within the TTL. ``None`` (never checked) is always stale — do + not fold it into ``0.0``: monotonic clocks have an arbitrary epoch.""" checked_at = getattr(self, "_bot_identity_checked_at", None) - if checked_at is None: - return False - return (time.monotonic() - checked_at) < self._BOT_IDENTITY_TTL_SECONDS + return checked_at is not None and (time.monotonic() - checked_at) < self._BOT_IDENTITY_TTL_SECONDS async def _refresh_bot_identity(self, *, force: bool = False) -> None: - """Re-read bot identity from Telegram when the cache may be stale. - - ``get_me()`` rewrites PTB's ``Bot._bot_user`` in place, repairing every consumer of - ``self._bot.username``. Best-effort: a failed probe keeps the last known handle. - """ + """Re-read bot identity when the cache may be stale (``get_me()`` rewrites PTB's ``Bot._bot_user`` + in place). Best-effort: a failed probe keeps the last known handle.""" bot = self._bot if bot is None or not callable(getattr(bot, "get_me", None)): return @@ -6750,9 +4907,7 @@ class TelegramAdapter(BasePlatformAdapter): raise except Exception as exc: logger.debug( - "[%s] Telegram identity refresh failed (keeping @%s): %s", - self.name, self._current_bot_username() or "unknown", exc, - ) + "[%s] Telegram identity refresh failed (keeping @%s): %s", self.name, self._current_bot_username() or "unknown", exc) return self._bot_identity_checked_at = time.monotonic() self._note_bot_username(getattr(me, "username", None)) @@ -6765,15 +4920,30 @@ class TelegramAdapter(BasePlatformAdapter): reply_user = getattr(message.reply_to_message, "from_user", None) return bool(reply_user and getattr(reply_user, "id", None) == getattr(self._bot, "id", None)) + @staticmethod + def _entity_sources(message: Message): + """``(text, entities)`` pairs for the message text and caption.""" + yield getattr(message, "text", None) or "", getattr(message, "entities", None) or [] + yield getattr(message, "caption", None) or "", getattr(message, "caption_entities", None) or [] + + @staticmethod + def _entity_type(entity) -> str: + return str(getattr(entity, "type", "")).split(".")[-1].lower() + + @classmethod + def _entity_span(cls, source_text: str, entity) -> Optional[str]: + """The entity's text, or None when its offsets are unusable.""" + offset = int(getattr(entity, "offset", -1)) + length = int(getattr(entity, "length", 0)) + if offset < 0 or length <= 0: + return None + return cls._telegram_entity_text(source_text, offset, length) + @classmethod def _extract_bot_mention_usernames(cls, message: Message, self_username: str = "") -> set[str]: - """Extract explicit bot usernames mentioned in text/captions. - - Foreign handles count only when bot-shaped (``...bot``) so human @handles never act - as routing hints; ``self_username`` opts our OWN handle in regardless of shape - (collectible usernames like @jarvis). Entity mentions are authoritative; the raw-text - fallback is deliberately narrow (no emails / arbitrary substrings). - """ + """Explicit bot usernames mentioned in text/captions: foreign handles count only when bot-shaped + (``...bot``), ``self_username`` opts our OWN handle in regardless of shape. Entity mentions are + authoritative; the raw-text fallback is deliberately narrow.""" mentioned_bot_usernames: set[str] = set() own = (self_username or "").lstrip("@").lower() @@ -6784,44 +4954,35 @@ class TelegramAdapter(BasePlatformAdapter): return True return bool(cls._FOREIGN_BOT_HANDLE_RE.fullmatch(handle)) - def _iter_sources(): - yield getattr(message, "text", None) or "", getattr(message, "entities", None) or [] - yield getattr(message, "caption", None) or "", getattr(message, "caption_entities", None) or [] - for source_text, entities in _iter_sources(): + for source_text, entities in cls._entity_sources(message): for entity in entities: - entity_type = str(getattr(entity, "type", "")).split(".")[-1].lower() + entity_type = cls._entity_type(entity) if entity_type not in {"mention", "bot_command"}: continue - offset = int(getattr(entity, "offset", -1)) - length = int(getattr(entity, "length", 0)) - if offset < 0 or length <= 0: + entity_text = cls._entity_span(source_text, entity) + if entity_text is None: continue - entity_text = TelegramAdapter._telegram_entity_text(source_text, offset, length).strip() + entity_text = entity_text.strip() if entity_type == "mention": handle = entity_text.lstrip("@").lower() if _is_bot_handle(handle): mentioned_bot_usernames.add(handle) continue - - # /cmd@botname is one bot_command entity (no separate mention); its suffix - # is an explicit bot address for exclusive multi-bot routing. + # /cmd@botname is one bot_command entity; its suffix is an explicit bot address. at_index = entity_text.find("@") if at_index < 0: continue command_target = entity_text[at_index + 1:].strip().lower() if _is_bot_handle(command_target): mentioned_bot_usernames.add(command_target) - - # Entity-less fallback only: if Telegram supplied entities, trust them and do not - # regex-rescue URL/code spans the server did not mark as mentions. - for raw_text, entities in _iter_sources(): + # Entity-less fallback only: if Telegram supplied entities, trust them (no URL/code rescue). + for raw_text, entities in cls._entity_sources(message): if not raw_text or entities: continue for match in re.finditer(r"(?i)(?= 0 and command_text[at_index:].strip().lower() == expected: return True if bot_username: return bot_username in self._extract_bot_mention_usernames(message, bot_username) return False def _schedule_bot_identity_recheck(self) -> None: - """Fire a TTL-guarded identity refresh in the background. - - Called when routing is about to discard a message naming other bots but not us — the - symptom of a stale handle after a rename. TTL-bounded to one getMe per - ``_BOT_IDENTITY_TTL_SECONDS``; fire-and-forget, the current message routes as-is. - """ + """Fire a TTL-guarded identity refresh in the background when routing is about to discard a + message naming other bots but not us (the symptom of a stale handle after a rename).""" existing = getattr(self, "_bot_identity_refresh_task", None) - if existing is not None and not existing.done(): - return - if self._bot_identity_is_fresh(): + if (existing is not None and not existing.done()) or self._bot_identity_is_fresh(): return try: loop = asyncio.get_running_loop() @@ -6907,12 +5044,8 @@ class TelegramAdapter(BasePlatformAdapter): task.add_done_callback(tracked.discard) def _explicit_bot_mentions_exclude_self(self, message: Message) -> bool: - """Return True when explicit bot handles target other bots, not this one. - - Groups may hold several Hermes bots; ``@bot3 hi @bot4`` must not wake ``@bot1`` via - reply/wake-word fallbacks. Foreign handles are limited to the ``...bot`` shape so - human @handles never suppress us; our own handle is matched by identity. - """ + """True when explicit bot handles target other bots, not this one (``@bot3 hi @bot4`` must not + wake ``@bot1`` via reply/wake-word fallbacks).""" if not self._bot: return False bot_username = self._current_bot_username() @@ -6921,21 +5054,17 @@ class TelegramAdapter(BasePlatformAdapter): mentioned_bot_usernames = self._extract_bot_mention_usernames(message, bot_username) excludes_self = bool(mentioned_bot_usernames) and bot_username not in mentioned_bot_usernames if excludes_self: - # Either truly for another bot, or our handle is stale after a rename — - # re-check identity out of band (TTL bounded) so the mistake self-corrects. + # Either truly for another bot, or our handle is stale after a rename — re-check out of band. self._schedule_bot_identity_recheck() return excludes_self def _message_matches_mention_patterns(self, message: Message) -> bool: if not self._mention_patterns: return False - for candidate in (getattr(message, "text", None), getattr(message, "caption", None)): - if not candidate: - continue - for pattern in self._mention_patterns: - if pattern.search(candidate): - return True - return False + return any( + pattern.search(candidate) + for candidate in (getattr(message, "text", None), getattr(message, "caption", None)) if candidate + for pattern in self._mention_patterns) def _is_guest_mention(self, message: Message) -> bool: """Guest-mode bypass: explicit bot mention (caller already verified group chat).""" @@ -6945,50 +5074,41 @@ class TelegramAdapter(BasePlatformAdapter): bot_username = self._current_bot_username() if not text or not bot_username: return text - username = re.escape(bot_username) - cleaned = re.sub(rf"(?i)@{username}\b[,:\-]*\s*", "", text).strip() + cleaned = re.sub(rf"(?i)@{re.escape(bot_username)}\b[,:\-]*\s*", "", text).strip() return cleaned or text - def _should_observe_unmentioned_group_message(self, message: Message) -> bool: - """Return True when a group message should be stored but not dispatched.""" - if self._is_own_message(message): - return False - if not self._telegram_observe_unmentioned_group_messages(): - return False - if not self._is_group_chat(message): - return False - thread_id = getattr(message, "message_thread_id", None) + def _topic_gates_pass(self, thread_id, *, warn_non_numeric: bool) -> Optional[bool]: + """``allowed_topics`` / ``ignored_threads`` gates; False = blocked, None = undecided.""" allowed_topics = self._telegram_allowed_topics() - if allowed_topics: - topic_id = str(thread_id) if thread_id is not None else self._GENERAL_TOPIC_THREAD_ID - if topic_id not in allowed_topics: - return False + if allowed_topics and self._topic_id_or_general(thread_id) not in allowed_topics: + return False if thread_id is not None: try: if int(thread_id) in self._telegram_ignored_threads(): return False except (TypeError, ValueError): - return False - chat_id_str = str(getattr(getattr(message, "chat", None), "id", "")) + if not warn_non_numeric: + return False + logger.warning("[%s] Ignoring non-numeric Telegram message_thread_id: %r", self.name, thread_id) + return None + + def _should_observe_unmentioned_group_message(self, message: Message) -> bool: + """Return True when a group message should be stored but not dispatched.""" + if self._is_own_message(message) or not self._telegram_observe_unmentioned_group_messages() or not self._is_group_chat(message): + return False + if self._topic_gates_pass(getattr(message, "message_thread_id", None), warn_non_numeric=False) is False: + return False + chat_id_str = self._chat_id_str(message) if self._telegram_exclusive_bot_mentions() and self._explicit_bot_mentions_exclude_self(message): return False + # Observed context is shared at chat/topic scope, so require an explicit chat allowlist. allowed = self._telegram_observe_allowed_chats() - # Observed context is shared at chat/topic scope, so require an explicit chat - # allowlist: it limits shared history to operator-approved groups and lets gateway - # auth pass once the shared source drops the per-sender user_id. if not allowed or chat_id_str not in allowed: return False - # Only observe messages the require_mention gate would skip; anything that would be - # processed normally belongs to the dispatcher. - if chat_id_str in self._telegram_free_response_chats(): + # Only observe messages the require_mention gate would skip. + if chat_id_str in self._telegram_free_response_chats() or self._telegram_is_free_response_topic(message): return False - if self._telegram_is_free_response_topic(message): - return False - if not self._telegram_require_mention(): - return False - if self._is_reply_to_bot(message): - return False - if self._message_mentions_bot(message): + if not self._telegram_require_mention() or self._is_reply_to_bot(message) or self._message_mentions_bot(message): return False return not self._message_matches_mention_patterns(message) @@ -6998,8 +5118,7 @@ class TelegramAdapter(BasePlatformAdapter): def _telegram_group_observe_attributed_text(self, event: MessageEvent) -> str: user_id = event.source.user_id or "unknown" - sender = event.source.user_name or user_id - return f"[{sender}|{user_id}]\n{event.text or ''}" + return f"[{event.source.user_name or user_id}|{user_id}]\n{event.text or ''}" def _telegram_group_observe_channel_prompt(self) -> str: username = self._current_bot_username() or "unknown" @@ -7010,8 +5129,7 @@ class TelegramAdapter(BasePlatformAdapter): "- observed Telegram group context may be provided in a separate context-only block " "before the current message; it is not necessarily addressed to you.\n" "- Treat only the current new message as a request explicitly directed at you, " - "and use observed context only when the current message asks for it." - ) + "and use observed context only when the current message asks for it.") def _apply_telegram_group_observe_attribution(self, event: MessageEvent) -> MessageEvent: """Align triggered group turns with observed-history attribution.""" @@ -7020,58 +5138,38 @@ class TelegramAdapter(BasePlatformAdapter): raw_message = getattr(event, "raw_message", None) if not raw_message or not self._is_group_chat(raw_message): return event - chat_id_str = str(getattr(getattr(raw_message, "chat", None), "id", "")) allowed = self._telegram_observe_allowed_chats() - if not allowed or chat_id_str not in allowed: + if not allowed or self._chat_id_str(raw_message) not in allowed: return event - shared_source = self._telegram_group_observe_shared_source(event.source) observe_prompt = self._telegram_group_observe_channel_prompt() channel_prompt = f"{event.channel_prompt}\n\n{observe_prompt}" if event.channel_prompt else observe_prompt if event.message_type == MessageType.COMMAND: - # Commands keep the original source (user_id) so _check_slash_access can identify - # the sender — SlashAccessPolicy.is_admin(None) is always False. Still inject prompt. + # Commands keep the original source (user_id) so _check_slash_access can identify the sender. return dataclasses.replace(event, channel_prompt=channel_prompt) return dataclasses.replace( - event, - text=self._telegram_group_observe_attributed_text(event), - source=shared_source, - channel_prompt=channel_prompt, - ) + event, text=self._telegram_group_observe_attributed_text(event), + source=self._telegram_group_observe_shared_source(event.source), channel_prompt=channel_prompt) def _media_message_type(self, msg: Message) -> MessageType: - """Classify a Telegram media message into a MessageType.""" - if msg.sticker: - return MessageType.STICKER - if msg.photo: - return MessageType.PHOTO - if msg.video: - return MessageType.VIDEO - if msg.audio: - return MessageType.AUDIO - if msg.voice: - return MessageType.VOICE + """Classify a Telegram media message into a MessageType (first present attachment wins).""" + for attr, mtype in ( + ("sticker", MessageType.STICKER), ("photo", MessageType.PHOTO), ("video", MessageType.VIDEO), + ("audio", MessageType.AUDIO), ("voice", MessageType.VOICE)): + if getattr(msg, attr): + return mtype return MessageType.DOCUMENT _CACHED_KIND_TO_MESSAGE_TYPE = {"image": MessageType.PHOTO, "video": MessageType.VIDEO, "audio": MessageType.AUDIO} async def _download_observed_media(self, msg: Any, what: str): - """Download ``msg``'s attachment into the media cache (bounded by ``_max_doc_bytes``). - - Returns ``(status, cached)`` where status is ``"none"`` (no attachment), - ``"oversized"`` (skipped, ``cached`` is the raw file_size), ``"failed"`` - (download error, logged), ``"unreadable"`` (cache rejected it) or ``"ok"``. - """ + """Download ``msg``'s attachment into the media cache (bounded by ``_max_doc_bytes``). Returns ``(status, cached)``: + ``"none"``, ``"oversized"`` (cached = raw file_size), ``"failed"``, ``"unreadable"`` or ``"ok"``.""" from gateway.platforms.base import cache_media_bytes source, filename, mime, kind = self._observed_media_source(msg) if source is None: return "none", None - max_bytes = getattr(self, "_max_doc_bytes", 20 * 1024 * 1024) file_size = getattr(source, "file_size", None) - try: - size = int(file_size or 0) - except (TypeError, ValueError): - size = 0 - if not (0 < size <= max_bytes): + if not (0 < self._int_or_zero(file_size) <= getattr(self, "_max_doc_bytes", 20 * 1024 * 1024)): return "oversized", file_size try: file_obj = await source.get_file() @@ -7087,31 +5185,31 @@ class TelegramAdapter(BasePlatformAdapter): return "ok", cached async def _cache_observed_media(self, msg: Message, event: MessageEvent) -> None: - """Cache an unmentioned group attachment and annotate the observed text. - - Bounded by ``_max_doc_bytes`` like the addressed document path; oversized or - unsupported attachments are noted in the transcript without downloading. - """ + """Cache an unmentioned group attachment and annotate the observed text; oversized or unsupported + attachments are noted in the transcript without downloading.""" status, cached = await self._download_observed_media(msg, "observed group media") if status == "oversized": limit_mb = getattr(self, "_max_doc_bytes", 20 * 1024 * 1024) // (1024 * 1024) event.text = self._append_observed_note( - event.text, f"[Observed Telegram attachment too large or unverifiable. Maximum: {limit_mb} MB.]" - ) + event.text, f"[Observed Telegram attachment too large or unverifiable. Maximum: {limit_mb} MB.]") logger.info("[Telegram] Observed group attachment skipped (size=%s)", cached) return - if status == "unreadable": - # Only images that fail validation reach here; every other type is always cached. + if status == "unreadable": # only images that fail validation reach here event.text = self._append_observed_note(event.text, "[Observed Telegram attachment could not be read, not cached.]") return - if status != "ok": - return - event.media_urls = [cached.path] - event.media_types = [cached.media_type] - if cached.kind in self._CACHED_KIND_TO_MESSAGE_TYPE: + if status == "ok": + event.media_urls = [] + event.media_types = [] + self._attach_cached(event, cached, cached.context_note(), "[Telegram] Cached observed group %s at %s") + + def _attach_cached(self, event: MessageEvent, cached, note: str, log_fmt: str) -> None: + """Append a cached attachment to the event (message type follows the kind only for the first one).""" + event.media_urls.append(cached.path) + event.media_types.append(cached.media_type) + if len(event.media_urls) == 1 and cached.kind in self._CACHED_KIND_TO_MESSAGE_TYPE: event.message_type = self._CACHED_KIND_TO_MESSAGE_TYPE[cached.kind] - event.text = self._append_observed_note(event.text, cached.context_note()) - logger.info("[Telegram] Cached observed group %s at %s", cached.kind, cached.path) + event.text = self._append_observed_note(event.text, note) + logger.info(log_fmt, cached.kind, cached.path) async def _cache_replied_media(self, msg: Any, event: MessageEvent) -> None: """Cache media from the message this turn replies to, if any.""" @@ -7119,16 +5217,10 @@ class TelegramAdapter(BasePlatformAdapter): if reply_msg is None: return status, cached = await self._download_observed_media(reply_msg, "replied-to media") - if status != "ok": - return - event.media_urls.append(cached.path) - event.media_types.append(cached.media_type) - if len(event.media_urls) == 1 and cached.kind in self._CACHED_KIND_TO_MESSAGE_TYPE: - event.message_type = self._CACHED_KIND_TO_MESSAGE_TYPE[cached.kind] - event.text = self._append_observed_note( - event.text, f"[Replied-to {cached.kind} '{cached.display_name}' saved at: {cached.path}]" - ) - logger.info("[Telegram] Cached replied-to %s at %s", cached.kind, cached.path) + if status == "ok": + self._attach_cached( + event, cached, f"[Replied-to {cached.kind} '{cached.display_name}' saved at: {cached.path}]", + "[Telegram] Cached replied-to %s at %s") def _observed_media_source(self, msg: Message): """Return (telegram_file_source, filename, mime, default_kind) or Nones.""" @@ -7149,68 +5241,47 @@ class TelegramAdapter(BasePlatformAdapter): def _append_observed_note(existing: Optional[str], note: str) -> str: if not note: return existing or "" - if not existing: - return note - return f"{existing}\n\n{note}" + return f"{existing}\n\n{note}" if existing else note async def _surface_media_cache_failure( - self, msg: Message, event: MessageEvent, kind: str, exc: Exception, display_name: Optional[str] = None - ) -> None: - """Surface a failed media download/cache to BOTH the user and the agent. - - A failed download (typically a transient CDN error) leaves event.media_urls empty; - without this the turn dispatches silently — user thinks it was delivered, agent sees - nothing. Reply asking to retry, and append an agent-visible observed note. - """ + self, msg: Message, event: MessageEvent, kind: str, exc: Exception, display_name: Optional[str] = None) -> None: + """Surface a failed media download to BOTH the user (reply asking to retry) and the agent (observed + note) — otherwise the turn dispatches silently with empty media_urls.""" named = f" ({display_name})" if display_name else "" try: await msg.reply_text( - f"\u26a0\ufe0f Couldn't download your {kind}{named} ({exc.__class__.__name__}). Please try sending it again." - ) + f"\u26a0\ufe0f Couldn't download your {kind}{named} ({exc.__class__.__name__}). Please try sending it again.") except Exception as reply_err: logger.warning("[Telegram] Failed to notify user about %s cache failure: %s", kind, reply_err, exc_info=True) - agent_note = ( - f"[The user attempted to send a {kind}{named} but it could not be downloaded ({exc.__class__.__name__}); they have been asked to retry.]" - ) - event.text = self._append_observed_note(event.text, agent_note) + event.text = self._append_observed_note( + event.text, + f"[The user attempted to send a {kind}{named} but it could not be downloaded ({exc.__class__.__name__}); they have been asked to retry.]", + ) def _observe_unmentioned_group_message( - self, message: Message, msg_type: MessageType, update_id: Optional[int] = None, event: Optional[MessageEvent] = None - ) -> None: + self, message: Message, msg_type: MessageType, update_id: Optional[int] = None, event: Optional[MessageEvent] = None) -> None: """Append skipped group chatter to the target session without dispatching.""" store = getattr(self, "_session_store", None) if not store: return + adapter_name = getattr(self, "name", "telegram") try: event = event or self._build_message_event(message, msg_type, update_id=update_id) - shared_source = self._telegram_group_observe_shared_source(event.source) - session_entry = store.get_or_create_session(shared_source) + session_entry = store.get_or_create_session(self._telegram_group_observe_shared_source(event.source)) entry = { - "role": "user", - "content": self._telegram_group_observe_attributed_text(event), - "timestamp": datetime.now(tz=timezone.utc).isoformat(), - "observed": True, - } + "role": "user", "content": self._telegram_group_observe_attributed_text(event), + "timestamp": datetime.now(tz=timezone.utc).isoformat(), "observed": True} if event.message_id: entry["message_id"] = str(event.message_id) store.append_to_transcript(session_entry.session_id, entry) - adapter_name = getattr(self, "name", "telegram") logger.info( - "[%s] Telegram group message observed (no bot trigger): chat=%s from=%s", - adapter_name, - getattr(getattr(message, "chat", None), "id", "unknown"), - event.source.user_id or "unknown", - ) + "[%s] Telegram group message observed (no bot trigger): chat=%s from=%s", adapter_name, + getattr(getattr(message, "chat", None), "id", "unknown"), event.source.user_id or "unknown") except Exception as exc: - adapter_name = getattr(self, "name", "telegram") logger.warning("[%s] Failed to observe Telegram group message: %s", adapter_name, exc) def _is_own_message(self, message: Message) -> bool: - """True when sent by this bot itself. - - In groups where the bot sees its own messages, getUpdates returns them as updates; - they must not count as incoming unread in the Hermes inbox. - """ + """True when sent by this bot itself (echoed getUpdates must not count as incoming unread).""" if not self._bot: return False from_user = getattr(message, "from_user", None) @@ -7221,73 +5292,38 @@ class TelegramAdapter(BasePlatformAdapter): return bot_id is not None and user_id is not None and bot_id == user_id def _should_process_message(self, message: Message, *, is_command: bool = False) -> bool: - """Apply Telegram group trigger rules. - - DMs are unrestricted. Group messages are accepted when the chat passes ``allowed_chats`` - (a hard gate; only the ``guest_mode`` explicit-@mention bypass crosses it) and then any - of: ``free_response_chats``/topic, ``require_mention`` off, reply to the bot, @mention, - or a regex wake-word match. Slash commands get no special treatment under - ``require_mention``; ``/cmd@botname`` and ``@botname /cmd`` count as mentions. - """ - # Learn the live handle BEFORE any mention gate routes on it (a rename would - # otherwise make the exclusive-mention gate misread messages addressed to us), - # then drop our own echoed messages so they never count as incoming unread. + """Apply Telegram group trigger rules: DMs unrestricted; group messages pass ``allowed_chats`` (hard gate; only + the ``guest_mode`` @mention bypass crosses it) and then any of free_response chat/topic, ``require_mention`` + off, reply to the bot, @mention (incl. ``/cmd@botname``), or a wake-word match.""" + # Learn the live handle BEFORE any mention gate routes on it, then drop our own echoed messages. self._observe_bot_identity_from_message(message) if self._is_own_message(message): return False if not self._is_group_chat(message): return True thread_id = self._effective_message_thread_id(message) - allowed_topics = self._telegram_allowed_topics() - if allowed_topics: - topic_id = str(thread_id) if thread_id is not None else self._GENERAL_TOPIC_THREAD_ID - if topic_id not in allowed_topics: - return False - - # ignored_threads applies to both groups and DM topics - if thread_id is not None: - try: - if int(thread_id) in self._telegram_ignored_threads(): - return False - except (TypeError, ValueError): - logger.warning("[%s] Ignoring non-numeric Telegram message_thread_id: %r", self.name, thread_id) - if not self._is_group_chat(message): - # Root DM (non-topic): ignore if ignore_root_dm is configured - if thread_id is None and self.config.extra.get("ignore_root_dm", False): - chat_id = str(getattr(getattr(message, "chat", None), "id", "")) - if not is_command and chat_id in self._dm_topic_chat_ids: - return False - return True - chat_id_str = str(getattr(getattr(message, "chat", None), "id", "")) + if self._topic_gates_pass(thread_id, warn_non_numeric=True) is False: + return False + chat_id_str = self._chat_id_str(message) if self._telegram_exclusive_bot_mentions() and self._explicit_bot_mentions_exclude_self(message): return False - # Resolve once; _message_mentions_bot is not re-called below in guest mode. guest_mention = self._is_guest_mention(message) # allowed_chats whitelist: outside chats pass only via the guest-mode explicit mention. allowed = self._telegram_allowed_chats() if allowed and chat_id_str not in allowed: return guest_mention - if guest_mention: + if guest_mention or chat_id_str in self._telegram_free_response_chats() or self._telegram_is_free_response_topic(message): return True - if chat_id_str in self._telegram_free_response_chats(): - return True - if self._telegram_is_free_response_topic(message): - return True - if not self._telegram_require_mention(): - return True - if self._is_reply_to_bot(message): + if not self._telegram_require_mention() or self._is_reply_to_bot(message): return True if not self._telegram_guest_mode() and self._message_mentions_bot(message): return True return self._message_matches_mention_patterns(message) async def _ensure_forum_commands(self, message) -> None: - """Lazy-register bot commands for forum supergroups. - - Forum topics don't inherit AllGroupChats scope (Telegram resolves via - BotCommandScopeChat), so register on first message for the topic-view menu. - """ + """Lazy-register bot commands for forum supergroups (topics don't inherit AllGroupChats scope; + Telegram resolves via BotCommandScopeChat).""" async with self._forum_lock: try: chat = getattr(message, "chat", None) @@ -7307,37 +5343,42 @@ class TelegramAdapter(BasePlatformAdapter): logger.warning("[%s] Forum command lazy-registration failed: %s", self.name, _redact_telegram_error_text(e)) def _effective_update_message(self, update: Update) -> Optional[Message]: - """Message-like payload for normal messages and channel posts. - - Channel broadcasts arrive as ``update.channel_post``, not ``update.message``; using - ``effective_message`` keeps handlers from consuming them without building an event. - """ + """Message-like payload for normal messages and channel posts (``update.channel_post``).""" return getattr(update, "effective_message", None) or getattr(update, "message", None) + def _log_blocked_user(self, msg, *, level=logging.WARNING, what: str = "unauthorized user") -> None: + logger.log( + level, "[Telegram] Blocked %s %s in chat %s", what, getattr(getattr(msg, "from_user", None), "id", None), + getattr(getattr(msg, "chat", None), "id", None)) + + def _gate_or_observe(self, msg, update, msg_type: MessageType) -> bool: + """Group trigger gate; observes unmentioned chatter when configured. True = proceed.""" + if self._should_process_message(msg): + return True + if self._should_observe_unmentioned_group_message(msg): + self._observe_unmentioned_group_message(msg, msg_type, update_id=update.update_id) + return False + + async def _build_triggered_event(self, msg, update, msg_type: MessageType) -> MessageEvent: + """Event for an addressed text/command: trigger text cleaned, replied-to media cached, attribution applied.""" + event = self._build_message_event(msg, msg_type, update_id=update.update_id) + event.text = self._clean_bot_trigger_text(event.text) + await self._cache_replied_media(msg, event) + return self._apply_telegram_group_observe_attribution(event) + async def _handle_text_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: """Handle incoming text; buffers client-split chunks into one MessageEvent.""" msg = self._effective_update_message(update) if not msg or not msg.text: return - # Auth check first: blocked users must not reach batching, the observed - # transcript, or the agent path. + # Auth check first: blocked users must not reach batching, the observed transcript, or the agent. if not self._is_user_authorized_from_message(msg): - logger.warning( - "[Telegram] Blocked unauthorized user %s in chat %s", - getattr(getattr(msg, "from_user", None), "id", None), - getattr(getattr(msg, "chat", None), "id", None), - ) + self._log_blocked_user(msg) return - if not self._should_process_message(msg): - if self._should_observe_unmentioned_group_message(msg): - self._observe_unmentioned_group_message(msg, MessageType.TEXT, update_id=update.update_id) + if not self._gate_or_observe(msg, update, MessageType.TEXT): return await self._ensure_forum_commands(update.message) - event = self._build_message_event(msg, MessageType.TEXT, update_id=update.update_id) - event.text = self._clean_bot_trigger_text(event.text) - await self._cache_replied_media(msg, event) - event = self._apply_telegram_group_observe_attribution(event) - self._enqueue_text_event(event) + self._enqueue_text_event(await self._build_triggered_event(msg, update, MessageType.TEXT)) async def _handle_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: """Handle incoming command messages.""" @@ -7347,20 +5388,12 @@ class TelegramAdapter(BasePlatformAdapter): if not self._should_process_message(msg, is_command=True): return if not self._is_user_authorized_from_message(msg): - logger.warning( - "[Telegram] Blocked unauthorized user %s in chat %s", - getattr(getattr(msg, "from_user", None), "id", None), - getattr(getattr(msg, "chat", None), "id", None), - ) + self._log_blocked_user(msg) return await self._ensure_forum_commands(msg) - event = self._build_message_event(msg, MessageType.COMMAND, update_id=update.update_id) - event.text = self._clean_bot_trigger_text(event.text) - await self._cache_replied_media(msg, event) - event = self._apply_telegram_group_observe_attribution(event) - # A >4096-char command paste arrives as a near-limit COMMAND chunk plus TEXT - # continuations; dispatching immediately would orphan them (and interrupt the - # agent). Near-limit commands go through text batching; short ones stay immediate. + event = await self._build_triggered_event(msg, update, MessageType.COMMAND) + # A >4096-char command paste arrives as a near-limit COMMAND chunk plus TEXT continuations; dispatching + # immediately would orphan them. Near-limit commands go through text batching. if len(event.text or "") >= self._SPLIT_THRESHOLD: self._enqueue_text_event(event) return @@ -7372,15 +5405,9 @@ class TelegramAdapter(BasePlatformAdapter): if not msg: return if not self._is_user_authorized_from_message(msg): - logger.warning( - "[Telegram] Blocked unauthorized user %s in chat %s", - getattr(getattr(msg, "from_user", None), "id", None), - getattr(getattr(msg, "chat", None), "id", None), - ) + self._log_blocked_user(msg) return - if not self._should_process_message(msg): - if self._should_observe_unmentioned_group_message(msg): - self._observe_unmentioned_group_message(msg, MessageType.LOCATION, update_id=update.update_id) + if not self._gate_or_observe(msg, update, MessageType.LOCATION): return venue = getattr(msg, "venue", None) location = getattr(venue, "location", None) if venue else getattr(msg, "location", None) @@ -7398,20 +5425,17 @@ class TelegramAdapter(BasePlatformAdapter): parts.append(f"Venue: {title}") if address: parts.append(f"Address: {address}") - parts.append(f"latitude: {lat}") - parts.append(f"longitude: {lon}") - parts.append(f"Map: https://www.google.com/maps/search/?api=1&query={lat},{lon}") - parts.append("Ask what they'd like to find nearby (restaurants, cafes, etc.) and any preferences.") + parts += [ + f"latitude: {lat}", f"longitude: {lon}", f"Map: https://www.google.com/maps/search/?api=1&query={lat},{lon}", + "Ask what they'd like to find nearby (restaurants, cafes, etc.) and any preferences."] event = self._build_message_event(msg, MessageType.LOCATION, update_id=update.update_id) event.text = "\n".join(parts) - event = self._apply_telegram_group_observe_attribution(event) - await self.handle_message(event) + await self.handle_message(self._apply_telegram_group_observe_attribution(event)) # -- Text message aggregation (handles Telegram client-side splits) -- def _text_batch_key(self, event: MessageEvent) -> str: - """Session-scoped batching key; topic recovery first so DM-topic batches coalesce on - the recovered lane, not the raw inbound thread id.""" + """Session-scoped batching key; topic recovery first so DM-topic batches coalesce on the recovered lane.""" self._apply_topic_recovery(event) return super()._text_batch_key(event) @@ -7422,44 +5446,50 @@ class TelegramAdapter(BasePlatformAdapter): return super()._enqueue_text_event(event) - async def _flush_text_batch(self, key: str) -> None: - """Wait for the quiet period then dispatch the aggregated text.""" + async def _flush_buffered(self, pending: dict, tasks: dict, key: str, delay: float, where: str, log_fn=None) -> None: + """Shared delayed-flush body: sleep, pop, hold if teardown started, else dispatch. A cancel after + the pop but before durable dispatch re-holds the event (never lose it).""" current_task = asyncio.current_task() event = None try: - # Adaptive delay: near-split-point last chunk → long delay (continuation almost - # certain); short/medium totals → capped fast delays; else configured cap. All - # tiers are min()'d with the operator's ``_text_batch_delay_seconds`` override. - pending = self._pending_text_batches.get(key) - last_len = getattr(pending, "_last_chunk_len", 0) if pending else 0 - total_len = len(getattr(pending, "text", "") or "") if pending else 0 - if last_len >= self._SPLIT_THRESHOLD: - delay = self._text_batch_split_delay_seconds - elif total_len <= self._TEXT_BATCH_FAST_LEN: - delay = min(self._text_batch_delay_seconds, self._TEXT_BATCH_FAST_DELAY_S) - elif total_len <= self._TEXT_BATCH_SHORT_LEN: - delay = min(self._text_batch_delay_seconds, self._TEXT_BATCH_SHORT_DELAY_S) - else: - delay = self._text_batch_delay_seconds await asyncio.sleep(delay) - event = self._pending_text_batches.pop(key, None) + event = pending.pop(key, None) if not event: return if self._should_drop_delayed_delivery(): - self._hold_inbound_event(event, where="text-flush") + self._hold_inbound_event(event, where=f"{where}-flush") event = None return - logger.info("[Telegram] Flushing text batch %s (%d chars)", key, len(event.text or "")) + if log_fn is not None: + log_fn(event) await self.handle_message(event) event = None except asyncio.CancelledError: - # Cancelled after pop but before durable dispatch — hold, don't lose. if event is not None: - self._hold_inbound_event(event, where="text-flush-cancelled") + self._hold_inbound_event(event, where=f"{where}-flush-cancelled") raise finally: - if self._pending_text_batch_tasks.get(key) is current_task: - self._pending_text_batch_tasks.pop(key, None) + if tasks.get(key) is current_task: + tasks.pop(key, None) + + async def _flush_text_batch(self, key: str) -> None: + """Wait for the quiet period then dispatch the aggregated text.""" + # Adaptive delay: near-split-point last chunk → long delay (continuation almost certain); + # short/medium totals → capped fast delays; else configured cap (all min()'d with the operator cap). + pending = self._pending_text_batches.get(key) + last_len = getattr(pending, "_last_chunk_len", 0) if pending else 0 + total_len = len(getattr(pending, "text", "") or "") if pending else 0 + if last_len >= self._SPLIT_THRESHOLD: + delay = self._text_batch_split_delay_seconds + elif total_len <= self._TEXT_BATCH_FAST_LEN: + delay = min(self._text_batch_delay_seconds, self._TEXT_BATCH_FAST_DELAY_S) + elif total_len <= self._TEXT_BATCH_SHORT_LEN: + delay = min(self._text_batch_delay_seconds, self._TEXT_BATCH_SHORT_DELAY_S) + else: + delay = self._text_batch_delay_seconds + await self._flush_buffered( + self._pending_text_batches, self._pending_text_batch_tasks, key, delay, "text", + lambda ev: logger.info("[Telegram] Flushing text batch %s (%d chars)", key, len(ev.text or ""))) # -- Photo batching -- @@ -7467,53 +5497,35 @@ class TelegramAdapter(BasePlatformAdapter): """Return a batching key for Telegram photos/albums.""" from gateway.session import build_session_key session_key = build_session_key( - event.source, - group_sessions_per_user=self.config.extra.get("group_sessions_per_user", True), + 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), - ) + profile=self._session_key_profile(event.source)) media_group_id = getattr(msg, "media_group_id", None) - if media_group_id: - return f"{session_key}:album:{media_group_id}" - return f"{session_key}:photo-burst" + return f"{session_key}:album:{media_group_id}" if media_group_id else f"{session_key}:photo-burst" async def _flush_photo_batch(self, batch_key: str) -> None: """Send a buffered photo burst/album as a single MessageEvent.""" - current_task = asyncio.current_task() - event = None - try: - await asyncio.sleep(self._media_batch_delay_seconds) - event = self._pending_photo_batches.pop(batch_key, None) - if not event: - return - if self._should_drop_delayed_delivery(): - self._hold_inbound_event(event, where="photo-flush") - event = None - return - logger.info("[Telegram] Flushing photo batch %s with %d image(s)", batch_key, len(event.media_urls)) - await self.handle_message(event) - event = None - except asyncio.CancelledError: - if event is not None: - self._hold_inbound_event(event, where="photo-flush-cancelled") - raise - finally: - if self._pending_photo_batch_tasks.get(batch_key) is current_task: - self._pending_photo_batch_tasks.pop(batch_key, None) + await self._flush_buffered( + self._pending_photo_batches, self._pending_photo_batch_tasks, batch_key, self._media_batch_delay_seconds, "photo", + lambda ev: logger.info("[Telegram] Flushing photo batch %s with %d image(s)", batch_key, len(ev.media_urls))) + + def _merge_into_pending(self, pending: dict, key: str, event: MessageEvent) -> None: + """Merge ``event`` into ``pending[key]`` (media + caption) or seed it.""" + existing = pending.get(key) + if existing is None: + pending[key] = event + return + existing.media_urls.extend(event.media_urls) + existing.media_types.extend(event.media_types) + if event.text: + existing.text = self._merge_caption(existing.text, event.text) def _enqueue_photo_event(self, batch_key: str, event: MessageEvent) -> None: """Merge photo events into a pending batch and schedule flush.""" if self._should_drop_delayed_delivery(): self._hold_inbound_event(event, where="photo-enqueue") return - existing = self._pending_photo_batches.get(batch_key) - if existing is None: - self._pending_photo_batches[batch_key] = event - else: - existing.media_urls.extend(event.media_urls) - existing.media_types.extend(event.media_types) - if event.text: - existing.text = self._merge_caption(existing.text, event.text) + self._merge_into_pending(self._pending_photo_batches, batch_key, event) prior_task = self._pending_photo_batch_tasks.get(batch_key) if prior_task and not prior_task.done(): prior_task.cancel() @@ -7527,14 +5539,19 @@ class TelegramAdapter(BasePlatformAdapter): else: self._enqueue_photo_event(self._photo_batch_key(event, msg), event) - async def _cache_inbound_av( - self, msg, event: MessageEvent, source: Any, label: str, kind: str, ext: str, mime: str, - ) -> bool: - """Download a voice/audio/video attachment into the local cache. + @staticmethod + def _ext_from_path(file_path: Optional[str], candidates, default: str) -> str: + """First extension in ``candidates`` that ``file_path`` ends with (case-insensitive), else default.""" + if file_path: + lowered = file_path.lower() + for candidate in candidates: + if lowered.endswith(candidate): + return candidate + return default - Returns True when the event was already dispatched (oversized attachment), - so the caller must return. Video resolves ``ext``/``mime`` from the file path. - """ + async def _cache_inbound_av(self, msg, event: MessageEvent, source: Any, label: str, kind: str, ext: str, mime: str) -> bool: + """Download a voice/audio/video attachment into the local cache. Returns True when the event was + already dispatched (oversized attachment), so the caller must return.""" try: allowed, note = self._telegram_media_size_allowed(source, label) if not allowed: @@ -7545,11 +5562,7 @@ class TelegramAdapter(BasePlatformAdapter): file_obj = await source.get_file() data = await file_obj.download_as_bytearray() if kind == "video": - if getattr(file_obj, "file_path", None): - for candidate in SUPPORTED_VIDEO_TYPES: - if file_obj.file_path.lower().endswith(candidate): - ext = candidate - break + ext = self._ext_from_path(getattr(file_obj, "file_path", None), SUPPORTED_VIDEO_TYPES, ext) cached_path = cache_video_from_bytes(bytes(data), ext=ext) mime = SUPPORTED_VIDEO_TYPES.get(ext, "video/mp4") else: @@ -7562,64 +5575,139 @@ class TelegramAdapter(BasePlatformAdapter): await self._surface_media_cache_failure(msg, event, label, e) return False + async def _dispatch_with_text(self, event: MessageEvent, text: str) -> bool: + """Replace the event text with a user-facing note and dispatch it; returns True (handled).""" + event.text = text + await self.handle_message(event) + return True + + @staticmethod + def _set_cached_media(event: MessageEvent, path: str, mime: str, mtype: MessageType, log_fmt: str) -> None: + event.media_urls = [path] + event.media_types = [mime] + event.message_type = mtype + logger.info(log_fmt, path) + + async def _cache_inbound_document(self, msg, event: MessageEvent) -> bool: + """Cache a document attachment (image → photo path, video, else generic media + text injection). + Returns True when the event was already dispatched/routed so the caller must return.""" + doc = msg.document + try: + original_filename = doc.file_name or "" + ext = os.path.splitext(original_filename)[1].lower() if original_filename else "" + doc_mime = (doc.mime_type or "").lower() # some clients send "IMAGE/PNG" + if not ext and doc_mime: + ext = _TELEGRAM_IMAGE_MIME_TO_EXT.get(doc_mime, "") + if not ext: + ext = {v: k for k, v in SUPPORTED_DOCUMENT_TYPES.items()}.get(doc_mime, "") + display = original_filename or doc_mime or ext or 'unknown' + # Size check before the image branch so image documents can't bypass the limit. + if not doc.file_size or doc.file_size > self._max_doc_bytes: + logger.info("[Telegram] Document too large: %s bytes", doc.file_size) + return await self._dispatch_with_text( + event, f"The document is too large or its size could not be verified. Maximum: {self._max_doc_bytes // (1024 * 1024)} MB.") + # Screenshots/photos sent as documents take the image cache + batching path. + if ext in _TELEGRAM_IMAGE_EXTENSIONS or doc_mime.startswith("image/"): + file_obj = await doc.get_file() + image_bytes = await file_obj.download_as_bytearray() + image_ext = ext if ext in _TELEGRAM_IMAGE_EXTENSIONS else _TELEGRAM_IMAGE_MIME_TO_EXT.get(doc_mime, ".jpg") + try: + cached_path = cache_image_from_bytes(bytes(image_bytes), ext=image_ext) + except ValueError as e: + logger.warning("[Telegram] Failed to cache image document: %s", _redact_telegram_error_text(e), exc_info=True) + return await self._dispatch_with_text(event, f"Image document '{display}' could not be read as an image.") + self._set_cached_media( + event, cached_path, doc_mime if doc_mime.startswith( + "image/" + ) else _TELEGRAM_IMAGE_EXT_TO_MIME.get(image_ext, "image/jpeg"), + MessageType.PHOTO, "[Telegram] Cached user image-document at %s") + await self._route_photo_event(msg, event) + return True + if not ext and doc.mime_type: + ext = {v: k for k, v in SUPPORTED_VIDEO_TYPES.items()}.get(doc.mime_type, "") + if not ext and doc.mime_type: + # .jpg and .jpeg both map to image/jpeg; keep the first ext seen. + image_mime_to_ext: dict[str, str] = {} + for _ext, _mime in SUPPORTED_IMAGE_DOCUMENT_TYPES.items(): + image_mime_to_ext.setdefault(_mime, _ext) + ext = image_mime_to_ext.get(doc.mime_type, "") + if ext in SUPPORTED_VIDEO_TYPES: + file_obj = await doc.get_file() + video_bytes = await file_obj.download_as_bytearray() + self._set_cached_media( + event, cache_video_from_bytes(bytes(video_bytes), ext=ext), SUPPORTED_VIDEO_TYPES[ext], MessageType.VIDEO, + "[Telegram] Cached user video document at %s") + await self.handle_message(event) + return True + # Any file type is accepted (authorization is the gate, not the extension); unknown types get + # application/octet-stream. Image documents already returned above. + file_obj = await doc.get_file() + raw_bytes = bytes(await file_obj.download_as_bytearray()) + from gateway.platforms.base import cache_media_bytes + cached = cache_media_bytes(raw_bytes, filename=original_filename or f"document{ext or '.bin'}", mime_type=doc_mime) + if cached is None: + return await self._dispatch_with_text(event, f"Document '{display}' could not be cached.") + event.media_urls = [cached.path] + event.media_types = [cached.media_type] + if cached.kind == "audio": + event.message_type = MessageType.AUDIO + logger.info("[Telegram] Cached user %s at %s (%s)", cached.kind, cached.path, cached.media_type) + # Inject text-readable content (≤100 KB). Gate on extension/MIME, NOT a blind UTF-8 decode: + # PDF/zip/docx have decodable ASCII headers. Binary files are surfaced as a cached path only. + MAX_TEXT_INJECT_BYTES = 100 * 1024 + _is_text = ext in _TEXT_INJECT_EXTENSIONS or (doc_mime or "").startswith("text/") + if _is_text and len(raw_bytes) <= MAX_TEXT_INJECT_BYTES: + try: + text_content = raw_bytes.decode("utf-8") + display_name = re.sub(r'[^\w.\- ]', '_', original_filename or f"document{ext or '.txt'}") + injection = f"[Content of {display_name}]:\n{text_content}" + event.text = f"{injection}\n\n{event.text}" if event.text else injection + except UnicodeDecodeError: + pass # binary — agent has the cached path + except Exception as e: + logger.warning("[Telegram] Failed to cache document: %s", _redact_telegram_error_text(e), exc_info=True) + await self._surface_media_cache_failure(msg, event, "attachment", e, display_name=getattr(doc, "file_name", None) or None) + return False + async def _handle_media_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: """Handle incoming media messages, downloading images to local cache.""" - if not update.message: - return - if not self._is_user_authorized_from_message(update.message): - logger.info( - "[Telegram] Blocked media from unauthorized user %s in chat %s", - getattr(getattr(update.message, "from_user", None), "id", None), - getattr(getattr(update.message, "chat", None), "id", None), - ) - return - if not self._should_process_message(update.message): - if self._should_observe_unmentioned_group_message(update.message): - _m = update.message - _observe_type = self._media_message_type(_m) - _event = self._build_message_event(_m, _observe_type, update_id=update.update_id) - if _m.caption: - _event.text = self._clean_bot_trigger_text(_m.caption) - await self._cache_observed_media(_m, _event) - self._observe_unmentioned_group_message(_m, _event.message_type, update_id=update.update_id, event=_event) - return msg = update.message - msg_type = self._media_message_type(msg) - event = self._build_message_event(msg, msg_type, update_id=update.update_id) + if not msg: + return + if not self._is_user_authorized_from_message(msg): + self._log_blocked_user(msg, level=logging.INFO, what="media from unauthorized user") + return + if not self._should_process_message(msg): + if self._should_observe_unmentioned_group_message(msg): + _event = self._build_message_event(msg, self._media_message_type(msg), update_id=update.update_id) + if msg.caption: + _event.text = self._clean_bot_trigger_text(msg.caption) + await self._cache_observed_media(msg, _event) + self._observe_unmentioned_group_message(msg, _event.message_type, update_id=update.update_id, event=_event) + return + event = self._build_message_event(msg, self._media_message_type(msg), update_id=update.update_id) if msg.caption: event.text = self._clean_bot_trigger_text(msg.caption) - - # Stickers: _handle_sticker overwrites event.text with its vision description, so - # observe attribution must run after it. + # Stickers: _handle_sticker overwrites event.text with its vision description, so observe attribution must run after it. if msg.sticker: await self._handle_sticker(msg, event) - event = self._apply_telegram_group_observe_attribution(event) - await self.handle_message(event) + await self.handle_message(self._apply_telegram_group_observe_attribution(event)) return event = self._apply_telegram_group_observe_attribution(event) - # Cache photo locally: Telegram's file URLs expire (~1 hour) before vision may run. if msg.photo: try: - photo = msg.photo[-1] # PhotoSize list sorted by size; largest last - file_obj = await photo.get_file() + file_obj = await msg.photo[-1].get_file() # PhotoSize list sorted by size; largest last image_bytes = await file_obj.download_as_bytearray() - ext = ".jpg" - if file_obj.file_path: - for candidate in [".png", ".webp", ".gif", ".jpeg", ".jpg"]: - if file_obj.file_path.lower().endswith(candidate): - ext = candidate - break - cached_path = cache_image_from_bytes(bytes(image_bytes), ext=ext) - event.media_urls = [cached_path] - event.media_types = [f"image/{ext.lstrip('.')}"] - logger.info("[Telegram] Cached user photo at %s", cached_path) + ext = self._ext_from_path(file_obj.file_path, [".png", ".webp", ".gif", ".jpeg", ".jpg"], ".jpg") + self._set_cached_media( + event, cache_image_from_bytes(bytes(image_bytes), ext=ext), f"image/{ext.lstrip('.')}", event.message_type, + "[Telegram] Cached user photo at %s") await self._route_photo_event(msg, event) return except Exception as e: logger.warning("[Telegram] Failed to cache photo: %s", _redact_telegram_error_text(e), exc_info=True) await self._surface_media_cache_failure(msg, event, "photo", e) - # Voice/audio cached for STT transcription; video for vision. if msg.voice: if await self._cache_inbound_av(msg, event, msg.voice, "voice message", "voice", ".ogg", "audio/ogg"): @@ -7630,109 +5718,8 @@ class TelegramAdapter(BasePlatformAdapter): elif msg.video: if await self._cache_inbound_av(msg, event, msg.video, "video file", "video", ".mp4", "video/mp4"): return - elif msg.document: - doc = msg.document - try: - ext = "" - original_filename = doc.file_name or "" - if original_filename: - _, ext = os.path.splitext(original_filename) - ext = ext.lower() - doc_mime = (doc.mime_type or "").lower() # some clients send "IMAGE/PNG" - if not ext and doc_mime: - ext = _TELEGRAM_IMAGE_MIME_TO_EXT.get(doc_mime, "") - if not ext: - mime_to_ext = {v: k for k, v in SUPPORTED_DOCUMENT_TYPES.items()} - ext = mime_to_ext.get(doc_mime, "") - - # Size check before the image branch so image documents can't bypass the limit. - if not doc.file_size or doc.file_size > self._max_doc_bytes: - limit_mb = self._max_doc_bytes // (1024 * 1024) - event.text = f"The document is too large or its size could not be verified. Maximum: {limit_mb} MB." - logger.info("[Telegram] Document too large: %s bytes", doc.file_size) - await self.handle_message(event) - return - - # Screenshots/photos sent as documents take the image cache + batching path. - if ext in _TELEGRAM_IMAGE_EXTENSIONS or doc_mime.startswith("image/"): - file_obj = await doc.get_file() - image_bytes = await file_obj.download_as_bytearray() - image_ext = ext if ext in _TELEGRAM_IMAGE_EXTENSIONS else _TELEGRAM_IMAGE_MIME_TO_EXT.get(doc_mime, ".jpg") - try: - cached_path = cache_image_from_bytes(bytes(image_bytes), ext=image_ext) - except ValueError as e: - logger.warning("[Telegram] Failed to cache image document: %s", _redact_telegram_error_text(e), exc_info=True) - event.text = f"Image document '{original_filename or doc_mime or ext or 'unknown'}' could not be read as an image." - await self.handle_message(event) - return - event.message_type = MessageType.PHOTO - event.media_urls = [cached_path] - event.media_types = [doc_mime if doc_mime.startswith("image/") else _TELEGRAM_IMAGE_EXT_TO_MIME.get(image_ext, "image/jpeg")] - logger.info("[Telegram] Cached user image-document at %s", cached_path) - await self._route_photo_event(msg, event) - return - if not ext and doc.mime_type: - video_mime_to_ext = {v: k for k, v in SUPPORTED_VIDEO_TYPES.items()} - ext = video_mime_to_ext.get(doc.mime_type, "") - if not ext and doc.mime_type: - # .jpg and .jpeg both map to image/jpeg; keep the first ext seen. - image_mime_to_ext: dict[str, str] = {} - for _ext, _mime in SUPPORTED_IMAGE_DOCUMENT_TYPES.items(): - image_mime_to_ext.setdefault(_mime, _ext) - ext = image_mime_to_ext.get(doc.mime_type, "") - if ext in SUPPORTED_VIDEO_TYPES: - file_obj = await doc.get_file() - video_bytes = await file_obj.download_as_bytearray() - cached_path = cache_video_from_bytes(bytes(video_bytes), ext=ext) - event.media_urls = [cached_path] - event.media_types = [SUPPORTED_VIDEO_TYPES[ext]] - event.message_type = MessageType.VIDEO - logger.info("[Telegram] Cached user video document at %s", cached_path) - await self.handle_message(event) - return - - # Any file type is accepted (authorization is the gate, not the extension). - # Image documents already returned above — an ext-in-SUPPORTED_IMAGE_DOCUMENT_TYPES - # branch here would be dead code. Unknown types get application/octet-stream. - file_obj = await doc.get_file() - doc_bytes = await file_obj.download_as_bytearray() - raw_bytes = bytes(doc_bytes) - from gateway.platforms.base import cache_media_bytes - cached = cache_media_bytes( - raw_bytes, filename=original_filename or f"document{ext or '.bin'}", mime_type=doc_mime - ) - if cached is None: - event.text = f"Document '{original_filename or doc_mime or ext or 'unknown'}' could not be cached." - await self.handle_message(event) - return - event.media_urls = [cached.path] - event.media_types = [cached.media_type] - if cached.kind == "audio": - event.message_type = MessageType.AUDIO - logger.info("[Telegram] Cached user %s at %s (%s)", cached.kind, cached.path, cached.media_type) - - # Inject text-readable content (≤100 KB). Gate on extension/MIME, NOT a blind - # UTF-8 decode: PDF/zip/docx have decodable ASCII headers. Binary files are - # surfaced as a cached path only. - MAX_TEXT_INJECT_BYTES = 100 * 1024 - _is_text = ext in _TEXT_INJECT_EXTENSIONS or (doc_mime or "").startswith("text/") - if _is_text and len(raw_bytes) <= MAX_TEXT_INJECT_BYTES: - try: - text_content = raw_bytes.decode("utf-8") - display_name = original_filename or f"document{ext or '.txt'}" - display_name = re.sub(r'[^\w.\- ]', '_', display_name) - injection = f"[Content of {display_name}]:\n{text_content}" - if event.text: - event.text = f"{injection}\n\n{event.text}" - else: - event.text = injection - except UnicodeDecodeError: - pass # binary — agent has the cached path - except Exception as e: - logger.warning("[Telegram] Failed to cache document: %s", _redact_telegram_error_text(e), exc_info=True) - await self._surface_media_cache_failure( - msg, event, "attachment", e, display_name=getattr(doc, "file_name", None) or None - ) + elif msg.document and await self._cache_inbound_document(msg, event): + return media_group_id = getattr(msg, "media_group_id", None) if media_group_id: await self._queue_media_group_event(str(media_group_id), event) @@ -7740,59 +5727,26 @@ class TelegramAdapter(BasePlatformAdapter): await self.handle_message(event) async def _queue_media_group_event(self, media_group_id: str, event: MessageEvent) -> None: - """Debounce album items (shared media_group_id) into one MessageEvent. - - Forwarding each item immediately would make the gateway treat the second image as a - new message that interrupts the first. - """ + """Debounce album items (shared media_group_id) into one MessageEvent so the second image isn't + treated as a new message interrupting the first.""" if self._should_drop_delayed_delivery(): self._hold_inbound_event(event, where="media-group-enqueue") return - existing = self._media_group_events.get(media_group_id) - if existing is None: - self._media_group_events[media_group_id] = event - else: - existing.media_urls.extend(event.media_urls) - existing.media_types.extend(event.media_types) - if event.text: - existing.text = self._merge_caption(existing.text, event.text) + self._merge_into_pending(self._media_group_events, media_group_id, event) prior_task = self._media_group_tasks.get(media_group_id) if prior_task: prior_task.cancel() self._media_group_tasks[media_group_id] = asyncio.create_task(self._flush_media_group_event(media_group_id)) async def _flush_media_group_event(self, media_group_id: str) -> None: - current_task = asyncio.current_task() - event = None - try: - await asyncio.sleep(self.MEDIA_GROUP_WAIT_SECONDS) - event = self._media_group_events.pop(media_group_id, None) - if event is None: - return - if self._should_drop_delayed_delivery(): - self._hold_inbound_event(event, where="media-group-flush") - event = None - return - await self.handle_message(event) - event = None - except asyncio.CancelledError: - # Cancelled after pop but before durable dispatch — hold, don't lose. - if event is not None: - self._hold_inbound_event(event, where="media-group-flush-cancelled") - raise - finally: - if self._media_group_tasks.get(media_group_id) is current_task: - self._media_group_tasks.pop(media_group_id, None) + await self._flush_buffered( + self._media_group_events, self._media_group_tasks, media_group_id, self.MEDIA_GROUP_WAIT_SECONDS, "media-group") async def _handle_sticker(self, msg: Message, event: "MessageEvent") -> None: - """Describe a sticker via vision, cached by file_unique_id. - - Animated/video stickers can't be analyzed as static images; they get an emoji placeholder. - """ + """Describe a sticker via vision, cached by file_unique_id; animated/video stickers get an emoji placeholder.""" from gateway.sticker_cache import ( get_cached_description, cache_sticker_description, build_sticker_injection, - build_animated_sticker_injection, STICKER_VISION_PROMPT, - ) + build_animated_sticker_injection, STICKER_VISION_PROMPT) sticker = msg.sticker emoji = sticker.emoji or "" set_name = sticker.set_name or "" @@ -7804,37 +5758,34 @@ class TelegramAdapter(BasePlatformAdapter): event.text = build_sticker_injection(cached["description"], cached.get("emoji", emoji), cached.get("set_name", set_name)) logger.info("[Telegram] Sticker cache hit: %s", sticker.file_unique_id) return + fallback = f"a sticker with emoji {emoji}" if emoji else "a sticker" try: file_obj = await sticker.get_file() image_bytes = await file_obj.download_as_bytearray() cached_path = cache_image_from_bytes(bytes(image_bytes), ext=".webp") logger.info("[Telegram] Analyzing sticker at %s", cached_path) from tools.vision_tools import vision_analyze_tool - result_json = await vision_analyze_tool(image_url=cached_path, user_prompt=STICKER_VISION_PROMPT) - result = json.loads(result_json) + result = json.loads(await vision_analyze_tool(image_url=cached_path, user_prompt=STICKER_VISION_PROMPT)) if result.get("success"): description = result.get("analysis", "a sticker") cache_sticker_description(sticker.file_unique_id, description, emoji, set_name) event.text = build_sticker_injection(description, emoji, set_name) else: - event.text = build_sticker_injection(f"a sticker with emoji {emoji}" if emoji else "a sticker", emoji, set_name) + event.text = build_sticker_injection(fallback, emoji, set_name) except Exception as e: logger.warning("[Telegram] Sticker analysis error: %s", _redact_telegram_error_text(e), exc_info=True) - event.text = build_sticker_injection(f"a sticker with emoji {emoji}" if emoji else "a sticker", emoji, set_name) + event.text = build_sticker_injection(fallback, emoji, set_name) def _reload_dm_topics_from_config(self) -> None: """Re-read dm_topics from config.yaml so externally created topics work without restart.""" try: - # Canonical loader: honors managed-scope overlay + ${VAR} expansion. - from hermes_cli.config import load_config_readonly - config = load_config_readonly() - dm_topics = config.get("platforms", {}).get("telegram", {}).get("extra", {}).get("dm_topics", []) + from hermes_cli.config import load_config_readonly # canonical loader: managed overlay + ${VAR} + dm_topics = load_config_readonly().get("platforms", {}).get("telegram", {}).get("extra", {}).get("dm_topics", []) if not dm_topics: self._dm_topics_config = [] self._dm_topic_chat_ids = set() return self._dm_topics_config = dm_topics - # chat_id set gives O(1) root-DM ignore lookup self._dm_topic_chat_ids = {str(chat_entry["chat_id"]) for chat_entry in dm_topics if "chat_id" in chat_entry} for chat_entry in dm_topics: cid = chat_entry.get("chat_id") @@ -7843,11 +5794,9 @@ class TelegramAdapter(BasePlatformAdapter): for t in chat_entry.get("topics", []): tid = t.get("thread_id") name = t.get("name") - if tid and name: - cache_key = f"{cid}:{name}" - if cache_key not in self._dm_topics: - self._dm_topics[cache_key] = int(tid) - logger.info("[%s] Hot-loaded DM topic from config: %s -> thread_id=%s", self.name, cache_key, tid) + if tid and name and f"{cid}:{name}" not in self._dm_topics: + self._dm_topics[f"{cid}:{name}"] = int(tid) + logger.info("[%s] Hot-loaded DM topic from config: %s -> thread_id=%s", self.name, f"{cid}:{name}", tid) except Exception as e: logger.debug("[%s] Failed to reload dm_topics from config: %s", self.name, e) @@ -7872,8 +5821,7 @@ class TelegramAdapter(BasePlatformAdapter): found = _lookup() if found is not None: return found - # Cache miss — hot-reload in case topics were added externally, then retry. - self._reload_dm_topics_from_config() + self._reload_dm_topics_from_config() # cache miss — topics may have been added externally return _lookup() def _cache_dm_topic_from_message(self, chat_id: str, thread_id: str, topic_name: str) -> None: @@ -7893,12 +5841,9 @@ class TelegramAdapter(BasePlatformAdapter): if isinstance(value, list): return "".join(cls._flatten_rich_inline_text(item) for item in value) if isinstance(value, dict): - text = value.get("text") - if text is not None: - return cls._flatten_rich_inline_text(text) - children = value.get("children") - if children is not None: - return cls._flatten_rich_inline_text(children) + for key in ("text", "children"): + if value.get(key) is not None: + return cls._flatten_rich_inline_text(value[key]) return "" @classmethod @@ -7910,22 +5855,15 @@ class TelegramAdapter(BasePlatformAdapter): for block in blocks: if not isinstance(block, dict): continue - block_type = block.get("type") - if block_type == "list": + if block.get("type") == "list": for item in block.get("items", []): if not isinstance(item, dict): continue - item_text = cls._flatten_rich_blocks(item.get("blocks")) - if not item_text: - continue - label = item.get("label") - item_lines = item_text.splitlines() + item_lines = cls._flatten_rich_blocks(item.get("blocks")).splitlines() if not item_lines: continue - first_line = item_lines[0] - if label: - first_line = f"{label} {first_line}".strip() - lines.append(first_line) + label = item.get("label") + lines.append(f"{label} {item_lines[0]}".strip() if label else item_lines[0]) lines.extend(item_lines[1:]) continue text = cls._flatten_rich_inline_text(block.get("text")) @@ -7937,16 +5875,13 @@ class TelegramAdapter(BasePlatformAdapter): def _extract_rich_reply_text(cls, reply_to_message: Any) -> Optional[str]: """Return plaintext echoed by Telegram's rich_message reply payload.""" try: - api_kwargs = getattr(reply_to_message, "api_kwargs", None) - getter = getattr(api_kwargs, "get", None) + getter = getattr(getattr(reply_to_message, "api_kwargs", None), "get", None) if not callable(getter): return None - rich_message = getter("rich_message") - rich_getter = getattr(rich_message, "get", None) + rich_getter = getattr(getter("rich_message"), "get", None) if not callable(rich_getter): return None - text = cls._flatten_rich_blocks(rich_getter("blocks")).strip() - return text or None + return cls._flatten_rich_blocks(rich_getter("blocks")).strip() or None except Exception: return None @@ -7972,35 +5907,29 @@ class TelegramAdapter(BasePlatformAdapter): # [{"chat_id": ..., "topics": [...]}] and legacy {"-100...": [{"thread_id": 12}]}. group_topics_config = self.config.extra.get("group_topics", []) if isinstance(group_topics_config, dict): - group_topics_iter = [ - {"chat_id": cfg_chat_id, "topics": topics} for cfg_chat_id, topics in group_topics_config.items() - ] + group_topics_iter = [{"chat_id": cfg_chat_id, "topics": topics} for cfg_chat_id, topics in group_topics_config.items()] elif isinstance(group_topics_config, list): group_topics_iter = [entry for entry in group_topics_config if isinstance(entry, dict)] else: group_topics_iter = [] for chat_entry in group_topics_iter: - if str(chat_entry.get("chat_id", "")) == str(chat.id): - topics = chat_entry.get("topics", []) - if not isinstance(topics, list): - topics = [] - for topic in topics: - if not isinstance(topic, dict): - continue - tid = topic.get("thread_id") - if tid is not None and str(tid) == thread_id_str: - chat_topic = topic.get("name") - topic_skill = topic.get("skill") - break - break + if str(chat_entry.get("chat_id", "")) != str(chat.id): + continue + topics = chat_entry.get("topics", []) + for topic in (topics if isinstance(topics, list) else []): + if not isinstance(topic, dict): + continue + tid = topic.get("thread_id") + if tid is not None and str(tid) == thread_id_str: + chat_topic = topic.get("name") + topic_skill = topic.get("skill") + break + break return chat_topic, topic_skill def _reply_context(self, message: Message) -> tuple: - """Return ``(reply_to_id, reply_to_text)`` for the replied-to message, if any. - - Prefers Telegram's native partial quote so quoting one substring doesn't inject the - whole replied-to message; falls back to text/caption, rich echo, then the sent index. - """ + """``(reply_to_id, reply_to_text)`` for the replied-to message: Telegram's native partial quote + first, then text/caption, rich echo, then the sent index.""" if not message.reply_to_message: return None, None reply_to_id = str(message.reply_to_message.message_id) @@ -8010,7 +5939,6 @@ class TelegramAdapter(BasePlatformAdapter): return reply_to_id, quote_text reply_to_text = message.reply_to_message.text or message.reply_to_message.caption or None if not reply_to_text: - # Native rich-message echo first; local send-time index only as fallback. reply_to_text = self._extract_rich_reply_text(message.reply_to_message) if not reply_to_text: try: @@ -8021,66 +5949,36 @@ class TelegramAdapter(BasePlatformAdapter): return reply_to_id, reply_to_text def _build_message_event(self, message: Message, msg_type: MessageType, update_id: Optional[int] = None) -> MessageEvent: - """Build a MessageEvent from a Telegram message. - - ``update_id`` lets ``/restart`` record the triggering offset so the new gateway process - advances past it (otherwise it is re-delivered when PTB's shutdown ACK fails). - """ + """Build a MessageEvent from a Telegram message. ``update_id`` lets ``/restart`` record the + triggering offset so the new gateway process advances past it.""" chat = message.chat user = message.from_user - # Normalize via str() so PTB enums (ChatType.CHANNEL) and plain-string mocks both work. - telegram_chat_type = str(getattr(chat, "type", "")).split(".")[-1].lower() - chat_type = "dm" - if telegram_chat_type in {"group", "supergroup"}: - chat_type = "group" - elif telegram_chat_type == "channel": - chat_type = "channel" - - # Shared normalizer so gating and session routing agree: reply-UI anchors are dropped - # (sends against them hit 'Message thread not found'); forum General-topic messages - # normalize to the General id so replies route back there. + telegram_chat_type = self._chat_type_str(chat) # str() so PTB enums and plain-string mocks both work + chat_type = "group" if telegram_chat_type in {"group", "supergroup"} else ("channel" if telegram_chat_type == "channel" else "dm") + # Shared normalizer so gating and session routing agree (reply-UI anchors dropped, General → "1"). thread_id_str = self._effective_message_thread_id(message) chat_topic, topic_skill = self._resolve_topic_binding(message, chat_type, thread_id_str) + has_full_name = hasattr(chat, "full_name") + if user: + user_name = user.full_name + elif has_full_name and chat_type == "dm": + user_name = chat.full_name + else: + user_name = chat.title if chat_type == "channel" else None source = self.build_source( - chat_id=str(chat.id), - chat_name=chat.title or (chat.full_name if hasattr(chat, "full_name") else None), - chat_type=chat_type, + chat_id=str(chat.id), chat_name=chat.title or (chat.full_name if has_full_name else None), chat_type=chat_type, user_id=(str(user.id) if user else (str(chat.id) if chat_type in {"dm", "channel"} else None)), - user_name=( - user.full_name - if user - else ( - chat.full_name - if hasattr(chat, "full_name") and chat_type == "dm" - else (chat.title if chat_type == "channel" else None) - ) - ), - thread_id=thread_id_str, - chat_topic=chat_topic, - message_id=str(message.message_id), - is_bot=bool(getattr(user, "is_bot", False)) if user else False, - ) + user_name=user_name, thread_id=thread_id_str, chat_topic=chat_topic, message_id=str(message.message_id), + is_bot=bool(getattr(user, "is_bot", False)) if user else False) reply_to_id, reply_to_text = self._reply_context(message) - - # Per-channel/topic ephemeral prompt - from gateway.platforms.base import resolve_channel_prompt + from gateway.platforms.base import resolve_channel_prompt # per-channel/topic ephemeral prompt _chat_id_str = str(chat.id) - _channel_prompt = resolve_channel_prompt( - self.config.extra, thread_id_str or _chat_id_str, _chat_id_str if thread_id_str else None - ) return MessageEvent( - text=message.text or "", - message_type=msg_type, - source=source, - raw_message=message, - message_id=str(message.message_id), - platform_update_id=update_id, - reply_to_message_id=reply_to_id, - reply_to_text=reply_to_text, - auto_skill=topic_skill, - channel_prompt=_channel_prompt, - timestamp=message.date, - ) + text=message.text or "", message_type=msg_type, source=source, raw_message=message, + message_id=str(message.message_id), platform_update_id=update_id, + reply_to_message_id=reply_to_id, reply_to_text=reply_to_text, auto_skill=topic_skill, + channel_prompt=resolve_channel_prompt(self.config.extra, thread_id_str or _chat_id_str, _chat_id_str if thread_id_str else None), + timestamp=message.date) # -- Message reactions (processing lifecycle) -- @@ -8088,31 +5986,23 @@ class TelegramAdapter(BasePlatformAdapter): """Reactions enabled via TELEGRAM_REACTIONS env/config.""" return os.getenv("TELEGRAM_REACTIONS", "false").lower() not in {"false", "0", "no"} - async def _set_reaction(self, chat_id: str, message_id: str, emoji: str) -> bool: - """Set a single emoji reaction on a Telegram message.""" + async def _set_reaction(self, chat_id: str, message_id: str, emoji: Optional[str]) -> bool: + """Set a single emoji reaction (``None`` clears all bot-set reactions, the documented Bot API way).""" if not self._bot: return False try: - await self._bot.set_message_reaction( - chat_id=normalize_telegram_chat_id(chat_id), message_id=int(message_id), reaction=emoji - ) + await self._bot.set_message_reaction(chat_id=normalize_telegram_chat_id(chat_id), message_id=int(message_id), reaction=emoji) return True except Exception as e: - logger.debug("[%s] set_message_reaction failed (%s): %s", self.name, emoji, _redact_telegram_error_text(e)) + if emoji is None: + logger.debug("[%s] clear reactions failed: %s", self.name, _redact_telegram_error_text(e)) + else: + logger.debug("[%s] set_message_reaction failed (%s): %s", self.name, emoji, _redact_telegram_error_text(e)) return False async def _clear_reactions(self, chat_id: str, message_id: str) -> bool: - """Clear all bot-set reactions (``reaction=None`` is the documented Bot API way).""" - if not self._bot: - return False - try: - await self._bot.set_message_reaction( - chat_id=normalize_telegram_chat_id(chat_id), message_id=int(message_id), reaction=None - ) - return True - except Exception as e: - logger.debug("[%s] clear reactions failed: %s", self.name, _redact_telegram_error_text(e)) - return False + """Clear all bot-set reactions.""" + return await self._set_reaction(chat_id, message_id, None) async def on_processing_start(self, event: MessageEvent) -> None: """Add an in-progress reaction when message processing begins.""" @@ -8124,11 +6014,8 @@ class TelegramAdapter(BasePlatformAdapter): await self._set_reaction(chat_id, message_id, "\U0001f440") async def on_processing_complete(self, event: MessageEvent, outcome: ProcessingOutcome) -> None: - """Swap the in-progress reaction for a final success/failure reaction. - - Telegram's set_message_reaction replaces (not adds), so no remove step. CANCELLED - explicitly clears the 👀 so it doesn't linger when the cancel was the last activity. - """ + """Swap the in-progress reaction for a final success/failure reaction (set_message_reaction + replaces, not adds); CANCELLED explicitly clears the 👀.""" if not self._reactions_enabled(): return chat_id = getattr(event.source, "chat_id", None) @@ -8141,21 +6028,18 @@ class TelegramAdapter(BasePlatformAdapter): await self._set_reaction(chat_id, message_id, "\U0001f44d" if outcome == ProcessingOutcome.SUCCESS else "\U0001f44e") -# -- Plugin registration glue: register(ctx) plus the hook implementations (adapter factory, -# YAML→env/extra config, setup wizard, standalone sender) that replace the former -# per-platform core touchpoints in gateway/, hermes_cli/ and tools/send_message_tool.py. +# -- Plugin registration glue: register(ctx) plus the hook implementations (adapter factory, YAML→env/extra +# config, setup wizard, standalone sender). def _resolve_notifications_mode() -> str: - """Notification mode (all/important) from env, else config.yaml - display.platforms.telegram.notifications, default 'important'.""" + """Notification mode (all/important) from env, else config.yaml display.platforms.telegram.notifications.""" mode = os.getenv("HERMES_TELEGRAM_NOTIFICATIONS", "") if not mode: try: from gateway.config import load_gateway_config from gateway.run import cfg_get - _gw_cfg = load_gateway_config() - _raw = cfg_get(_gw_cfg, "display", "platforms", "telegram", "notifications") + _raw = cfg_get(load_gateway_config(), "display", "platforms", "telegram", "notifications") if _raw not in {None, ""}: mode = str(_raw).strip().lower() except Exception: @@ -8178,11 +6062,8 @@ def _build_adapter(config): def _is_connected(config) -> bool: - """Connected when a bot token is configured (env or PlatformConfig.token). - - check_telegram_requirements() only checks the SDK is importable; without this gate the - plugin-enable pass would enable Telegram on any machine with the SDK installed. - """ + """Connected when a bot token is configured (env or PlatformConfig.token); the SDK being importable is + not enough or the plugin-enable pass would enable Telegram on any machine with it installed.""" token = getattr(config, "token", None) if not token: import hermes_cli.gateway as gateway_mod @@ -8191,19 +6072,17 @@ def _is_connected(config) -> bool: async def _standalone_send(pconfig, chat_id, message, *, thread_id=None, media_files=None, force_document=False): - """Out-of-process delivery (standalone_sender_fn contract) so deliver=telegram cron jobs - succeed without the gateway; delegates to the REST ``_send_telegram`` sender.""" + """Out-of-process delivery (standalone_sender_fn) so deliver=telegram cron jobs succeed without the + gateway; delegates to the REST ``_send_telegram`` sender.""" token = getattr(pconfig, "token", None) if not token: - # Profile-scoped read: don't borrow another profile's env-bridged token under multiplex. - from agent.secret_scope import get_secret + from agent.secret_scope import get_secret # profile-scoped: never borrow another profile's token token = get_secret("TELEGRAM_BOT_TOKEN", "") or "" disable_link_previews = bool(getattr(pconfig, "extra", {}) and pconfig.extra.get("disable_link_previews")) from tools.send_message_tool import _send_telegram return await _send_telegram( token, chat_id, message, media_files=media_files, thread_id=thread_id, - disable_link_previews=disable_link_previews, force_document=force_document, - ) + disable_link_previews=disable_link_previews, force_document=force_document) def interactive_setup() -> None: @@ -8213,14 +6092,12 @@ def interactive_setup() -> None: def _apply_yaml_config(yaml_cfg: dict, telegram_cfg: dict) -> dict | None: - """Translate config.yaml telegram: keys into TELEGRAM_* env vars and PlatformConfig.extra. - - Env vars take precedence over YAML. Returns extras to merge into PlatformConfig.extra, or None. - """ + """Translate config.yaml telegram: keys into TELEGRAM_* env vars and PlatformConfig.extra. Env vars + take precedence over YAML. Returns extras to merge into PlatformConfig.extra, or None.""" import json as _json extras: dict = {} - # Under multiplex a secondary profile's authorization gates must NOT hit the process-global - # env (first-writer-wins would pin them for every profile); they flow via extra/secret scope. + # Under multiplex a secondary profile's authorization gates must NOT hit the process-global env + # (first-writer-wins would pin them for every profile); they flow via extra/secret scope. try: from agent.secret_scope import current_secret_scope, is_multiplex_active _skip_env_bridge = bool(is_multiplex_active() and current_secret_scope() is not None) @@ -8248,23 +6125,22 @@ def _apply_yaml_config(yaml_cfg: dict, telegram_cfg: dict) -> dict | None: if "disable_topic_auto_rename" in telegram_cfg: extras.setdefault("disable_topic_auto_rename", telegram_cfg["disable_topic_auto_rename"]) - _effective_rm = telegram_cfg.get("require_mention", yaml_cfg.get("require_mention")) if _effective_rm is not None: _set_env("TELEGRAM_REQUIRE_MENTION", str(_effective_rm).lower()) if "mention_patterns" in telegram_cfg: _set_env("TELEGRAM_MENTION_PATTERNS", _json.dumps(telegram_cfg["mention_patterns"])) - _bridge_lower("exclusive_bot_mentions", "TELEGRAM_EXCLUSIVE_BOT_MENTIONS") - _bridge_lower("allow_bots", "TELEGRAM_ALLOW_BOTS") - _bridge_lower("guest_mode", "TELEGRAM_GUEST_MODE") - _bridge_lower("observe_unmentioned_group_messages", "TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES") - # No extras seed for allowed_chats / allowed_topics / group_allowed_chats: the shared-key - # loop already bridges them with their original type and this merge would clobber it. - _bridge_gate("free_response_chats", "TELEGRAM_FREE_RESPONSE_CHATS", telegram_cfg.get("free_response_chats"), seed_extra=True) - _bridge_gate("free_response_topics", "TELEGRAM_FREE_RESPONSE_TOPICS", telegram_cfg.get("free_response_topics")) - _bridge_gate("allowed_chats", "TELEGRAM_ALLOWED_CHATS", telegram_cfg.get("allowed_chats")) - _bridge_gate("allowed_topics", "TELEGRAM_ALLOWED_TOPICS", telegram_cfg.get("allowed_topics")) - _bridge_gate("ignored_threads", "TELEGRAM_IGNORED_THREADS", telegram_cfg.get("ignored_threads"), seed_extra=True) + for key, env in ( + ("exclusive_bot_mentions", "TELEGRAM_EXCLUSIVE_BOT_MENTIONS"), ("allow_bots", "TELEGRAM_ALLOW_BOTS"), + ("guest_mode", "TELEGRAM_GUEST_MODE", ), ("observe_unmentioned_group_messages", "TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES")): + _bridge_lower(key, env) + # No extras seed for allowed_chats / allowed_topics / group_allowed_chats: the shared-key loop already + # bridges them with their original type and this merge would clobber it. + for key, env, seed in ( + ("free_response_chats", "TELEGRAM_FREE_RESPONSE_CHATS", True), ("free_response_topics", "TELEGRAM_FREE_RESPONSE_TOPICS", False), + ("allowed_chats", "TELEGRAM_ALLOWED_CHATS", False), ("allowed_topics", "TELEGRAM_ALLOWED_TOPICS", False), + ("ignored_threads", "TELEGRAM_IGNORED_THREADS", True)): + _bridge_gate(key, env, telegram_cfg.get(key), seed_extra=seed) _bridge_lower("reactions", "TELEGRAM_REACTIONS") if "proxy_url" in telegram_cfg: _set_env("TELEGRAM_PROXY", str(telegram_cfg["proxy_url"]).strip()) @@ -8274,25 +6150,19 @@ def _apply_yaml_config(yaml_cfg: dict, telegram_cfg: dict) -> dict | None: _set_env("TELEGRAM_REPLY_TO_MODE", "off" if _telegram_rtm is False else str(_telegram_rtm).lower()) _bridge_gate("allow_from", "TELEGRAM_ALLOWED_USERS", telegram_cfg.get("allow_from")) _bridge_gate( - "group_allow_from", "TELEGRAM_GROUP_ALLOWED_USERS", - telegram_cfg.get("group_allow_from") or _telegram_extra.get("group_allow_from"), - ) + "group_allow_from", "TELEGRAM_GROUP_ALLOWED_USERS", telegram_cfg.get("group_allow_from") or _telegram_extra.get("group_allow_from")) _bridge_gate( "group_allowed_chats", "TELEGRAM_GROUP_ALLOWED_CHATS", - telegram_cfg.get("group_allowed_chats") or _telegram_extra.get("group_allowed_chats"), - ) + telegram_cfg.get("group_allowed_chats") or _telegram_extra.get("group_allowed_chats")) for _key in ("guest_mode", "disable_link_previews", "observe_unmentioned_group_messages", "free_response_topics"): if _key in telegram_cfg: extras.setdefault(_key, telegram_cfg[_key]) - # Pass through telegram-specific extra keys but EXCLUDE generic shared-config keys: - # _merge_platform_map already applied top-level-over-nested precedence, and our return is - # merged via dict.update(), so re-emitting them would undo it. + # Pass through telegram-specific extra keys but EXCLUDE generic shared-config keys: _merge_platform_map + # already applied top-level-over-nested precedence and re-emitting them via dict.update() would undo it. _GENERIC_MERGE_KEYS = { - "reply_prefix", "reply_in_thread", "reply_to_mode", - "unauthorized_dm_behavior", "notice_delivery", "require_mention", - "channel_skill_bindings", "channel_prompts", "gateway_restart_notification", - "allow_from", "allow_admin_from", "dm_policy", "group_policy", - } + "reply_prefix", "reply_in_thread", "reply_to_mode", "unauthorized_dm_behavior", "notice_delivery", + "require_mention", "channel_skill_bindings", "channel_prompts", "gateway_restart_notification", "allow_from", + "allow_admin_from", "dm_policy", "group_policy"} for _k, _v in _telegram_extra.items(): if _k not in _GENERIC_MERGE_KEYS: extras.setdefault(_k, _v) @@ -8302,22 +6172,9 @@ def _apply_yaml_config(yaml_cfg: dict, telegram_cfg: dict) -> dict | None: def register(ctx) -> None: """Plugin entry point — called by the Hermes plugin system.""" ctx.register_platform( - name="telegram", - label="Telegram", - adapter_factory=_build_adapter, - check_fn=telegram_deps_present, - ensure_deps_fn=check_telegram_requirements, - is_connected=_is_connected, - required_env=["TELEGRAM_BOT_TOKEN"], - install_hint="Run `hermes setup` to install Telegram support.", - setup_fn=interactive_setup, - apply_yaml_config_fn=_apply_yaml_config, - allowed_users_env="TELEGRAM_ALLOWED_USERS", - allow_all_env="TELEGRAM_ALLOW_ALL_USERS", - cron_deliver_env_var="TELEGRAM_HOME_CHANNEL", - standalone_sender_fn=_standalone_send, - max_message_length=4096, - emoji="✈️", - allow_update_command=True, - ) + name="telegram", label="Telegram", adapter_factory=_build_adapter, check_fn=telegram_deps_present, + ensure_deps_fn=check_telegram_requirements, is_connected=_is_connected, required_env=["TELEGRAM_BOT_TOKEN"], + install_hint="Run `hermes setup` to install Telegram support.", setup_fn=interactive_setup, apply_yaml_config_fn=_apply_yaml_config, + allowed_users_env="TELEGRAM_ALLOWED_USERS", allow_all_env="TELEGRAM_ALLOW_ALL_USERS", cron_deliver_env_var="TELEGRAM_HOME_CHANNEL", + standalone_sender_fn=_standalone_send, max_message_length=4096, emoji="✈️", allow_update_command=True) diff --git a/plugins/platforms/telegram/inline_picker.py b/plugins/platforms/telegram/inline_picker.py index 0c04620ec7..fa3267ac54 100644 --- a/plugins/platforms/telegram/inline_picker.py +++ b/plugins/platforms/telegram/inline_picker.py @@ -1,14 +1,10 @@ #!/usr/bin/env python3 """Telegram inline command picker — searchable access to EVERY command/skill. -The BotCommand menu is capped (100/scope, Hermes uses 60), so inline mode -(``@yourbot ``, live per keystroke, 50 per page) exposes the rest. Tapping a -result sends ``/cmd args`` as the user; it starts with ``/`` so it arrives even under -privacy mode and dispatches through the normal command path. - -PTB-object-free on purpose: plain dicts keep catalog/filter/pagination unit-testable -without python-telegram-bot; the adapter converts to ``InlineQueryResultArticle``. -Inline mode must be enabled via BotFather ``/setinline``; until then the handler is inert. +The BotCommand menu is capped (100/scope, Hermes uses 60), so inline mode (``@yourbot ``, 50 per +page) exposes the rest; tapping a result sends ``/cmd args`` as the user through the normal command path. +PTB-object-free on purpose: plain dicts keep catalog/filter/pagination unit-testable; the adapter converts +to ``InlineQueryResultArticle``. Inert until inline mode is enabled via BotFather ``/setinline``. """ from __future__ import annotations @@ -26,49 +22,34 @@ CACHE_TIME_SECONDS = 10 def collect_inline_catalog() -> List[Dict[str, str]]: - """Every dispatchable command as ``{name, description}``, first occurrence wins. - - Core gateway commands first (menu gating), then plugin + skill commands via the - shared collector with ``max_slots=None`` — the inline picker has no cap. - """ + """Every dispatchable command as ``{name, description}``, first occurrence wins: core gateway commands + first (menu gating), then plugin + skill commands with ``max_slots=None`` (no cap).""" catalog: List[Dict[str, str]] = [] seen: set[str] = set() + def _add(name, desc): + if name and name not in seen: + seen.add(name) + catalog.append({"name": name, "description": desc or ""}) + try: - from hermes_cli.commands import ( - _collect_gateway_skill_entries, - _sanitize_telegram_name, - telegram_bot_commands, - ) + from hermes_cli.commands import _collect_gateway_skill_entries, _sanitize_telegram_name, telegram_bot_commands except Exception: # pragma: no cover - defensive logger.debug("inline picker: commands registry unavailable", exc_info=True) return catalog - try: for name, desc in telegram_bot_commands(): - if name and name not in seen: - seen.add(name) - catalog.append({"name": name, "description": desc or ""}) + _add(name, desc) except Exception: logger.debug("inline picker: core command collection failed", exc_info=True) - try: entries, _hidden = _collect_gateway_skill_entries( - platform="telegram", - max_slots=None, # inline mode has no cap — collect everything - reserved_names=set(seen), - desc_limit=100, - sanitize_name=_sanitize_telegram_name, + platform="telegram", max_slots=None, reserved_names=set(seen), desc_limit=100, sanitize_name=_sanitize_telegram_name, ) - for entry in entries: - # Entry shape is (name, desc, cmd_key[, raw_name]) — tolerate both. - name, desc = entry[0], entry[1] - if name and name not in seen: - seen.add(name) - catalog.append({"name": name, "description": desc or ""}) + for entry in entries: # shape is (name, desc, cmd_key[, raw_name]) + _add(entry[0], entry[1]) except Exception: logger.debug("inline picker: skill/plugin collection failed", exc_info=True) - return catalog @@ -78,12 +59,10 @@ def filter_catalog(catalog: List[Dict[str, str]], term: str) -> List[Dict[str, s term = (term or "").strip().lower().lstrip("/") if not term: return list(catalog) - prefix: List[Dict[str, str]] = [] name_sub: List[Dict[str, str]] = [] desc_sub: List[Dict[str, str]] = [] - # Treat hyphens/underscores as equivalent, mirroring command dispatch. - norm_term = term.replace("-", "_") + norm_term = term.replace("-", "_") # hyphens/underscores equivalent, mirroring command dispatch for item in catalog: norm_name = item["name"].lower().replace("-", "_") if norm_name.startswith(norm_term): @@ -95,34 +74,21 @@ def filter_catalog(catalog: List[Dict[str, str]], term: str) -> List[Dict[str, s return prefix + name_sub + desc_sub -def build_inline_results( - query: str, offset: str = "", page_size: int = PAGE_SIZE, -) -> Tuple[List[Dict[str, Any]], str]: - """One page of inline results for *query*. - - First token filters the catalog; the remainder becomes the command argument - (``@bot plan migrate auth`` → tapping ``/plan`` sends ``/plan migrate auth``). - Returns ``(results, next_offset)``; ``next_offset == ""`` means last page. - """ - query = (query or "").strip() - parts = query.split(None, 1) +def build_inline_results(query: str, offset: str = "", page_size: int = PAGE_SIZE) -> Tuple[List[Dict[str, Any]], str]: + """One page of inline results for *query*: first token filters the catalog; the remainder becomes the + command argument (``@bot plan migrate auth`` → ``/plan migrate auth``). ``next_offset == ""`` = last page.""" + parts = (query or "").strip().split(None, 1) term = parts[0] if parts else "" args = parts[1].strip() if len(parts) > 1 else "" - matches = filter_catalog(collect_inline_catalog(), term) - try: start = int(offset) if offset else 0 except (TypeError, ValueError): start = 0 - page = matches[start:start + page_size] next_offset = str(start + page_size) if len(matches) > start + page_size else "" - results: List[Dict[str, Any]] = [] - for item in page: - message_text = f"/{item['name']}" - if args: - message_text += f" {args}" + for item in matches[start:start + page_size]: + message_text = f"/{item['name']}" + (f" {args}" if args else "") results.append({ "id": f"{start}:{item['name']}"[:64], # offset-scoped: unique across pages "title": f"/{item['name']}", diff --git a/plugins/platforms/telegram/telegram_ids.py b/plugins/platforms/telegram/telegram_ids.py index 458d561186..90f4a715e6 100644 --- a/plugins/platforms/telegram/telegram_ids.py +++ b/plugins/platforms/telegram/telegram_ids.py @@ -1,33 +1,18 @@ -"""Helpers for Telegram Bot API chat identifiers. - -Telegram's Bot API accepts a ``chat_id`` in two forms: a numeric ID (an int, -e.g. ``123456789`` for a DM or ``-1001234567890`` for a channel/supergroup) or -an ``@username`` string for public channels and groups. Hermes historically -coerced every ``chat_id`` with ``int()``, which crashes on the username form -(``ValueError: invalid literal for int()``). Normalizing here lets numeric IDs -pass through as ints while usernames pass through unchanged — both are valid -values for the Bot API. -""" +"""Helpers for Telegram Bot API chat identifiers: a ``chat_id`` is a numeric ID (int) or an ``@username`` +string for public channels/groups; a bare ``int(chat_id)`` crashes on the username form.""" from __future__ import annotations import re from typing import Any, Union -# Telegram usernames are 5-32 chars: letters, digits, underscores, with a -# leading "@". (Telegram also permits 4-char usernames for some legacy/official -# accounts, but the 5-32 public rule is the safe lower bound for routing.) +# Usernames are 5-32 chars (letters, digits, underscores) with a leading "@"; 4-char legacy handles are tolerated. _TELEGRAM_USERNAME_RE = re.compile(r"@[A-Za-z0-9_]{4,32}") def normalize_telegram_chat_id(chat_id: Any) -> Union[int, str]: - """Return a Bot API-compatible chat_id. - - Numeric values (incl. negative channel IDs) are returned as ``int``; any - non-numeric value (e.g. an ``@username``) is returned as a stripped string. - Telegram's Bot API accepts both, so this never raises on a username the way - a bare ``int(chat_id)`` would. - """ + """Bot API-compatible chat_id: numeric values (incl. negative channel IDs) as ``int``, anything + else (e.g. ``@username``) as a stripped string; never raises.""" chat_id_str = str(chat_id).strip() try: return int(chat_id_str) diff --git a/plugins/platforms/telegram/telegram_network.py b/plugins/platforms/telegram/telegram_network.py index 4a91c95c32..91a104de6d 100644 --- a/plugins/platforms/telegram/telegram_network.py +++ b/plugins/platforms/telegram/telegram_network.py @@ -15,39 +15,32 @@ logger = logging.getLogger(__name__) _TELEGRAM_API_HOST = "api.telegram.org" -# TCP keepalive so a half-open/CLOSE-WAIT long-poll errors out instead of blocking -# getUpdates forever (Windows leaves SO_KEEPALIVE off by default). Idle/interval knobs -# are best-effort — not every Python/OS combo exposes TCP_KEEPIDLE / TCP_KEEPALIVE. +# TCP keepalive so a half-open/CLOSE-WAIT long-poll errors out instead of blocking getUpdates forever +# (Windows leaves SO_KEEPALIVE off). Idle/interval knobs are best-effort per Python/OS combo. _TCP_KEEPALIVE_IDLE_S = 30 _TCP_KEEPALIVE_INTERVAL_S = 10 _TCP_KEEPALIVE_COUNT = 3 def tcp_keepalive_socket_options() -> list[tuple[int, int, int]]: - """``setsockopt`` tuples for httpx ``socket_options``: always SO_KEEPALIVE, plus - idle/interval/count when the interpreter exposes those option names.""" + """``setsockopt`` tuples for httpx ``socket_options``: always SO_KEEPALIVE, plus idle/interval/count + when the interpreter exposes those option names.""" options: list[tuple[int, int, int]] = [(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)] idle = getattr(socket, "TCP_KEEPIDLE", None) or getattr(socket, "TCP_KEEPALIVE", None) - if idle is not None: - options.append((socket.IPPROTO_TCP, idle, _TCP_KEEPALIVE_IDLE_S)) - interval = getattr(socket, "TCP_KEEPINTVL", None) - if interval is not None: - options.append((socket.IPPROTO_TCP, interval, _TCP_KEEPALIVE_INTERVAL_S)) - count = getattr(socket, "TCP_KEEPCNT", None) - if count is not None: - options.append((socket.IPPROTO_TCP, count, _TCP_KEEPALIVE_COUNT)) + for opt, value in ((idle, _TCP_KEEPALIVE_IDLE_S), (getattr(socket, "TCP_KEEPINTVL", None), _TCP_KEEPALIVE_INTERVAL_S), + (getattr(socket, "TCP_KEEPCNT", None), _TCP_KEEPALIVE_COUNT)): + if opt is not None: + options.append((socket.IPPROTO_TCP, opt, value)) return options -# DNS-over-HTTPS providers: discover Telegram API IPs that may differ from the -# (possibly unreachable) one the local resolver returns. Bounded so connect() isn't delayed. +# DNS-over-HTTPS providers: discover Telegram API IPs the (possibly unreachable) local resolver may not +# return. Bounded so connect() isn't delayed. _DOH_TIMEOUT = 4.0 _DOH_PROVIDERS: list[dict] = [ {"url": "https://dns.google/resolve", "params": {"name": _TELEGRAM_API_HOST, "type": "A"}, "headers": {}}, { - "url": "https://cloudflare-dns.com/dns-query", - "params": {"name": _TELEGRAM_API_HOST, "type": "A"}, - "headers": {"Accept": "application/dns-json"}, - }, + "url": "https://cloudflare-dns.com/dns-query", "params": {"name": _TELEGRAM_API_HOST, "type": "A"}, + "headers": {"Accept": "application/dns-json"}}, ] # Last-resort IPv4 Bot API endpoints (149.154.160.0/20). Used when DoH is blocked AND as # first-try connect targets so a blackholed IPv6 AAAA for the hostname can't pin initialize(). @@ -61,15 +54,10 @@ def _resolve_proxy_url(target_hosts=None) -> str | None: class TelegramFallbackTransport(httpx.AsyncBaseTransport): - """Reach the Bot API via known IPv4 literals first, dual-stack hostname last. + """Reach the Bot API via known IPv4 literals first, dual-stack hostname last. Host + SNI stay on + api.telegram.org (like ``curl --resolve``) so a blackholed IPv6 AAAA can't pin initialize().""" - Logically requests still target https://api.telegram.org (Host + SNI stay on the - hostname) — like ``curl --resolve api.telegram.org:443:`` — so a blackholed - IPv6 AAAA can't pin initialize(); the hostname remains for IPv6-only networks. - """ - - # Bound every pool: httpx's 100-connection default × (wedged endpoint + seed IPs) - # can outgrow the process fd limit on its own. + # Bound every pool: httpx's 100-connection default × (wedged endpoint + seed IPs) can outgrow the fd limit. _POOL_LIMITS = httpx.Limits(max_connections=8, max_keepalive_connections=4) def __init__(self, fallback_ips: Iterable[str], **transport_kwargs): @@ -99,8 +87,7 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): return transport async def _reset_primary(self, transport: httpx.AsyncHTTPTransport) -> None: - # Retryable primary failures leave half-closed sockets in the pool; replace the - # generation and close the old one before trying fallback. + # Retryable primary failures leave half-closed sockets in the pool; replace the generation first. async with self._primary_lock: if self._primary_closed or transport is not self._primary: return @@ -111,8 +98,8 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): logger.debug("[Telegram] Error closing primary transport: %s", exc) async def _reset_fallback(self, ip: str) -> None: - """Discard a failed fallback pool: a peer-closed connect leaves a CLOSE_WAIT socket - in it, and keeping the poisoned pool leaks one fd per retry until the process limit.""" + """Discard a failed fallback pool: a peer-closed connect leaves a CLOSE_WAIT socket in it, and the + poisoned pool would leak one fd per retry.""" async with self._fallback_lock: transport = self._fallbacks.pop(ip, None) if transport is None: @@ -123,18 +110,12 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): logger.debug("[Telegram] Error closing fallback transport %s: %s", ip, exc) def _attempt_order(self) -> list[Optional[str]]: - """Sticky path first, then IPv4 literals, dual-stack hostname last. - - A blackholed IPv6 path never errors — Happy Eyeballs waits on AAAA until the OS - TCP timeout and can pin the loop so the thread deadline never fires. - """ + """Sticky path first, then IPv4 literals, dual-stack hostname last (a blackholed IPv6 path never + errors — Happy Eyeballs waits on AAAA until the OS TCP timeout and can pin the loop).""" order: list[Optional[str]] = [] if self._sticky_ip is not _UNSET: - sticky = self._sticky_ip - order.append(sticky if sticky is None else str(sticky)) - for ip in self._fallback_ips: - if ip not in order: - order.append(ip) + order.append(None if self._sticky_ip is None else str(self._sticky_ip)) + order.extend(ip for ip in self._fallback_ips if ip not in order) if None not in order: order.append(None) return order @@ -142,11 +123,8 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): async def handle_async_request(self, request: httpx.Request) -> httpx.Response: if request.url.host != _TELEGRAM_API_HOST or not self._fallback_ips: return await self._primary.handle_async_request(request) - - attempt_order = self._attempt_order() - last_error: Exception | None = None - for ip in attempt_order: + for ip in self._attempt_order(): candidate = request if ip is None else _rewrite_request_for_ip(request, ip) transport = self._primary if ip is None else await self._get_fallback(ip) try: @@ -157,10 +135,7 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): self._sticky_ip = ip if ip is not None: log = logger.warning if last_error is not None else logger.info - log( - "[Telegram] Using sticky IPv4 Telegram API path %s " - "(dual-stack hostname tried last — #87015)", ip, - ) + log("[Telegram] Using sticky IPv4 Telegram API path %s (dual-stack hostname tried last — #87015)", ip) return response except Exception as exc: last_error = exc @@ -171,10 +146,8 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): if self._sticky_ip is not _UNSET and self._sticky_ip == ip: self._sticky_ip = _UNSET logger.warning( - "[Telegram] Sticky Telegram path %s failed; " - "re-walking IPv4 literals before the hostname", - ip if ip is not None else "api.telegram.org", - ) + "[Telegram] Sticky Telegram path %s failed; re-walking IPv4 literals before the hostname", + ip if ip is not None else "api.telegram.org") if ip is None: await self._reset_primary(transport) logger.warning("[Telegram] Dual-stack api.telegram.org path failed (%s)", exc) @@ -182,7 +155,6 @@ class TelegramFallbackTransport(httpx.AsyncBaseTransport): logger.warning("[Telegram] IPv4 Telegram API IP %s failed: %s", ip, exc) await self._reset_fallback(ip) continue - if last_error is None: raise RuntimeError("All Telegram fallback IPs exhausted but no error was recorded") raise last_error @@ -212,19 +184,15 @@ def _normalize_fallback_ips(values: Iterable[str]) -> list[str]: continue if addr.version != 4: logger.warning("Ignoring non-IPv4 Telegram fallback IP: %s", raw) - continue - if addr.is_private or addr.is_loopback or addr.is_link_local or addr.is_unspecified: + elif addr.is_private or addr.is_loopback or addr.is_link_local or addr.is_unspecified: logger.warning("Ignoring private/internal Telegram fallback IP: %s", raw) - continue - normalized.append(str(addr)) + else: + normalized.append(str(addr)) return normalized def parse_fallback_ip_env(value: str | None) -> list[str]: - if not value: - return [] - parts = [part.strip() for part in value.split(",")] - return _normalize_fallback_ips(parts) + return _normalize_fallback_ips(part.strip() for part in value.split(",")) if value else [] def _resolve_system_dns() -> set[str]: @@ -249,9 +217,9 @@ async def _query_doh_provider(client: httpx.AsyncClient, provider: dict) -> list raw = answer.get("data", "").strip() try: ipaddress.ip_address(raw) - ips.append(raw) except ValueError: continue + ips.append(raw) return ips except Exception as exc: logger.debug("DoH query to %s failed: %s", provider["url"], exc) @@ -259,19 +227,13 @@ async def _query_doh_provider(client: httpx.AsyncClient, provider: dict) -> list async def discover_fallback_ips() -> list[str]: - """Resolve api.telegram.org via Google + Cloudflare DoH; unique A records, in order. - - IPs matching the system resolver are deliberately KEPT (often the most reliable - path; a transient primary failure should retry it via IP-rewrite before the seed - list). Falls back to ``SEED_FALLBACK_IPS`` only when DoH yields nothing usable. - """ + """Resolve api.telegram.org via Google + Cloudflare DoH; unique A records, in order. IPs matching the + system resolver are deliberately KEPT (often the most reliable path). Falls back to + ``SEED_FALLBACK_IPS`` only when DoH yields nothing usable.""" async with httpx.AsyncClient(timeout=httpx.Timeout(_DOH_TIMEOUT)) as client: - doh_tasks = [_query_doh_provider(client, p) for p in _DOH_PROVIDERS] system_dns_task = asyncio.ensure_future(asyncio.to_thread(_resolve_system_dns)) - results = await asyncio.gather(*doh_tasks, return_exceptions=True) - - # The getaddrinfo leg has no timeout of its own (a wedged resolver can sit for - # minutes) and only feeds the log line below — bound it, never gate discovery on it. + results = await asyncio.gather(*[_query_doh_provider(client, p) for p in _DOH_PROVIDERS], return_exceptions=True) + # The getaddrinfo leg has no timeout of its own and only feeds the log line below — bound it. system_ips: set[str] = set() try: system_result = await asyncio.wait_for(system_dns_task, timeout=_DOH_TIMEOUT) @@ -279,21 +241,14 @@ async def discover_fallback_ips() -> list[str]: system_ips = system_result except Exception: logger.debug("System-DNS resolution for %s did not complete in time", _TELEGRAM_API_HOST) - - doh_ips: list[str] = [] - for r in results: - if isinstance(r, list): - doh_ips.extend(r) + doh_ips = [ip for r in results if isinstance(r, list) for ip in r] validated = _normalize_fallback_ips(list(dict.fromkeys(doh_ips))) # dedupe, keep order if validated: logger.debug("Discovered Telegram fallback IPs via DoH: %s", ", ".join(validated)) return validated - logger.info( "DoH discovery yielded no usable IPs (system DNS: %s); using seed fallback IPs %s", - ", ".join(system_ips) or "unknown", - ", ".join(SEED_FALLBACK_IPS), - ) + ", ".join(system_ips) or "unknown", ", ".join(SEED_FALLBACK_IPS)) return list(SEED_FALLBACK_IPS) @@ -304,9 +259,7 @@ def _rewrite_request_for_ip(request: httpx.Request, ip: str) -> httpx.Request: headers["host"] = original_host extensions = dict(request.extensions) extensions["sni_hostname"] = original_host - return httpx.Request( - method=request.method, url=url, headers=headers, stream=request.stream, extensions=extensions, - ) + return httpx.Request(method=request.method, url=url, headers=headers, stream=request.stream, extensions=extensions) def _is_retryable_connect_error(exc: Exception) -> bool: diff --git a/tests/gateway/test_telegram_prune_stale_topic_binding_31501.py b/tests/gateway/test_telegram_prune_stale_topic_binding_31501.py index 97fe209e48..b125eee33d 100644 --- a/tests/gateway/test_telegram_prune_stale_topic_binding_31501.py +++ b/tests/gateway/test_telegram_prune_stale_topic_binding_31501.py @@ -194,7 +194,8 @@ class TestThreadNotFoundFallbackSitesPruneBinding: def test_streaming_send_fallback_calls_prune(self): from plugins.platforms.telegram import adapter as telegram_mod - src = inspect.getsource(telegram_mod.TelegramAdapter.send) + # The per-chunk retry loop (with the fallback) lives in _send_chunk_with_retries, called by send(). + src = inspect.getsource(telegram_mod.TelegramAdapter._send_chunk_with_retries) # Locate the second-failure branch (the one that flips # ``used_thread_fallback``). It must invoke the prune # helper before flipping the flag.