feat(telegram): two-phase guest reply — immediate stub + progressive streaming

[elphamale]

Summary

Handles Bot API 10.0 guest_message updates with a two-phase delivery loop:

• Phase 1: On receiving a guest_message, immediately fire answerGuestQuery with a random thinking-verb stub (e.g. "⏳ Brewing..."). The call returns an inline_message_id identifying the placed bubble.
• Phase 2 — streaming: send() returns inline_message_id to the stream consumer, which then drives progressive editMessageText(inline_message_id=…) edits for each chunk. All existing adaptive flood-control and think-block filtering apply transparently — no new rate-limit paths.
• Phase 2 — fallback: If the stub call fails (_imi is None), send() buffers text and on_processing_complete delivers via answerGuestQuery (original approach, still-live guest_query_id). A second fallback covers the stream-consumer flood path: non-empty _buffered triggers a final editMessageText edit.

Previously, guest-mode users saw nothing until the full LLM response was ready (10–30 s). This change gives immediate feedback and then updates the bubble in-place — no second bubble, no blank wait.

Streaming-finalize hardening

Beyond the core two-phase loop, four media-independent robustness fixes to the guest text path:

• _strip_mdv2 — unclosed bold. A stream cut mid-token (e.g. - **2) leaves the balanced **…** regex unmatched, so raw markdown surfaced in the bubble. A trailing pass removes any leftover **.
• send() — chat_id normalization. The event source can pass chat_id as int, which silently missed every str-keyed guest dict and dropped the reply onto the wrong delivery path. Normalized to str before lookups.
• send() — MEDIA: residual strip. Intermediate streaming chunks (MEDIA:, MEDIA:/path) slip past the stream consumer's extension-anchored cleanup and would buffer as visible text.
• edit_message() — buffer kept current. Each streaming edit updates _guest_reply_buffer, so on_processing_complete can re-render through _strip_mdv2 and recover a finalize the stream consumer left truncated.

As a consequence, on_processing_complete now always performs a final, idempotent re-render. When the stream consumer already finalized with identical text, Telegram returns not modified; that case is downgraded from warning to debug rather than logged as a failure.

Design note — why the stub stays immediate, not lazy

A natural follow-up question is whether the stub should fire lazily (on the first send()/send_typing) instead of immediately at handler entry. It is deliberately not lazy in this PR:

• Deferring the stub only earns its added state (a three-way False/None/str sentinel plus multiple fire points) once native media delivery needs the answerGuestQuery slot held open so a media tool can claim it. There is no such consumer here.
• For text-only replies there is no behavioral payoff: with a send_typing hook the lazy stub fires at essentially the same pre-LLM moment as the immediate one.
• Keeping it immediate makes this PR self-justifying and matches its title.

The lazy-stub refactor — and the gateway-rejection authz fallback it enables (an empty buffer with a placed stub should resolve to a terse refusal rather than a lingering "⏳") — is therefore scoped to the follow-up guest-media PR that stacks on this one.

thinking_verbs.py — design note

The stub verb is drawn from plugins/platforms/telegram/thinking_verbs.py, a deliberately separate file. The intent is that users can customize the list without touching adapter.py at all: swap in verbs from a different language, replace them with emojis, or maintain a larger set tuned to their SOUL.md persona.

The bundled list ships five verbs (Thinking, Pondering, Cooking, Toolcalling, Yarning) as a neutral starting point. Users can drop a replacement file into ~/.hermes/local-patches/plugins/platforms/telegram/thinking_verbs.py and it will override the bundled list after every gateway restart.

On verb provenance: During development I considered seeding the bundled list from the Claude Code spinner verb set. That list was not used — its provenance (extraction from a binary; no clear redistribution licence) creates ambiguity that is not worth importing into hermes-agent. The five bundled verbs are original.

Prerequisites

• feat(telegram/plugin): port guest mode + buffer fixes to adapter.py #49801 — adds guest_message to allowed_updates + reconnect polling + base buffer/flush logic in adapter.py. The two-phase stub builds directly on top of that.

New state added to __init__

self._guest_inline_message_ids: Dict[str, Optional[str]] = {}

Test plan

• Mention the bot in a foreign chat (guest mode eligible)
• Verify a random thinking-verb stub appears immediately (e.g. "⏳ Brewing...")
• Verify each streaming chunk progressively edits the bubble in-place
• Verify the final answer replaces the stub completely on completion
• Verify a reply cut mid-token (- **2) renders clean after finalize
• Automated coverage: tests/gateway/test_telegram_guest_reply.py (11 tests — streaming path, buffer fallback, state cleanup, and the four streaming-finalize fixes above)

