feat: Add Telegram transport support (Issue #11)

beacon_skill/cli.py

@@ -129,7 +129,7 @@ def _maybe_udp_emit(cfg: Dict[str, Any], event: Dict[str, Any]) -> None:
 _ALL_KINDS = ["like", "want", "bounty", "ad", "hello", "link", "event", "pay",
               "pulse", "offer", "accept", "deliver", "confirm", "subscribe",
               "mayday", "heartbeat", "accord"]
-_ALL_TRANSPORTS = ["udp", "webhook", "discord", "bottube", "moltbook", "clawcities", "clawsta", "fourclaw", "pinchedin", "clawtasks", "clawnews", "rustchain"]
+_ALL_TRANSPORTS = ["udp", "webhook", "telegram", "discord", "bottube", "moltbook", "clawcities", "clawsta", "fourclaw", "pinchedin", "clawtasks", "clawnews", "rustchain"]
 _TOPIC_SUGGESTIONS = [
     "ai", "blockchain", "gaming", "vintage-hardware", "music",
     "art", "science", "finance", "devtools", "security",
@@ -1139,6 +1139,71 @@ def cmd_clawnews_search(args: argparse.Namespace) -> int:
 
 # ── Discord ──
 
+
+def _telegram_client(cfg: Dict[str, Any], bot_token: Optional[str] = None) -> Any:
+    from .transports.telegram import TelegramClient
+    token = bot_token or _cfg_get(cfg, "telegram", "bot_token", default="")
+    if not token:
+        logger.error("Missing telegram.bot_token in config or --bot-token.")
+        sys.exit(1)
+    timeout_s = int(_cfg_get(cfg, "telegram", "timeout_s", default=20) or 20)
+    return TelegramClient(bot_token=token, timeout_s=timeout_s)
+
+def cmd_telegram_send(args: argparse.Namespace) -> int:
+    cfg = _load_config(args.config)
+    setup_logging(args.verbose)
+    from .transports.telegram import TelegramClient
+
+    extra, links = _parse_extra_and_links(args)
+    kind = getattr(args, "kind", "hello")
+    identity, _ = _ensure_identity(cfg, args)
+
+    env = _build_envelope(cfg, kind, "telegram:webhook", links, extra, identity=identity)
+
+    token = args.bot_token or _cfg_get(cfg, "telegram", "bot_token", default="")
+    if not token:
+        logger.error("Missing bot_token.")
+        return 1
+
+    client = TelegramClient(bot_token=token)
+    try:
+        res = client.send_message(args.chat_id, args.text, envelope=env)
+        if args.json:
+            print(json.dumps(res))
+        else:
+            print("Telegram message sent successfully.")
+            return 0
+    except Exception as e:
+        logger.error(f"Failed to send: {e}")
+        return 1
+    return 0
+
+def cmd_telegram_listen(args: argparse.Namespace) -> int:
+    cfg = _load_config(args.config)
+    setup_logging(args.verbose)
+    from .transports.telegram import TelegramListener
+
+    token = args.bot_token or _cfg_get(cfg, "telegram", "bot_token", default="")
+    if not token:
+        logger.error("Missing bot_token.")
+        return 1
+
+    listener = TelegramListener(bot_token=token)
+
+    def on_env(env_obj):
+        if args.json:
+            print(json.dumps(env_obj))
+        else:
+            chat = env_obj.get("chat_id")
+            txt = env_obj.get("text")
+            print(f"[Telegram] {chat}: {txt}")
+
+    try:
+        listener.run_sync(on_env)
+    except KeyboardInterrupt:
+        print("\nExiting Telegram listener.")
+    return 0
+
 def _discord_client(cfg=None, webhook_url: Optional[str] = None) -> DiscordClient:
     cfg = cfg or load_config()
     timeout_s = int(_cfg_get(cfg, "discord", "timeout_s", default=20) or 20)
@@ -4934,6 +4999,19 @@ def add_ping_opts(pp: argparse.ArgumentParser) -> None:
     sp.set_defaults(func=cmd_webhook_send)
 
     # Discord
+    tg = sub.add_parser("telegram", help="Telegram bot transport")
+    tg_sub = tg.add_subparsers(dest="tcmd", required=True)
+
+    sp_send = tg_sub.add_parser("send", help="Send message to Telegram")
+    sp_send.add_argument("--bot-token", default=None, help="Telegram bot token")
+    sp_send.add_argument("--chat-id", required=True, help="Telegram chat ID")
+    sp_send.add_argument("--text", required=True, help="Message text")
+    sp_send.add_argument("--kind", default="hello", help="Envelope kind")
+    sp_send.add_argument("--link", action="append", default=[], help="Attach a link")
+
+    sp_listen = tg_sub.add_parser("listen", help="Listen for Telegram webhook updates")
+    sp_listen.add_argument("--bot-token", default=None, help="Telegram bot token")
+
     dc = sub.add_parser("discord", help="Discord webhook transport")
     dc_sub = dc.add_subparsers(dest="dcmd", required=True)
 

beacon_skill/transports/__init__.py

@@ -1,4 +1,6 @@
 __all__ = [
+    "TelegramClient",
+    "TelegramListener",
     "AgentMatrixTransport",
     "BoTTubeClient",
     "ClawCitiesClient",
@@ -34,3 +36,4 @@
 from .udp import udp_listen, udp_send
 from .conway import ConwayClient
 from .webhook import WebhookServer, webhook_send
+from .telegram import TelegramClient, TelegramListener

beacon_skill/transports/telegram.py

@@ -0,0 +1,75 @@
+"""Telegram transport for Beacon."""
+
+import logging
+import requests
+import time
+from typing import Dict, Any, List
+
+logger = logging.getLogger(__name__)
+
+class TelegramError(RuntimeError):
+    pass
+
+class TelegramClient:
+    def __init__(self, bot_token: str, timeout_s: int = 20):
+        self.bot_token = bot_token
+        self.timeout_s = timeout_s
+        self.session = requests.Session()
+        self.base_url = f"https://api.telegram.org/bot{bot_token}"
+
+    def send_message(self, chat_id: str, text: str, envelope: Dict[str, Any] = None) -> Dict[str, Any]:
+        url = f"{self.base_url}/sendMessage"
+
+        message_text = text
+        if envelope:
+            message_text += f"\n\n[Beacon]: {envelope.get('id', 'N/A')} ({envelope.get('kind', 'N/A')})"
+
+        payload = {
+            "chat_id": chat_id,
+            "text": message_text
+        }
+
+        resp = self.session.post(url, json=payload, timeout=self.timeout_s)
+        if resp.status_code != 200:
+            raise TelegramError(f"Failed to send to Telegram: {resp.text}")
+        return resp.json()
+
+class TelegramListener:
+    def __init__(self, bot_token: str, timeout_s: int = 20):
+        self.bot_token = bot_token
+        self.timeout_s = timeout_s
+        self.base_url = f"https://api.telegram.org/bot{bot_token}"
+        self.session = requests.Session()
+
+    def run_sync(self, callback):
+        offset = 0
+        logger.info("Starting Telegram listener...")
+        while True:
+            try:
+                url = f"{self.base_url}/getUpdates"
+                payload = {"offset": offset, "timeout": self.timeout_s}
+                resp = self.session.get(url, params=payload, timeout=self.timeout_s + 5)
+
+                if resp.status_code == 200:
+                    data = resp.json()
+
+                    if not data.get("ok"):
+                        continue
+
+                    for update in data.get("result", []):
+                        offset = update["update_id"] + 1
+                        msg = update.get("message")
+                        if msg and "text" in msg:
+                            env = {
+                                "platform": "telegram",
+                                "chat_id": str(msg["chat"]["id"]),
+                                "text": msg["text"],
+                                "raw": update
+                            }
+                            callback(env)
+                else:
+                    logger.error(f"Telegram offset {offset} failed: {resp.status_code}")
+                    time.sleep(2)
+            except Exception as e:
+                logger.error(f"Telegram polling error: {e}")
+                time.sleep(5)