feat(telegram): inline query mode with Platform.TELEGRAM_INLINE

[elphamale]

Why this PR

1. Guest mode and inline mode are distinct API surfaces that conflict on a shared token

Telegram Bot API 10.0 introduced guest mode: bots can receive guest_message updates from groups without being a member. That surface is text-only — any attempt to send media returns guest_chat_no_media. The solution for media delivery is inline mode (@botname <query>), where the user sends the result, not the bot, so group membership is irrelevant.

These two surfaces cannot share one python-telegram-bot Application without race conditions on the update-routing loop. A second Application instance running on TELEGRAM_BOT_TOKEN_INLINE isolates the inline polling loop completely. Platform.TELEGRAM_INLINE gives that second adapter a first-class enum value, separate env-var, and its own lifecycle in the platform registry — exactly the same pattern already used for Platform.RELAY.

2. Inline tool registry: explicit whitelist, type: direct vs type: llm

InlineToolRegistry reads inline_tools.yaml from the Hermes config directory. Every tool that can be reached via inline query must be listed and have enabled: true. Unlisted executors cannot be dispatched — the dispatcher logs a warning and returns a "failed" cache entry.

Two tool types are defined:

type	LLM calls	Primary use case
direct	zero	media/file fetching, deterministic lookups
llm	one	short text answers, search summaries

The distinction is load-bearing: Telegram imposes a hard 30-second timeout on answerInlineQuery. LLM calls on a slow model can easily exceed this; type: direct tools never will. LLM tools are supported in the schema but should use a fast/small model tier.

3. Speed constraint — 30 s hard timeout drives the direct-first design

Telegram silently drops answerInlineQuery calls that arrive after 30 seconds. The adapter implements a two-phase UX that works around this:

1. First query → cache miss → set status: downloading → return InlineQueryResultArticle("Downloading...") immediately (within milliseconds)
2. Background task runs the executor
3. Second query (user re-types or waits) → cache hit → return InlineQueryResultCachedAudio with the stored file_id

The cache_time=0 on the "Downloading" result forces Telegram to re-query on every keystroke; cache_time=300 on the ready result lets Telegram cache it locally.

4. file_id caching is the correct Telegram primitive for repeated delivery

Once a file is uploaded to Telegram via send_audio, the returned audio.file_id is permanent on Telegram's servers regardless of where the message was sent. InlineQueryResultCachedAudio reuses that ID for instant inline delivery without re-uploading. The in-memory cache in TelegramInlineRouter holds {query_lower → {status, file_id}} for the adapter lifetime; entries are evicted on "failed" status to allow retries.

The staging_chat_env key in inline_tools.yaml names an environment variable (TELEGRAM_INLINE_STAGING_CHAT) that holds the chat ID where the executor stages uploads. This is an executor-level concern; the router itself never reads it.

5. platforms.telegram.inline.enabled — fail-open gate

platforms:
  telegram:
    inline:
      enabled: false   # set to disable; omit to enable (default: true)

_handle_inline_query checks this at the top and returns silently if disabled. The gate is fail-open (missing key → enabled) so existing deployments without the key are unaffected.

6. What this PR does NOT include

No specific inline tool implementation ships upstream. InlineExecutor is an abstract base class; register_executor() on TelegramInlineRouter accepts user-space factories. The inline_tools.yaml registry schema is documented in the module docstring. Concrete executors (media downloaders, search handlers, etc.) are user-space concerns and are intentionally absent.

Files changed

File	Change
gateway/config.py	Platform.TELEGRAM_INLINE enum; TELEGRAM_BOT_TOKEN_INLINE env pickup; inline config key bridge
gateway/platforms/telegram_inline_router.py	new — InlineToolRegistry, InlineExecutor ABC, TelegramInlineRouter
plugins/platforms/telegram/adapter.py	inline_only_mode handler gating; _handle_inline_query; _build_inline_adapter; second register_platform
agent/skill_utils.py	Skip inline_only: true skills from chat-mode context

Test plan

• Set TELEGRAM_BOT_TOKEN_INLINE to a second bot token and start the gateway — confirm telegram_inline platform connects
• Type @botname query in any Telegram chat — confirm "Downloading..." placeholder appears immediately
• With no executor registered, confirm inline query returns "Executor not registered" error result and does not crash the adapter
• Confirm primary telegram platform chat handlers are unaffected (no regression on text, command, media, callback flows)
• Set platforms.telegram.inline.enabled: false in config — confirm inline queries are silently dropped
• Add a skill with inline_only: true frontmatter — confirm it does not appear in agent chat completions

🤖 Generated with Claude Code