🤖 Generated with Claude Code

[elphamale]

Status update — branch cleaned, feature essentially complete

The PR branch has been rebased onto a fresh commit directly on top of current main (no shared-history issue, no stale merge commits from dependency PRs). It is now MERGEABLE against main.

---

Guest mode delivery — feature complete

With this PR merged (and #49801 as the only prerequisite), Telegram guest-mode delivery is functionally complete and on par with what "claude tag" style bots provide:

• Immediate feedback stub — answerGuestQuery fires as soon as the mention arrives, showing ⏳ Thinking… so the user never stares at a blank chat.
• Buffer-only streaming — no intermediate raw-markdown edits during LLM generation; the full response is buffered first.
• Typewriter animation — after buffering, editMessageText progressively reveals the response (~8 frames, 0.4 s each) before delivering the final MarkdownV2-formatted text. Looks polished, no ** flicker.
• Slash command guard — /commands in guest context are caught before the LLM runs and answered directly; prevents the double-stub artifact.
• Media delivery — native photo/audio/video/document delivery via answerGuestQuery with LLM text as caption (covered by feat(telegram): guest-mode native media delivery + lazy two-phase stub #52639).
• Multi-segment tool responses — preamble text from tool calls is dropped; only the final answer reaches the user.

---

Security implemented so far

1. Slash command blocking — commands are rejected at the handler boundary before any LLM or PTB command-dispatcher path is entered. Prevents unintended tool execution via guest context.
2. _should_process_message gate — existing authorization checks (user ID validation, allowlist/blocklist) run before the stub is fired, so unauthorized senders never consume an answerGuestQuery slot.
3. Tool-progress strip — send() drops non-stream-consumer calls (tool progress blocks, 💻 terminal blocks) so internal execution details never leak into the guest reply.
4. MEDIA: tag sanitization — any raw MEDIA: path residuals are stripped from the buffer before delivery, preventing workspace path disclosure.
5. Guest-only chat isolation — _guest_only_chats set prevents guest chat IDs from accidentally routing through the regular sendMessage path (which Telegram would reject and which could expose bot errors to regular chats).

---

Open questions / suggestions welcome

The above covers the basics, but guest mode is a higher-exposure surface than regular DMs (bot hasn't joined the group, can't moderate it). Some areas that likely need attention:

• Security of authorized interactions — testing so far has been limited to a single known user; the "not authorized" path for unknown users works, but there is currently no protection against malicious or dangerous queries coming from an authorized user or from an authorized chat where third-party members can craft the mention text. One approach under consideration is assigning a separate, curtailed bot profile to guest-mode interactions (reduced tool access, stricter system prompt, no sensitive-context injection) so that even a fully authorized guest query operates within tighter constraints than a private DM session. This needs more design thought — in particular how the profile interacts with the existing persona/profile system and what the right capability boundary is.
• Per-chat rate limiting — a single group could fire many mentions rapidly; there's currently no cooldown or token-bucket guard at the guest handler level.
• Query length cap — very long queries (e.g. pasted documents) increase LLM cost and latency with no user-visible limit. A character cap with a friendly error reply would help.
• Per-user cooldown — distinct from per-chat; a single user in a large group could spam mentions.
• Group/domain allowlisting — optionally restrict which chat_ids (or chat types: groups vs supergroups vs channels) are permitted to trigger guest replies.
• Reply content guardrails — guest replies go to chats the bot doesn't moderate; there's no second-pass filter on the outgoing text (beyond what the LLM itself provides).
• Audit trail — guest interactions are currently logged at logger.info level which is below the default verbosity threshold. Explicit warning-level audit events for every guest query (who asked, from which chat, response length) would help with abuse detection.
• Stub timeout / cancellation — if the LLM takes too long and the answerGuestQuery stub expires (Telegram TTL), the inline message becomes un-editable but there's no graceful fallback or user notification.

Happy to discuss priorities or implementation approaches for any of the above.

[elphamale]

Closing in favor of a clean rebuild off current main, sourced from the same production-tested guest-mode code: #56476 (two-phase reply foundation) and #56477 (deliver_ media flow, stacked on #56476). This branch had drifted too far from main to cleanly rebase, and the reconstruction accidentally carried some content that shouldn't ship (a personalized thinking_verbs.py data file) — the new PRs are clean of that. Docs in #56297 have been updated to point at the new PRs.