feat: event-driven wait_for_new_message + debounced wait_for_settled_message

[artgas1]

Summary

Lets MCP agents react to incoming messages instead of polling get_messages/list_chats on a timer.

A Telethon NewMessage(incoming=True) handler (attached to every configured client) records incoming private, non-bot, non-self messages per chat. Two new tools expose them:

• wait_for_new_message(timeout=50) — block until a new incoming user message arrives; returns the chats with pending messages. Does not consume them.
• wait_for_settled_message(settle_ms=6000, max_wait_ms=50000) — debounced wait. Returns a chat only after it has gone quiet for settle_ms, so a user who types several messages (or sends file + text) in a row is delivered as one settled burst instead of waking the agent on every message. Each new message resets the timer. Consumes the burst (next call returns the next settled chat); returns {"event": false, "reason": "timeout"} if nothing settles in max_wait_ms.

Why

Per-timer polling is wasteful and reacts on partial input (replying to message 1 of 3). This makes agents event-driven and naturally batches multi-message bursts.

Implementation

• New module telegram_mcp/tools/events.py, registered via the telegram_mcp.tools package import (decorator pattern, like the other tool modules).
• In-process state (single asyncio loop), no new deps.
• Handler attached to all clients in clients (multi-account safe).

Tests / checks

• black + flake8 clean, pytest green locally.
• Package imports cleanly; handler registers on the default client.

🤖 Generated with Claude Code