Skip to content

The agent that grows with you

fix(telegram): route a new DM topic's thread-less opening message into that topic

PRELVAS943687ef0bf4a0
diff --git a/plugins/platforms/telegram/adapter.py b/plugins/platforms/telegram/adapter.py
index d3493da1427..b25b9993335 100644
--- a/plugins/platforms/telegram/adapter.py
+++ b/plugins/platforms/telegram/adapter.py
@@ -185,6 +185,7 @@ from plugins.platforms.telegram.telegram_ids import normalize_telegram_chat_id,
from plugins.platforms.telegram.telegram_topic_transfer import TopicTransferFn, apply_root_dm_topic_transfer
from plugins.platforms.telegram.telegram_network import (
SEED_FALLBACK_IPS, TelegramFallbackTransport, discover_fallback_ips, parse_fallback_ip_env, tcp_keepalive_socket_options)
+from plugins.platforms.telegram.telegram_topic_routing import TelegramTopicRoutingMixin
from utils import env_float, env_int
_TELEGRAM_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp", ".gif"}
@@ -513,7 +514,7 @@ class _PollingStallError(RuntimeError):
"""
-class TelegramAdapter(TelegramHeldInboundMixin, BasePlatformAdapter):
+class TelegramAdapter(TelegramHeldInboundMixin, TelegramTopicRoutingMixin, BasePlatformAdapter):
"""Telegram bot adapter: users/groups, MarkdownV2 replies, forum topics, media."""
# Bound for the per-(chat_id, status_key) status-message cache; FIFO half-trim on overflow.
@@ -684,6 +685,8 @@ class TelegramAdapter(TelegramHeldInboundMixin, BasePlatformAdapter):
self._send_path_degraded: bool = False
self._general_request_drain_lock = asyncio.Lock()
self._dm_topics: dict[str, int] = {} # topic_name -> message_thread_id
+ # Topic creation whose opening message has not arrived yet (#136567); see TelegramTopicRoutingMixin.
+ self._pending_created_topics: dict[tuple[str, str], tuple[str, int, float]] = {}
self._forum_command_registered: set[int] = set() # forum chats with commands registered
self._command_menu_fingerprint: str = "" # language + menu payload last pushed via set_my_commands
self._forum_lock = asyncio.Lock()
@@ -2900,6 +2903,11 @@ class TelegramAdapter(TelegramHeldInboundMixin, BasePlatformAdapter):
app.add_handler(TelegramMessageHandler(
filters.PHOTO | filters.VIDEO | filters.AUDIO | filters.VOICE | filters.Document.ALL | filters.Sticker.ALL,
self._handle_media_message))
+ # Topic-creation service messages carry the new topic id and no text, so no other handler sees
+ # them. They are a routing signal only (never an agent turn): see _handle_forum_topic_created.
+ created_filter = getattr(getattr(filters, "StatusUpdate", None), "FORUM_TOPIC_CREATED", None)
+ if created_filter is not None:
+ app.add_handler(TelegramMessageHandler(created_filter, self._handle_forum_topic_created))
app.add_handler(CallbackQueryHandler(self._handle_callback_query))
# Inline command picker; inert until the owner enables inline mode via BotFather /setinline.
app.add_handler(InlineQueryHandler(self._handle_inline_query))
@@ -6953,13 +6961,6 @@ class TelegramAdapter(TelegramHeldInboundMixin, BasePlatformAdapter):
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:
- """Cache a thread_id -> topic_name mapping discovered from an incoming message."""
- cache_key = f"{chat_id}:{topic_name}"
- if cache_key not in self._dm_topics:
- self._dm_topics[cache_key] = int(thread_id)
- logger.info("[%s] Cached DM topic from message: %s -> thread_id=%s", self.name, cache_key, thread_id)
-
@classmethod
def _flatten_rich_inline_text(cls, value: Any) -> str:
"""Best-effort plaintext flattener for Bot API rich-message inline nodes."""
@@ -7024,13 +7025,8 @@ class TelegramAdapter(TelegramHeldInboundMixin, BasePlatformAdapter):
if topic_info:
chat_topic = topic_info.get("name")
topic_skill = topic_info.get("skill")
- # forum_topic_created service messages also reveal topic names
- if hasattr(message, "forum_topic_created") and message.forum_topic_created:
- created_name = message.forum_topic_created.name
- if created_name:
- self._cache_dm_topic_from_message(str(chat.id), thread_id_str, created_name)
- if not chat_topic:
- chat_topic = created_name
+ # The topic name a creation reveals is cached by _handle_forum_topic_created, which is the
+ # only path Telegram delivers a ``forum_topic_created`` service message through.
elif chat_type == "group" and thread_id_str:
# Forum topic skill binding via config.extra['group_topics']; accepts both
# [{"chat_id": ..., "topics": [...]}] and legacy {"-100...": [{"thread_id": 12}]}.
@@ -7098,6 +7094,10 @@ class TelegramAdapter(TelegramHeldInboundMixin, BasePlatformAdapter):
# (message_thread_id=None) normalize to the General-topic id so replies route back to General
# (#22423).
thread_id_str = self._effective_message_thread_id(message)
+ # A new private-chat topic's opening message can arrive with no thread id at all (#136567); the
+ # creation it follows is then the only source of the topic id. Adopt it before anything downstream
+ # (gating, batching, session routing, topic recovery) reads the event source.
+ thread_id_str = self._adopt_created_topic_thread(message, chat_type, thread_id_str)
chat_topic, topic_skill = self._resolve_topic_binding(message, chat_type, thread_id_str)
has_full_name = hasattr(chat, "full_name")
if user:
diff --git a/plugins/platforms/telegram/telegram_topic_routing.py b/plugins/platforms/telegram/telegram_topic_routing.py
new file mode 100644
index 00000000000..4714b73ea60
--- /dev/null
+++ b/plugins/platforms/telegram/telegram_topic_routing.py
@@ -0,0 +1,109 @@
+"""Telegram chat/topic identity and topic-creation bookkeeping (#136567).
+
+Telegram normally stamps a newly created private-chat topic's opening message with the new
+``message_thread_id``, but it sometimes delivers that opener with no thread id at all. The
+``forum_topic_created`` service message for the same event always carries the new topic id, so it is
+the only reliable source for it. Recording it here lets the opener adopt it instead of arriving
+lobby-shaped, where gateway topic recovery would pin it to the most recently bound topic.
+"""
+
+import logging
+import time
+from typing import Any, Optional
+
+logger = logging.getLogger("plugins.platforms.telegram.adapter")
+
+
+class TelegramTopicRoutingMixin:
+ """Chat/topic identity helpers and topic-creation bookkeeping for ``TelegramAdapter``."""
+
+ # How long a recorded topic creation may claim a following thread-less message.
+ _NEW_TOPIC_OPENER_TTL_SECONDS = 120.0
+
+ @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 _sender_id_str(self, message) -> str:
+ """Sender identity as a string; falls back to the chat id (equal in a private chat)."""
+ sender = getattr(message, "from_user", None)
+ sender_id = getattr(sender, "id", None)
+ return str(sender_id) if sender_id is not None else self._chat_id_str(message)
+
+ def _cache_dm_topic_from_message(self, chat_id: str, thread_id: str, topic_name: str) -> None:
+ """Cache a thread_id -> topic_name mapping discovered from an incoming message."""
+ cache_key = f"{chat_id}:{topic_name}"
+ if cache_key not in self._dm_topics:
+ self._dm_topics[cache_key] = int(thread_id)
+ logger.info("[%s] Cached DM topic from message: %s -> thread_id=%s", self.name, cache_key, thread_id)
+
+ def _pending_created_topics_store(self) -> dict:
+ """``(chat_id, sender_id) -> (thread_id, creation message id, monotonic stamp)``."""
+ pending = getattr(self, "_pending_created_topics", None)
+ if not isinstance(pending, dict):
+ pending = {}
+ self._pending_created_topics = pending
+ return pending
+
+ async def _handle_forum_topic_created(self, update: Any, context: Any) -> None:
+ """Record the topic a ``forum_topic_created`` service message just created (#136567).
+
+ The creation carries the new ``message_thread_id`` and no text, so no other handler matches it.
+ Routing signal only: it is never handed to the agent.
+ """
+ message = getattr(update, "effective_message", None)
+ created = getattr(message, "forum_topic_created", None) if message is not None else None
+ if created is None:
+ return
+ # Private chats only: in a forum group a thread-less message is General, never an opener.
+ if self._chat_type_str(getattr(message, "chat", None)) != "private":
+ return
+ thread_id = getattr(message, "message_thread_id", None)
+ message_id = getattr(message, "message_id", None)
+ if thread_id is None or not isinstance(message_id, int):
+ return
+ chat_id = self._chat_id_str(message)
+ self._pending_created_topics_store()[(chat_id, self._sender_id_str(message))] = (
+ str(thread_id), message_id, time.monotonic())
+ topic_name = getattr(created, "name", None)
+ if topic_name and isinstance(getattr(self, "_dm_topics", None), dict):
+ # The creation is the one message that reveals the new topic's name.
+ self._cache_dm_topic_from_message(chat_id, str(thread_id), str(topic_name))
+ logger.debug("[%s] Recorded new Telegram topic %s (chat=%s)", self.name, thread_id, chat_id)
+
+ def _adopt_created_topic_thread(self, message: Any, chat_type: str, thread_id: Optional[str]) -> Optional[str]:
+ """Return the just-created topic's thread id for that topic's thread-less opening message (#136567).
+
+ One-shot and adjacency-bounded: only the message immediately following the creation
+ (``message_id == creation + 1``) from the same sender, within ``_NEW_TOPIC_OPENER_TTL_SECONDS``,
+ adopts it. Everything else keeps its incoming thread id, so a later lobby message is unaffected.
+ """
+ if thread_id is not None or chat_type != "dm":
+ return thread_id
+ pending = getattr(self, "_pending_created_topics", None)
+ if not isinstance(pending, dict) or not pending:
+ return thread_id
+ key = (self._chat_id_str(message), self._sender_id_str(message))
+ record = pending.get(key)
+ if record is None:
+ return thread_id
+ created_thread_id, created_message_id, stamped_at = record
+ if (time.monotonic() - stamped_at) > self._NEW_TOPIC_OPENER_TTL_SECONDS:
+ pending.pop(key, None)
+ return thread_id
+ if getattr(message, "message_id", None) != created_message_id + 1:
+ return thread_id
+ pending.pop(key, None)
+ logger.info(
+ "[%s] New Telegram topic %s adopted by its opening message (chat=%s)",
+ self.name, created_thread_id, key[0])
+ return created_thread_id
diff --git a/tests/plugins/test_telegram_forum_topic_created_opener.py b/tests/plugins/test_telegram_forum_topic_created_opener.py
new file mode 100644
index 00000000000..f5b81bec973
--- /dev/null
+++ b/tests/plugins/test_telegram_forum_topic_created_opener.py
@@ -0,0 +1,182 @@
+"""A newly created Telegram DM topic's opening message must land in that topic (Refs #136567).
+
+Telegram usually stamps the topic's opening message with the new ``message_thread_id``, but it
+sometimes delivers that opener with NO thread id at all. The ``forum_topic_created`` service
+message that precedes it is then the only update carrying the new topic id. Core registered no
+handler for service messages, so the adapter never learned the topic and the opener reached the
+runner as a thread-less lobby-shaped DM event - gateway lobby recovery then pinned it to the most
+recently bound topic and the new topic stayed empty.
+
+Transport is a stand-in; registration, gating, batching and PTB dispatch are real.
+"""
+
+import asyncio
+import json
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock
+
+import pytest
+
+pytest.importorskip("telegram")
+from telegram import Update
+from telegram.request import BaseRequest
+
+from gateway.config import PlatformConfig
+from plugins.platforms.telegram.adapter import TelegramAdapter
+
+
+class NoNetwork(BaseRequest):
+ def __init__(self, bot_id=111):
+ self.bot_id = bot_id
+
+ @property
+ def read_timeout(self):
+ return 1
+
+ async def initialize(self):
+ pass
+
+ async def shutdown(self):
+ pass
+
+ async def do_request(self, url, method, request_data=None, **kwargs):
+ endpoint = url.rsplit("/", 1)[-1]
+ assert endpoint == "getMe", "No Telegram polls, sends or downloads allowed"
+ return 200, json.dumps({"ok": True, "result": {
+ "id": self.bot_id, "is_bot": True, "first_name": "Offline", "username": "offline_bot",
+ }}).encode()
+
+
+def _chat(chat, group, *, is_forum=False):
+ payload = {"id": chat, "type": "supergroup" if group else "private"}
+ if group:
+ payload["is_forum"] = is_forum
+ return payload
+
+
+def topic_created(bot, *, uid=10, chat=42, user=88, thread=40798, message_id=40799, name="Prova 3", group=False):
+ """``forum_topic_created`` service message: carries the NEW topic's thread id, never text."""
+ return Update.de_json({"update_id": uid, "message": {
+ "message_id": message_id, "date": 1800000000, "chat": _chat(chat, group, is_forum=group),
+ "from": {"id": user, "is_bot": False, "first_name": "Human"},
+ "message_thread_id": thread, "is_topic_message": True,
+ "forum_topic_created": {"name": name, "icon_color": 7322096},
+ }}, bot)
+
+
+def opener(bot, *, uid=11, chat=42, user=88, message_id=40800, text="Prova 3", thread=None,
+ is_topic=None, group=False):
+ """The topic's opening user message. ``thread=None`` is the shape Telegram regressed to."""
+ message = {
+ "message_id": message_id, "date": 1800000001, "chat": _chat(chat, group, is_forum=group),
+ "from": {"id": user, "is_bot": False, "first_name": "Human"}, "text": text,
+ }
+ if thread is not None:
+ message["message_thread_id"] = thread
+ if is_topic is not None:
+ message["is_topic_message"] = is_topic
+ return Update.de_json({"update_id": uid, "message": message}, bot)
+
+
+@asynccontextmanager
+async def connected(monkeypatch, *, bot_id=111):
+ adapter = TelegramAdapter(PlatformConfig(enabled=True, token=f"{bot_id}:offline-test", extra={}))
+ monkeypatch.setenv("TELEGRAM_ALLOWED_USERS", "88")
+ monkeypatch.setenv("TELEGRAM_WEBHOOK_URL", "")
+ monkeypatch.setattr(adapter, "_build_ptb_requests", AsyncMock(return_value=(NoNetwork(bot_id), NoNetwork(bot_id))))
+ monkeypatch.setattr(adapter, "_start_polling_mode", AsyncMock())
+ monkeypatch.setattr(adapter, "_start_post_connect_housekeeping", lambda: None)
+ monkeypatch.setattr(adapter, "_restart_task_attr", lambda name, coroutine: coroutine.close())
+ monkeypatch.setattr(adapter, "_set_status_indicator", AsyncMock())
+ delivered = []
+ adapter._message_handler = AsyncMock()
+ monkeypatch.setattr(adapter, "_start_session_processing", lambda event, session_key: delivered.append(event) or True)
+ assert await adapter.connect(is_reconnect=False)
+ try:
+ yield adapter, adapter._app, delivered
+ finally:
+ await adapter.disconnect()
+ store = getattr(adapter, "_session_store", None)
+ if store is not None:
+ store.close_all_db_handles()
+
+
+async def _deliver(app, adapter, *updates):
+ for item in updates:
+ await app.process_update(item)
+ await asyncio.gather(*adapter._pending_text_batch_tasks.values())
+
+
[email protected]("is_topic", [None, True])
+async def test_new_topic_opener_lands_in_the_new_topic(monkeypatch, is_topic):
+ """The service message's topic id is adopted by the opening message that follows it."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ await _deliver(app, adapter, topic_created(app.bot), opener(app.bot, is_topic=is_topic))
+
+ assert [event.text for event in delivered] == ["Prova 3"], "the service message must not reach the agent"
+ assert delivered[0].source.thread_id == "40798"
+
+
+async def test_threadless_message_without_topic_creation_stays_lobby(monkeypatch):
+ """No preceding service message: an ordinary thread-less DM keeps its lobby shape."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ await _deliver(app, adapter, opener(app.bot))
+
+ assert delivered[0].source.thread_id is None
+
+
+async def test_non_adjacent_threadless_message_is_not_adopted(monkeypatch):
+ """Only the message immediately after the creation may claim the new topic."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ await _deliver(app, adapter, topic_created(app.bot), opener(app.bot, message_id=40805))
+
+ assert delivered[0].source.thread_id is None
+
+
+async def test_pending_topic_creation_expires(monkeypatch):
+ """A stale creation record must not claim a much later thread-less message."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ monkeypatch.setattr(TelegramAdapter, "_NEW_TOPIC_OPENER_TTL_SECONDS", -1.0)
+ await _deliver(app, adapter, topic_created(app.bot), opener(app.bot))
+
+ assert delivered[0].source.thread_id is None
+
+
+async def test_only_the_opener_consumes_the_creation(monkeypatch):
+ """One-shot: a second thread-less message in the same chat is not re-pinned."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ await _deliver(
+ app, adapter,
+ topic_created(app.bot),
+ opener(app.bot),
+ opener(app.bot, uid=12, message_id=40801, text="second"),
+ )
+
+ assert [event.source.thread_id for event in delivered] == ["40798", None]
+
+
+async def test_forum_group_general_message_is_not_adopted(monkeypatch):
+ """In a forum group a thread-less message IS General; a creation must not re-route it."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ await _deliver(
+ app, adapter,
+ topic_created(app.bot, thread=99, group=True),
+ opener(app.bot, group=True),
+ )
+
+ assert delivered[0].source.thread_id == "1"
+
+
+async def test_explicit_thread_on_the_opener_wins(monkeypatch):
+ """Telegram's healthy shape (opener carries its thread id) is untouched."""
+ async with connected(monkeypatch) as (adapter, app, delivered):
+ await _deliver(app, adapter, topic_created(app.bot), opener(app.bot, thread=40798, is_topic=True))
+
+ assert delivered[0].source.thread_id == "40798"