feat(telegram): guest mode two-phase reply (Bot API 10.0, text-only)

[elphamale]

Summary

• Handles Telegram Bot API 10.0 guest_message updates for chats the bot is not a member of
• Fires a text "thinking" stub via answerGuestQuery immediately on first activity, buffers the streamed reply, then edits the stub in place via editMessageText (using the returned inline_message_id) once the response is ready
• Text-only foundation — no media delivery and no query-content classification; the stub always fires. Media delivery lands in a follow-up PR stacked on this one.
• Rebuilt fresh off current main from the live, production-tested guest-mode code, superseding the earlier stale reconstructions in feat(telegram): two-phase guest reply — immediate stub + progressive streaming #51886 and feat(telegram): guest-mode native media delivery + lazy two-phase stub #52639 (to be closed with a pointer to this PR)

Test plan

• New tests/gateway/test_telegram_guest_reply.py — stub-fire and OPC text-flush coverage
• Updated _make_adapter() helpers in test_telegram_reactions.py, test_telegram_thread_fallback.py, test_telegram_username_chat_id.py to include the new guest-mode instance attributes (these tests construct the adapter via object.__new__, bypassing __init__)
• Full tests/ -k telegram suite passes with no new regressions vs. a clean main baseline

Update: UTF-16 truncation fix (addresses hermes-sweeper review)

hermes-sweeper flagged a blocking bug: the final OPC flush truncated the reply with _plain[:4096] — Python string length, not UTF-16 code units. Telegram's 4,096 limit is UTF-16 units, so e.g. 2,049 emoji is 2,049 chars but 4,098 units — a heavy-emoji reply could pass this truncation and then fail the real editMessageText call, silently dropping the turn after guest state had already been torn down.

Fixed by reusing the existing _truncate_stream_overflow_preview() helper (the same UTF-16-aware truncate_message() the regular streaming edit path already uses) instead of a naive slice. Also switched the typewriter animation to iterate over the already-truncated text instead of the raw buffered reply — it was typing out untruncated content and then visibly "shrinking" on the final edit, on top of risking oversized intermediate frames for the same reason. Added a regression test (test_branch1_opc_truncates_by_utf16_units_not_python_length) that asserts every editMessageText call — typewriter frames and the final edit — stays within the UTF-16 cap.

Sweeper also flagged the thinking_verbs.py dynamic-exec loader as dead initialization, since the file doesn't exist in this PR or on main. That diagnosis was right but my first fix (dropping the loader for a hardcoded ["Thinking"]) was wrong — the file existed in this same feature's earlier iteration, #51886 ("feat(telegram): add bundled thinking_verbs.py with minimal curated list"), and was simply dropped when this branch was rebuilt fresh off main. Restored it instead:

# Thinking-verb stub displayed while Hermes processes a guest query.
# Customize freely: translate to another language, swap in emojis, curate
# to match your SOUL.md persona, or replace this file entirely via
# ~/.hermes/local-patches/plugins/platforms/telegram/thinking_verbs.py.
THINKING_VERBS = [
    "Thinking", "Pondering", "Cooking", "Toolcalling", "Yarning",
]

The loader itself is intentional, not dead code: it's designed so operators can customize the stub's progress-verb list — translate it, curate it to their bot's persona, swap in emojis — by dropping a replacement file at ~/.hermes/local-patches/plugins/platforms/telegram/thinking_verbs.py, without needing a code change. That's the same override mechanism this codebase already uses elsewhere for personal/operator-specific customization. The bug was that the bundled default got lost in the rebuild, not that the loader mechanism was wrong.

🤖 Generated with Claude Code

[alt-glitch]

This was generated by AI during triage.

Related: supersedes the stale guest-mode reconstructions #51886 and #52639 (both still open), rebuilt fresh off main. Also related to #56297 (docs for this flow) and the earlier-open guest-mode impls #43049 / #32802. Not a duplicate — this is the fresh production-tested salvage a human should pick as canonical over the superseded pair.

[elphamale]

Related docs: #56297 documents the Bot API 10.0 guest mode media delivery flow this PR (and the stacked #56477) implements.

