Merge pull request chigwell#176 from ex3lite/feat/rich-messages

feat: favorite aliases, incoming event feed (callback mode), rich messages with Premium gating

Author: chigwell

.env.example

@@ -2,6 +2,10 @@
 TELEGRAM_API_ID=123456
 TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
 
+# --- Incoming event feed (optional, Claude Code callback mode; see README) ---
+# TELEGRAM_EVENT_FEED=1
+# TELEGRAM_EVENT_FEED_FILE=/path/to/incoming_feed.jsonl
+
 # --- Single account (backward-compatible) ---
 # Option 1: File-based session (a .session file will be created)
 TELEGRAM_SESSION_NAME=telegram_session

.gitignore

@@ -200,3 +200,4 @@ test_voice.ogg
 sticker.webp
 two.png
 aliases.json
+incoming_feed.jsonl

README.md

@@ -45,14 +45,26 @@ The server currently includes 80+ MCP tools grouped into these areas:
 
 - **Accounts:** list configured accounts and route tool calls by account label.
 - **Chats and groups:** list chats, inspect metadata, create groups/channels, join or leave chats, invite users, manage admins, bans, default permissions, slow mode, topics, invite links, common chats, read receipts, and message links.
-- **Messages:** send, schedule, edit, delete, forward, pin, unpin, mark read, reply, search, inspect context, create polls, manage reactions, inspect inline buttons, and press inline callbacks.
+- **Messages:** send, schedule, edit, delete, forward, pin, unpin, mark read, reply, search, inspect context, create polls, manage reactions, inspect inline buttons, and press inline callbacks. `send_message`, `reply_to_message`, and `edit_message` support classic formatting (`parse_mode='md'`/`'html'`) and server-side rich formatting (`parse_mode='rich'`/`'rich_markdown'`/`'rich_html'` — full Markdown/HTML with tables, headings, formulas, and collapsible sections). Rich modes require Telegram Premium on the account; Premium is re-checked on every call, and without it nothing is sent — the tool returns a structured `telegram_premium_required` result so the agent can reformat with classic modes and retry.
 - **Contacts:** list, search, add, delete, block, unblock, import, export, inspect direct chats, find recent contact interactions, and manage favorite aliases (e.g. save "andrew" so any tool accepting a `chat_id` resolves it; searches check favorites first).
 - **Media:** send files, download media, upload files, send voice notes, stickers, GIFs, and inspect message media.
 - **Profile and privacy:** get your own account info, update profile fields, set or delete profile photos, inspect privacy settings, get user info/photos/status, and manage bot commands.
 - **Folders and drafts:** list, create, update, reorder, and delete Telegram folders; save, list, and clear drafts.
+- **Events:** wait for incoming messages with debounce (`wait_for_new_message`, `wait_for_settled_message`), or enable the opt-in incoming event feed for callback-style delivery (see below).
 
 All tool results that include Telegram user-controlled content are sanitized and, where practical, returned as structured JSON.
 
+### Incoming Event Feed (callback mode, Claude Code only)
+
+By default, an agent waits for replies by calling `wait_for_settled_message`, which blocks up to the MCP tool timeout and must be re-called — that works everywhere (Codex, Cursor, etc.) and is unchanged.
+
+Clients that can wake an agent on external output (Claude Code's persistent `Monitor` on `tail -f`) can switch to callback mode instead:
+
+1. The agent calls `enable_incoming_feed` (or set `TELEGRAM_EVENT_FEED=1` in the environment to auto-enable). Each settled incoming burst is appended as one JSON line to `${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/incoming_feed.jsonl`, created owner-only (0600). Override the path with `TELEGRAM_EVENT_FEED_FILE` — an explicit path's directory must already exist. `incoming_feed_status` reports the effective path and a ready-to-use watch command.
+2. The agent arms a persistent Monitor with the `watch_command` returned by the tool. Every new line re-invokes the agent with the burst summary; no blocking tool call is held open, and the chat stays free.
+
+`disable_incoming_feed` switches back; `incoming_feed_status` reports the current mode. While the feed is enabled it consumes settled bursts, so don't combine it with `wait_for_settled_message`. Feed lines contain user-generated `name` fields — treat them as untrusted data.
+
 ## Requirements
 
 - Python 3.10+

telegram_mcp/runtime.py

@@ -816,6 +816,46 @@ def format_entity(entity) -> Dict[str, Any]:
     return result
 
 
+# Parse modes that request server-side rich formatting (tables, headings,
+# formulas, collapsible sections — the June 2026 "Rich Messages" feature).
+# Sending rich messages requires Telegram Premium on the account.
+RICH_PARSE_MODES = {"rich", "rich_md", "rich_markdown", "rich_html"}
+
+
+async def account_is_premium(client) -> bool:
+    """Fresh Premium check at call time — Premium can expire or be bought anytime."""
+    me = await client.get_me()
+    return bool(getattr(me, "premium", False))
+
+
+def make_rich_input(parse_mode: str, text: str):
+    """Build the InputRichMessage payload for a rich parse mode."""
+    if parse_mode == "rich_html":
+        return types.InputRichMessageHTML(html=text)
+    return types.InputRichMessageMarkdown(markdown=text)
+
+
+def premium_required_result(action: str) -> str:
+    """Structured refusal so the agent can degrade gracefully instead of sending garbage."""
+    return json.dumps(
+        {
+            "sent": False,
+            "reason": "telegram_premium_required",
+            "detail": (
+                f"{action} with rich formatting requires Telegram Premium on this account. "
+                "Nothing was sent. Reformat without rich-only blocks (tables, headings, "
+                "formulas) and retry with parse_mode='md' or 'html'."
+            ),
+        },
+        ensure_ascii=False,
+    )
+
+
+def is_premium_rpc_error(error: Exception) -> bool:
+    """True when Telegram rejected a call because the account lacks Premium."""
+    return "PREMIUM" in getattr(error, "message", str(error)).upper()
+
+
 _ALIASES_FILE = Path(__file__).resolve().parent.parent / "aliases.json"