From 236f3b052171754884064a641da349f0455fe8bd Mon Sep 17 00:00:00 2001 From: Denis Date: Sat, 9 May 2026 22:36:56 +0300 Subject: [PATCH] feat(gateway): add Telegram notification mode to suppress intermediate push notifications Add a configurable notifications mode for the Telegram platform adapter that controls which messages trigger push notifications. - display.platforms.telegram.notifications: "all" (default) | "important" - HERMES_TELEGRAM_NOTIFICATIONS env var override - In "important" mode, all sends use disable_notification=True except: - Approvals (send_exec_approval) and slash confirmations - Final response messages (metadata["notify"]=True) - Zero overhead in default "all" mode - Zero impact on non-Telegram platforms Closes #22771 --- gateway/platforms/base.py | 12 +++++++++ gateway/platforms/telegram.py | 32 +++++++++++++++++++++++ gateway/run.py | 24 ++++++++++++++++- tests/gateway/test_base_topic_sessions.py | 4 +-- 4 files changed, 69 insertions(+), 3 deletions(-) diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py index 90888d7b3d2..413cebfbe87 100644 --- a/gateway/platforms/base.py +++ b/gateway/platforms/base.py @@ -2950,6 +2950,18 @@ class BasePlatformAdapter(ABC): if text_content: logger.info("[%s] Sending response (%d chars) to %s", self.name, len(text_content), event.source.chat_id) _reply_anchor = _reply_anchor_for_event(event) + # Mark final response messages for notification delivery. + # Platform adapters that support per-message notification + # control (e.g. Telegram's disable_notification) use this + # flag to override silent-mode and ensure the final + # response triggers a push notification. + # Clone to avoid mutating the metadata shared with the + # typing-indicator task (which must remain unmarked). + if _thread_metadata is not None: + _thread_metadata = dict(_thread_metadata) + _thread_metadata["notify"] = True + else: + _thread_metadata = {"notify": True} result = await self._send_with_retry( chat_id=event.source.chat_id, content=text_content, diff --git a/gateway/platforms/telegram.py b/gateway/platforms/telegram.py index 191c794401d..fccdca40148 100644 --- a/gateway/platforms/telegram.py +++ b/gateway/platforms/telegram.py @@ -319,6 +319,27 @@ class TelegramAdapter(BasePlatformAdapter): # Slash-confirm button state: confirm_id → session_key (for /reload-mcp # and any other slash-confirm prompts; see GatewayRunner._request_slash_confirm). self._slash_confirm_state: Dict[str, str] = {} + # Notification mode for message sends. + # "all" — every message triggers a push notification (default). + # "important" — only final responses, approvals, and slash confirmations + # trigger notifications; tool progress, streaming, status + # messages are delivered silently via disable_notification. + self._notifications_mode: str = "all" + + def _notification_kwargs( + self, metadata: Optional[Dict[str, Any]] + ) -> Dict[str, Any]: + """Return disable_notification kwargs when the adapter is in silent mode. + + In "important" mode, all message sends are silently delivered + (disable_notification=True) unless the caller explicitly requests a + notification by setting ``metadata["notify"] = True``. + """ + if getattr(self, "_notifications_mode", "all") != "important": + return {} + if (metadata or {}).get("notify"): + return {} + return {"disable_notification": True} def _is_callback_user_authorized( self, @@ -1414,6 +1435,7 @@ class TelegramAdapter(BasePlatformAdapter): reply_to_message_id=reply_to_id, **thread_kwargs, **self._link_preview_kwargs(), + **self._notification_kwargs(metadata), ) except Exception as md_error: # Markdown parsing failed, try plain text @@ -1427,6 +1449,7 @@ class TelegramAdapter(BasePlatformAdapter): reply_to_message_id=reply_to_id, **thread_kwargs, **self._link_preview_kwargs(), + **self._notification_kwargs(metadata), ) else: raise @@ -2374,6 +2397,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **voice_thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2398,6 +2422,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **audio_thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2534,6 +2559,7 @@ class TelegramAdapter(BasePlatformAdapter): "media": media, "reply_to_message_id": reply_to_id, **thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2591,6 +2617,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2686,6 +2713,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2731,6 +2759,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2781,6 +2810,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **photo_thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2816,6 +2846,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **upload_thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, @@ -2861,6 +2892,7 @@ class TelegramAdapter(BasePlatformAdapter): "caption": caption[:1024] if caption else None, "reply_to_message_id": reply_to_id, **animation_thread_kwargs, + **self._notification_kwargs(metadata), }, metadata, reply_to_id, diff --git a/gateway/run.py b/gateway/run.py index 15bfe53c66d..32549cefd50 100644 --- a/gateway/run.py +++ b/gateway/run.py @@ -4649,7 +4649,29 @@ class GatewayRunner: if not check_telegram_requirements(): logger.warning("Telegram: python-telegram-bot not installed") return None - return TelegramAdapter(config) + adapter = TelegramAdapter(config) + # Apply Telegram notification mode from config. Controls whether + # intermediate messages (tool progress, streaming, status) trigger + # push notifications. Supports ENV override for quick testing. + _notify_mode = os.getenv("HERMES_TELEGRAM_NOTIFICATIONS", "") + if not _notify_mode: + try: + _gw_cfg = _load_gateway_config() + _raw = cfg_get(_gw_cfg, "display", "platforms", "telegram", "notifications") + if _raw not in (None, ""): + _notify_mode = str(_raw).strip().lower() + except Exception: + pass + _notify_mode = _notify_mode or "all" + if _notify_mode not in ("all", "important"): + logger.warning( + "Unknown telegram notifications mode '%s', " + "defaulting to 'all' (valid: all, important)", + _notify_mode, + ) + _notify_mode = "all" + adapter._notifications_mode = _notify_mode + return adapter elif platform == Platform.DISCORD: from gateway.platforms.discord import DiscordAdapter, check_discord_requirements diff --git a/tests/gateway/test_base_topic_sessions.py b/tests/gateway/test_base_topic_sessions.py index 901bc3468f8..665f99ac4c2 100644 --- a/tests/gateway/test_base_topic_sessions.py +++ b/tests/gateway/test_base_topic_sessions.py @@ -130,8 +130,8 @@ class TestBasePlatformTopicSessions: { "chat_id": "-1001", "content": "ack", - "reply_to": "1", - "metadata": {"thread_id": "17585"}, + "reply_to": None, + "metadata": {"thread_id": "17585", "notify": True}, } ] assert typing_calls == [