"""Telegram group addressing helpers, kept out of the adapter facade. The identity line lives in ``channel_prompt`` and therefore in the cached-agent signature: it must be stable for the life of a session (username only — never a per-message fact). """ from typing import TYPE_CHECKING, Optional if TYPE_CHECKING: from telegram import Message from plugins.platforms.telegram.adapter import TelegramAdapter def mentions_other_participants(adapter: "TelegramAdapter", message: "Message") -> bool: """True when a ``mention``/``text_mention`` entity names someone other than this bot.""" return any( _is_other_participant(adapter, text, entity) for text, entity in _mention_entities(adapter, message) ) def _mention_entities(adapter: "TelegramAdapter", message: "Message"): """``(source_text, entity)`` for every ``mention``/``text_mention`` in the text and caption.""" for source_text, entities in adapter._entity_sources(message): for entity in entities: if adapter._entity_type(entity) in {"mention", "text_mention"}: yield source_text, entity def _is_other_participant(adapter: "TelegramAdapter", source_text: str, entity) -> bool: if adapter._entity_type(entity) == "text_mention": user = getattr(entity, "user", None) bot_id = getattr(adapter._bot, "id", None) if adapter._bot else None return user is not None and getattr(user, "id", None) != bot_id handle = (adapter._entity_span(source_text, entity) or "").strip().lstrip("@").lower() return bool(handle) and handle != adapter._current_bot_username() def starts_with_other_participant_mention(adapter: "TelegramAdapter", message: "Message") -> bool: return any( getattr(entity, "offset", None) == len(text) - len(text.lstrip()) and _is_other_participant(adapter, text, entity) for text, entity in _mention_entities(adapter, message) ) def _quoted_reply(message: "Message") -> Optional["Message"]: """The message this one replies to, or None. In a forum topic Telegram also sets ``reply_to_message`` to the topic's root on every plain message; that anchor is not a reply to a person.""" replied = getattr(message, "reply_to_message", None) if replied is None or (getattr(message, "is_topic_message", False) and getattr(replied, "message_id", None) == getattr(message, "message_thread_id", None)): return None return replied def group_reply_expected(adapter: "TelegramAdapter", message: "Message", chat_type: str) -> Optional[bool]: """Whether an admitted message needs a reply; None keeps the visible silence fallback.""" if chat_type != "group": return True if chat_type == "dm" else None text = getattr(message, "text", None) or getattr(message, "caption", None) or "" addressed_to_bot = ( text.lstrip().startswith("/") or adapter._is_reply_to_bot(message) or adapter._message_mentions_bot(message) or adapter._message_matches_mention_patterns(message) ) if addressed_to_bot: return True if not adapter._bot or not adapter._current_bot_username(): return None if (replied := _quoted_reply(message)) is not None: # Only a reply to another known member is chatter. An unknown author, or a post signed by a chat # (a linked channel's auto-forward, an anonymous admin; Telegram fills from_user with a service # account there), may still be meant for the bot. unknown = getattr(replied, "from_user", None) is None or getattr(replied, "sender_chat", None) is not None return None if unknown else False if starts_with_other_participant_mention(adapter, message): return False # Words in a voice note, video note or audio file are not in the message text, so the "?" rule cannot read them. spoken = not text and any(getattr(message, kind, None) for kind in ("voice", "video_note", "audio")) return None if "?" in text or spoken else False def group_trigger_text(adapter: "TelegramAdapter", message: "Message", text: Optional[str]) -> Optional[str]: """Strip our own handle only when we are the sole addressee. With other participants named, ``@research_bot , @ops_bot are you both listening?`` must not reach us as ``, @ops_bot …``.""" if adapter._is_group_chat(message) and mentions_other_participants(adapter, message): return text return adapter._clean_bot_trigger_text(text) def group_identity_prompt( adapter: "TelegramAdapter", message: "Message", channel_prompt: Optional[str], ) -> Optional[str]: """Session-stable identity line so the model can read retained @mentions as itself or not.""" if not adapter._is_group_chat(message) or not getattr(adapter, "_bot", None): return channel_prompt username = adapter._current_bot_username() if not username: return channel_prompt identity = ( f"Your Telegram bot username in this group: @{username}. " "Mentions of other bots are not requests for you to relay the message." ) return f"{channel_prompt}\n\n{identity}" if channel_prompt else identity