hermes - 💡(How to fix) Fix Telegram group reply-derived thread IDs can route human-handoff “done” replies into the wrong session [1 pull requests]

Title

Telegram group reply-derived thread IDs can route human-handoff “done” replies into the wrong session

Summary

A Telegram group human-handoff workflow can misroute short continuation messages such as Done / continue into a different Hermes session. In the observed case, Hermes asked the user to complete a noVNC/CAPTCHA login handoff and then “reply done”; the user sent Done, but the gateway routed it to an unrelated group session, so the model replied only Done. instead of resuming the browser/CAPTCHA workflow.

This does not look like a model-quality/configuration issue. The evidence points to Telegram session-key fragmentation around message_thread_id and reply handling.

Observed evidence

From gateway/session logs, the same chat/user interaction split into three different session lanes:

• Handoff request and noVNC response used a reply-derived lane:
  • text batch key shape: agent:main:telegram:group:<chat>:461
  • session: handoff/noVNC setup
  • assistant said: “Please complete the CAPTCHA/login there, then reply ‘done’ and I’ll continue.”
• User sent plain Done:
  • text batch key shape: agent:main:telegram:group:<chat>:<user_id>
  • session: an unrelated existing group session
  • assistant response length was 5 chars: Done.
• User replied “What do u mean done?” to the bot’s Done.:
  • text batch key shape: agent:main:telegram:group:<chat>:465
  • session: yet another new reply-derived lane

So the continuation was not delivered to the session that created the noVNC handoff.

Likely root cause

The Telegram adapter currently preserves message.message_thread_id for every group message:

# gateway/platforms/telegram.py
if thread_id_raw is not None:
    if chat_type == "group":
        thread_id_str = str(thread_id_raw)

Then gateway/session.py::build_session_key() includes thread_id in the session key and, by default, does not include the user ID for threaded group sessions. This makes reply-derived message_thread_id values behave like stable forum/topic IDs.

In regular Telegram groups / reply flows, these values can correspond to reply/thread UI anchors rather than a durable forum topic. That fragments one human workflow into separate sessions like <chat>:461, <chat>:<user_id>, and <chat>:465.

There is also no durable “pending human handoff” mapping from the outbound noVNC/handoff message back to its originating session, so a plain Done has no way to find the session that requested the handoff.

Expected behavior

After Hermes asks the user to complete a login/CAPTCHA/noVNC handoff and then reply done / continue:

• the next matching acknowledgement from the same chat/user should resume the originating session, or
• if the user replies to the bot’s handoff message, that reply should route to the originating session, not create a new session lane, and
• Hermes should continue the pending task rather than answering with a generic Done..

Actual behavior

The acknowledgement was routed to a different session and the model replied only Done., leaving the noVNC/CAPTCHA workflow waiting.

Suggested fix direction

1. Telegram group thread handling

   • Only treat message_thread_id as a true session thread for actual Telegram forum/topic messages, e.g. when chat.is_forum / message.is_topic_message indicates a real topic.
   • For ordinary group replies outside forum topics, ignore reply-derived message_thread_id when building the session key.
   • Add regression coverage for:
     • non-forum group reply with message_thread_id: session key should stay <chat>:<user_id>;
     • forum/topic group message: session key should preserve the real topic/thread ID.

2. Human handoff robustness

   • When sending a login/CAPTCHA/noVNC handoff, register a pending continuation keyed by (platform, chat_id, user_id) and/or outbound message_id -> session_key.
   • Route simple acknowledgements (done, continue, completed, etc.) back to the originating session while the handoff is active.
   • Expire the mapping after a short TTL or once consumed.
   • Optional: send a button or explicit “Reply to this exact message with done” instruction, but routing should still be robust if the user sends a plain acknowledgement in the same chat.

Screenshot evidence

The reporter explicitly approved publishing the full screenshot for this issue.