[mazzz3r]

Really like this one. The two-phase flow reads clean, and honestly the restart dedup, MEDIA stripping and busy-chat handling are better than what I had.

I was writing my own guest-mode PR (#59879) and triage flagged it as a dup of this cluster, which is fair. So instead of competing I want to hand you the one bit I think is missing here.

There's no auth check on who the guest caller is.

Guest handling only checks _telegram_guest_mode() and _should_process_message(). But _should_process_message() only looks at the chat and the mention. For any chat outside allowed_chats it just returns the guest bypass:

allowed = self._telegram_allowed_chats()
if allowed and chat_id_str not in allowed:
    return guest_mention   # any @mention from any non-allowlisted chat passes

Fine as guest behavior, but it also means that with guest_mode: true, anyone who knows the bot's @handle can drive it from any group. No check on the person. On a bot wired to an LLM and tools that's an open door for abuse, cost and prompt injection. And the caller for guest updates lives in guest_bot_caller_user, not msg.from_user, so even a from_user check would be reading the wrong field.

The fix is small and stays inside the adapter (no gateway changes). Gate the caller in _handle_guest_message_update, fail closed, reuse the allowlists you already have:

# after parsing `msg`, before registering guest state
caller = getattr(msg, "guest_bot_caller_user", None) or msg.from_user
caller_id = str(getattr(caller, "id", "") or "").strip()
if not self._is_guest_caller_authorized(caller_id):   # empty allowlist => deny all
    logger.warning("[%s] Unauthorized guest caller: %s", self.name, caller_id)
    return

_is_guest_caller_authorized just unions allow_from, group_allow_from, TELEGRAM_ALLOWED_USERS (plus a * wildcard) and denies when the list is empty. Tested on my branch. I can open a small PR against feat/guest-two-phase-reply-clean or drop the diff here, whichever works for you.

One thing I'm curious about: state is keyed by chat_id, and you bounce concurrent same-chat queries with the busy reply, but two guest turns from the same chat one after another still land on the same session. So the previous asker's context can bleed into the next one. Is that intended? I gave each guest turn its own session-key suffix on my branch, though that touches gateway/session.py, which you're deliberately keeping clean here, so maybe it's better as a follow-up.

[elphamale]

Thanks for this — and for closing #59879 to hand it over instead of racing it. Genuinely good sportsmanship, appreciated.

I like both ideas and I'm going to do them.

Caller auth (fail-closed): you're right, this is the gap. On a bot wired to an LLM + tools, "anyone who knows the @handle can drive it from any group" is an open door, and the approval work elsewhere in this stack only gates dangerous commands — it does nothing about someone just burning tokens or slipping in a prompt injection. Hermes is aimed at individuals / small teams, so the right default is a tight allowlist, not gen-pop access, with * as the explicit opt-out for anyone who really wants it open. One adaptation on my branch: I parse the raw payload via Message.de_json, and PTB drops fields it doesn't model — so getattr(msg, "guest_bot_caller_user", ...) comes back None here; the caller id has to be read from the raw dict instead. I'll route the check through the same is_authorized() the rest of the bot (and the approval buttons) already use, so there's one definition of "who's allowed" including the pairing store. Landing it as a commit here with you as Co-authored-by:.

Session bleed: this one's a nice catch. Funny timing — I'd been going back and forth on exactly this and had talked myself out of the obvious version: my first instinct was a brand-new session per guest turn, but I killed it because a chatty user would spawn a pile of throwaway sessions. Your per-turn suffix is the same instinct, and it made me realize the middle key I should've reached for is (chat_id, caller_id) — repeat turns from the same guest reuse their session, different askers in the same chat stay isolated, and it scales with distinct callers rather than messages. And it composes with the caller gate above: once only allowlisted users can invoke guest mode, "distinct callers" is bounded by the allowlist, so the thing that made per-caller keying scary just goes away. That half touches gateway/session.py, which I'm keeping clean in this PR, so I'll take it as the immediate follow-up rather than folding it in here.

Will ping you when these land. Thanks again.

[elphamale]

Both landed on this branch, co-authored to you.

Caller gate — fail-closed in _handle_guest_message_update, before the busy-reply, state registration, and the deliver_<token> branch (so a leaked token can't be redeemed by an unauthorized caller either). Reads the caller from the raw guest_bot_caller_user (via raw_gm, since de_json drops the unmodeled field on this branch) and routes through the same _is_callback_user_authorized the exec-approval buttons use — env allowlists ∪ pairing store, * opt-out, deny on empty/unknown. If the caller field is ever absent it logs the payload keys loudly so a field-name drift is diagnosable instead of a silent deny-all. That raw field name is the one thing I'll confirm against a live payload on the first test.

Session bleed — your suffix idea pushed me to a slightly smaller version. Since the caller gate means guests are now authorized users, I just stamp the real caller id onto the event source and let the existing group keying isolate them: build_session_key already splits group participants by user_id, guest messages just never carried one. So it comes out as …:group:<chat_id>:<caller_id> — per-caller when group_sessions_per_user is on, shared only if the operator deliberately turned that off — and behaves exactly like ordinary group traffic, no guest-specific branch in session.py. Same outcome you were after, one less moving part.

Thanks again — this was a good catch and a clean handoff.

[GottZ]

This was generated by AI during triage.

Summary

Four PRs address or reference the missing Telegram Bot API 10.0 guest-message delivery path. #51886 and #52639 are stale cumulative prototypes, while #56476 cleanly rebuilds the text-only guest-reply foundation and #56477 adds the stacked media-delivery flow.

Related pull requests

• #51886 [closed] duplicate — (+1406/-379) — superseded prototype: Implements guest_message ingestion, answerGuestQuery stubs, buffered/edited text replies, and media handling, but the diff also carries substantial unrelated Telegram changes and a personalized thinking-verbs file; it remains relevant as the original implementation now cleanly rebuilt as #56476 and #56477.
• #52639 [closed] related — (+1381/-217) — superseded cumulative media prototype: Extends the two-phase guest reply with lazy stubs and native media staging, but includes the stale #51886 foundation plus unrelated changes; its text foundation is replaced by #56476 and its media scope by #56477.
• #56476 related — (+953/-5) — canonical text foundation: Adds explicit guest_message allowed-updates and handling, fail-closed caller authorization, per-caller session isolation, in-flight-query protection, restart deduplication, buffered answerGuestQuery/editMessageText delivery, and focused regressions. This is consistent with the keep_open review on #56476; its blocking UTF-16 truncation finding is addressed in the diff with UTF-16-aware truncation and an emoji-boundary test.
• #56477 related — (+1711/-8) — stacked media follow-up: Builds on #56476 with contained media staging, short-lived deliver_ redemption, authorized direct dispatch, stale-file avoidance, and final-segment-only buffering. This is consistent with the keep_open review on #56477; the missing path-translation call and insufficient handler coverage identified there were replaced with an existing cache-path translator and real-handler tests.

Duplicates

#51886 substantially overlaps the #56476 text foundation and parts of #56477; #52639 cumulatively overlaps both #56476 and #56477. #56477 is not a duplicate of #56476 because it is the intentionally stacked media extension.

Suggested consolidation

Merge #56476 as the canonical text-only guest-mode foundation, then restack and evaluate #56477 as its media follow-up. #51886 and #52639 can remain closed as superseded duplicates of the clean #56476/#56477 split.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    subgraph Dup51886 ["PRs duplicating each other"]
        P51886["PR #51886 (closed)"]
        P56476["PR #56476 (open)"]
    end
    class P51886 closed
    class P56476 open
    class P56476 target
    click P51886 "https://github.com/NousResearch/hermes-agent/pull/51886"
    click P56476 "https://github.com/NousResearch/hermes-agent/pull/56476"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 4 pull requests and 0 issues in this complex. Each diff was read against this issue; Assessment working set: 380 kB of PR diffs, 17 kB of issue/PR text, 21 kB of discussion (17 comments), 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.