feat(telegram): support Bot API 10 guest messages

[mazzz3r]

What does this PR do?

Adds Telegram Bot API 10.0 guest-message support to the current plugin-based Telegram adapter.

Telegram guest messages let a bot receive explicit @mentions from groups where it is not a member. Those updates cannot be answered through normal sendMessage chat delivery; they must use answerGuestQuery. This PR wires that path through the Telegram adapter, preserves guest metadata through gateway session/progress handling, and prevents duplicate normal final sends after the guest reply is delivered.

This is related to the existing guest-mode work already open upstream:

• feat: support Telegram guest messages #32802
• feat(telegram): implement Bot API 10.0 guest mode (@mention from non-member chats) #43049
• feat(telegram/plugin): port guest mode + buffer fixes to adapter.py #49801
• fix(telegram): guest @mention reply shows only final answer, not inter-tool preamble #50601
• fix(telegram): handle channel senders and fix guest reply ordering #49116
• feat(telegram): guest mode two-phase reply (Bot API 10.0, text-only) #56476
• feat(telegram): guest mode deliver_<token> media flow #56477
• docs(telegram): document Bot API 10.0 guest mode media delivery #56297
• issue [Bug]: disable streaming for guest replies that use answerGuestQuery #46196

I found these while following the contributing guide's duplicate-search step. If maintainers prefer, this can be treated as a tested current-main patch/reference for one of those PRs instead of a competing PR.

Related Issue

Related to #46196 and the open Telegram guest-mode PR stack listed above.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• plugins/platforms/telegram/adapter.py
  • subscribes polling/webhook startup to guest_message updates;
  • handles native PTB 22.8 guest-message updates;
  • routes guest replies through answer_guest_query;
  • supports editing guest placeholder replies through returned inline-message metadata;
  • preserves normal Telegram chat/topic/group behavior.
• gateway/platforms/base.py
  • adds platform metadata to message events so downstream gateway code can identify guest replies.
• gateway/session.py
  • preserves Telegram guest metadata in session source data and isolates guest sessions with a suffix.
• gateway/run.py
  • carries guest metadata into progress/final send paths;
  • suppresses normal final delivery when a guest reply has already been delivered through the guest path.
• gateway/config.py, hermes_cli/config.py, cli-config.yaml.example
  • bridge/document guest-related Telegram config fields.
• pyproject.toml, uv.lock
  • bump python-telegram-bot[webhooks] from 22.6 to 22.8 for Bot API 10.0 guest-message API support.
• tests/gateway/test_telegram_guest_botapi10.py
  • adds focused regression coverage for guest update handling, metadata propagation, session isolation, and final-send suppression.
• tests/gateway/test_telegram_format.py
  • isolates Telegram formatting tests from bridged group-topic config state.

How to Test

1. Verify PTB exposes Bot API 10.0 guest support:

   uv run --extra messaging python - <<'PY'
   import telegram
   from telegram import Update, Message, Bot, SentGuestMessage
   print(telegram.__version__)
   print('guest_message' in Update.ALL_TYPES)
   print(hasattr(Message, 'guest_query_id'))
   print(hasattr(Message, 'guest_bot_caller_user'))
   print(hasattr(Message, 'guest_bot_caller_chat'))
   print(hasattr(Bot, 'answer_guest_query'))
   print(SentGuestMessage.__name__)
   PY

2. Run focused Telegram/gateway regression tests:

   uv run --extra dev --extra messaging pytest \
     tests/gateway/test_run_progress_topics.py::test_run_agent_previewed_split_keeps_final_delivery_pending \
     tests/gateway/test_telegram_group_gating.py \
     tests/gateway/test_telegram_format.py \
     tests/gateway/test_telegram_guest_botapi10.py \
     -q

3. Run lint for touched Python files:

   uv run --extra dev ruff check \
     gateway/config.py gateway/platforms/base.py gateway/run.py gateway/session.py \
     hermes_cli/config.py plugins/platforms/telegram/adapter.py \
     tests/gateway/test_telegram_format.py tests/gateway/test_telegram_guest_botapi10.py

4. Optional runtime check:

   • enable Telegram guest mode in config/BotFather;
   • restart the gateway;
   • mention the bot from a group where it is not a member;
   • verify Hermes sends the placeholder and replaces/sends the final answer without a duplicate normal chat send.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(telegram): support Bot API 10 guest messages)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A.

Screenshots / Logs

Local verification:

$ uv run --extra messaging python - <<'PY'
...
PY
22.8
True
True
True
True
True
SentGuestMessage

$ uv run --extra dev --extra messaging pytest tests/gateway/test_run_progress_topics.py::test_run_agent_previewed_split_keeps_final_delivery_pending tests/gateway/test_telegram_group_gating.py tests/gateway/test_telegram_format.py tests/gateway/test_telegram_guest_botapi10.py -q
170 passed, 7 warnings in 16.84s

$ uv run --extra dev ruff check gateway/config.py gateway/platforms/base.py gateway/run.py gateway/session.py hermes_cli/config.py plugins/platforms/telegram/adapter.py tests/gateway/test_telegram_format.py tests/gateway/test_telegram_guest_botapi10.py
All checks passed!

$ git diff --check
# no output

Note: I did not run the full pytest tests/ -q suite in this environment; only the focused Telegram/gateway regression set above.

[Copilot]

Pull request overview

Adds Telegram Bot API 10.0 “guest message” support to the plugin-based Telegram adapter, routing replies via answerGuestQuery/inline edits and propagating per-message guest metadata through the gateway/session pipeline so guest turns can be isolated and delivered correctly.

Changes:

• Bump python-telegram-bot[webhooks] to 22.8 (Bot API 10 guest APIs) and wire Telegram adapter handling for guest_message updates + guest reply delivery/editing.
• Propagate ephemeral platform metadata through SessionSource / thread-metadata helpers and incorporate a suffix into build_session_key() for guest session isolation.
• Add focused gateway/Telegram guest-mode regression tests and adjust Telegram formatting tests to avoid cross-test config bleed.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
uv.lock	Updates the locked python-telegram-bot version to 22.8.
pyproject.toml	Pins the messaging/termux extras to python-telegram-bot[webhooks]==22.8.
plugins/platforms/telegram/adapter.py	Implements guest update extraction/authorization + reply via answerGuestQuery and inline edits; subscribes to guest_message updates.
gateway/platforms/base.py	Preserves platform_metadata when building thread metadata for adapter sends.
gateway/session.py	Adds platform_metadata to SessionSource and appends a session_key_suffix when building session keys.
gateway/run.py	Merges platform metadata into send/progress metadata and adds logic to suppress duplicate final sends after streaming.
gateway/config.py	Bridges the new Telegram guest_thinking_text config field into platform extra.
hermes_cli/config.py	Adds default Telegram guest_thinking_text in the CLI config defaults.
cli-config.yaml.example	Documents the guest_thinking_text Telegram config field in the example config.
tests/gateway/test_telegram_guest_botapi10.py	Adds tests covering guest update handling, metadata propagation, guest send/edit behavior, and session key suffix behavior.
tests/gateway/test_telegram_format.py	Ensures Telegram formatting tests set platform and isolate topics config to avoid cross-test pollution.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[alt-glitch]

This was generated by AI during triage.

Duplicate of #43049 — same Telegram Bot API 10 guest-message feature (guest_message subscription + answerGuestQuery reply path). #43049 is the earliest-open comprehensive guest-mode implementation in this cluster (#51082 was already deduped into it and is now closed; #32802 competes). related to #32802. Kept open; a maintainer should pick the canonical implementation.