pythonclaw 0.5.0__py3-none-any.whl → 0.6.1__py3-none-any.whl

pythonclaw/channels/discord_bot.py

@@ -1,7 +1,7 @@
 """
 Discord channel for PythonClaw.
 
-Session IDs: "discord:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
+Session IDs: "discord:dm:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
 
 Commands
 --------
@@ -9,21 +9,29 @@ Commands
   !status         — show session info
   !compact [hint] — compact conversation history
   <text>          — forwarded to Agent.chat(), reply sent back
+  <image>         — image attachments sent to LLM for analysis
 
 The bot responds to:
   - Direct messages (always)
-  - Channel mentions (@bot message) in guilds
-  - Optionally all messages in whitelisted channels
+  - Channel mentions (@bot message) in guilds (when requireMention=true)
+  - All messages in whitelisted channels (when requireMention=false)
 
 Access control
 --------------
 Set DISCORD_ALLOWED_USERS to a comma-separated list of Discord user IDs.
 Set DISCORD_ALLOWED_CHANNELS to restrict which guild channels the bot listens in.
 Leave empty to allow all.
+
+Group behaviour
+---------------
+Set ``channels.discord.requireMention`` to ``true`` to require @bot mention
+in guild channels. Default is ``false`` (respond when mentioned OR in
+whitelisted channels).
 """
 
 from __future__ import annotations
 
+import base64
 import logging
 from typing import TYPE_CHECKING
 
@@ -52,11 +60,13 @@ class DiscordBot:
         token: str,
         allowed_users: list[int] | None = None,
         allowed_channels: list[int] | None = None,
+        require_mention: bool = False,
     ) -> None:
         self._sm = session_manager
         self._token = token
         self._allowed_users: set[int] = set(allowed_users) if allowed_users else set()
         self._allowed_channels: set[int] = set(allowed_channels) if allowed_channels else set()
+        self._require_mention = require_mention
 
         intents = discord.Intents.default()
         intents.message_content = True
@@ -113,20 +123,27 @@ class DiscordBot:
             is_dm = isinstance(message.channel, discord.DMChannel)
             is_mentioned = client.user in message.mentions if not is_dm else False
 
-            # In guilds, only respond to mentions or whitelisted channels
-            if not is_dm and not is_mentioned and not self._is_allowed_channel(message.channel.id):
-                return
+            if not is_dm:
+                if self._require_mention and not is_mentioned:
+                    return
+                if not self._require_mention and not is_mentioned:
+                    if not self._is_allowed_channel(message.channel.id):
+                        return
 
             if not self._is_allowed_user(message.author.id):
                 await message.reply("Sorry, you are not authorised to use this bot.")
                 return
 
             content = message.content.strip()
-            # Remove bot mention from the beginning
             if is_mentioned and client.user:
                 content = content.replace(f"<@{client.user.id}>", "").strip()
 
-            if not content:
+            has_image = any(
+                a.content_type and a.content_type.startswith("image/")
+                for a in message.attachments
+            )
+
+            if not content and not has_image:
                 return
 
             # Command dispatch
@@ -141,7 +158,35 @@ class DiscordBot:
                 await self._cmd_compact(message, is_dm, hint)
                 return
 
-            await self._handle_chat(message, content, is_dm)
+            chat_input = content or ""
+            if has_image:
+                chat_input = await self._build_image_input(
+                    message, content or "What's in this image?"
+                )
+
+            await self._handle_chat(message, chat_input, is_dm)
+
+    # ── Image handling ────────────────────────────────────────────────────────
+
+    @staticmethod
+    async def _build_image_input(message: discord.Message, caption: str) -> list:
+        """Download image attachments and build multimodal content array."""
+        parts: list[dict] = [{"type": "text", "text": caption}]
+        for att in message.attachments:
+            if att.content_type and att.content_type.startswith("image/"):
+                try:
+                    data = await att.read()
+                    b64 = base64.b64encode(data).decode()
+                    media_type = att.content_type.split(";")[0]
+                    parts.append({
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:{media_type};base64,{b64}",
+                        },
+                    })
+                except Exception:
+                    logger.warning("[Discord] Failed to download attachment %s", att.filename)
+        return parts
 
     # ── Command implementations ───────────────────────────────────────────────
 
@@ -180,12 +225,17 @@ class DiscordBot:
         for chunk in self._split_message(result or "(no result)"):
             await message.reply(chunk)
 
-    async def _handle_chat(self, message: discord.Message, content: str, is_dm: bool) -> None:
+    async def _handle_chat(
+        self,
+        message: discord.Message,
+        content: str | list,
+        is_dm: bool,
+    ) -> None:
         sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
         agent = self._sm.get_or_create(sid)
 
         if self._sm.is_locked(sid):
-            await message.reply("Processing previous message…")
+            await message.reply("Processing previous message\u2026")
 
         async with message.channel.typing():
             try:
@@ -226,11 +276,15 @@ def create_bot(session_manager: "SessionManager") -> "DiscordBot":
     allowed_channels = config.get_int_list(
         "channels", "discord", "allowedChannels", env="DISCORD_ALLOWED_CHANNELS",
     )
+    require_mention = config.get_bool(
+        "channels", "discord", "requireMention", default=False,
+    )
     return DiscordBot(
         session_manager=session_manager,
         token=token,
         allowed_users=allowed_users or None,
         allowed_channels=allowed_channels or None,
+        require_mention=require_mention,
     )
 
 

pythonclaw/channels/telegram_bot.py

@@ -14,17 +14,27 @@ Commands
   /status         — show session info (provider, skills, memory, tokens, compactions)
   /compact [hint] — compact conversation history
   <text>          — forwarded to Agent.chat(), reply sent back
+  <photo>         — image sent to LLM with optional caption
 
 Access control
 --------------
 Set TELEGRAM_ALLOWED_USERS to a comma-separated list of integer Telegram user
 IDs to restrict access.  Leave empty (or unset) to allow all users.
+
+Group behaviour
+---------------
+Set ``channels.telegram.requireMention`` to ``true`` in pythonclaw.json to
+require @bot mention in group chats.  DMs always respond.
 """
 
 from __future__ import annotations
 
 import asyncio
+import base64
 import logging
+import queue as _queue
+import re
+import time
 from typing import TYPE_CHECKING
 
 from telegram import BotCommand, ReactionTypeEmoji, Update
@@ -57,11 +67,14 @@ class TelegramBot:
         session_manager: "SessionManager",
         token: str,
         allowed_users: list[int] | None = None,
+        require_mention: bool = False,
     ) -> None:
         self._sm = session_manager
         self._token = token
         self._allowed_users: set[int] = set(allowed_users) if allowed_users else set()
+        self._require_mention = require_mention
         self._app: Application | None = None
+        self._bot_username: str | None = None
 
     # ── Session ID convention ─────────────────────────────────────────────────
 
@@ -93,6 +106,29 @@ class TelegramBot:
             return False
         return True
 
+    def _is_group(self, update: Update) -> bool:
+        """Return True if the message is from a group/supergroup."""
+        return update.effective_chat.type in ("group", "supergroup")
+
+    def _is_mentioned(self, update: Update) -> bool:
+        """Check if the bot is @mentioned in the message text."""
+        text = update.message.text or update.message.caption or ""
+        if self._bot_username and f"@{self._bot_username}" in text:
+            return True
+        entities = update.message.entities or update.message.caption_entities or []
+        for ent in entities:
+            if ent.type == "mention" and self._bot_username:
+                mention = text[ent.offset:ent.offset + ent.length]
+                if mention.lower() == f"@{self._bot_username.lower()}":
+                    return True
+        return False
+
+    def _strip_mention(self, text: str) -> str:
+        """Remove the @bot mention from message text."""
+        if self._bot_username:
+            text = text.replace(f"@{self._bot_username}", "").strip()
+        return text
+
     # ── Command handlers ──────────────────────────────────────────────────────
 
     async def _cmd_start(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -101,13 +137,14 @@ class TelegramBot:
         sid = self._session_id(update.effective_chat.id)
         self._sm.get_or_create(sid)
         await update.message.reply_text(
-            "👋 Hi! I'm your PythonClaw agent.\n\n"
-            "Just send me a message and I'll do my best to help.\n\n"
+            "\U0001f44b Hi! I'm your PythonClaw agent.\n\n"
+            "Just send me a message and I'll do my best to help.\n"
+            "You can also send photos and I'll analyze them.\n\n"
             "Commands:\n"
-            "  /start          — show this message\n"
-            "  /reset          — start a fresh session\n"
-            "  /status         — show session info\n"
-            "  /compact [hint] — compact conversation history"
+            "  /start          \u2014 show this message\n"
+            "  /reset          \u2014 start a fresh session\n"
+            "  /status         \u2014 show session info\n"
+            "  /compact [hint] \u2014 compact conversation history"
         )
 
     async def _cmd_reset(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -124,7 +161,7 @@ class TelegramBot:
         agent = self._sm.get_or_create(sid)
         from ..core.compaction import estimate_tokens
         await update.message.reply_text(
-            f"📊 Session Status\n"
+            f"\U0001f4ca Session Status\n"
             f"  Session ID   : {sid}\n"
             f"  Provider     : {type(agent.provider).__name__}\n"
             f"  Skills       : {len(agent.loaded_skill_names)} loaded\n"
@@ -141,7 +178,7 @@ class TelegramBot:
         sid = self._session_id(update.effective_chat.id)
         agent = self._sm.get_or_create(sid)
         hint: str | None = " ".join(context.args).strip() or None if context.args else None
-        await update.message.reply_text("⏳ Compacting conversation history...")
+        await update.message.reply_text("\u23f3 Compacting conversation history...")
         try:
             result = agent.compact(instruction=hint)
         except Exception as exc:
@@ -149,50 +186,239 @@ class TelegramBot:
         for chunk in _split_message(result):
             await update.message.reply_text(chunk)
 
-    # ── Message handler ───────────────────────────────────────────────────────
+    # ── Message handler (text + photos) ───────────────────────────────────────
 
     async def _handle_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         if not await self._check_access(update, context):
             return
-        user_text = (update.message.text or "").strip()
-        if not user_text:
+
+        if self._is_group(update) and self._require_mention:
+            if not self._is_mentioned(update):
+                return
+
+        user_text = (update.message.text or update.message.caption or "").strip()
+        user_text = self._strip_mention(user_text)
+
+        has_photo = bool(update.message.photo)
+
+        if not user_text and not has_photo:
             return
+
         sid = self._session_id(update.effective_chat.id)
         agent = self._sm.get_or_create(sid)
 
         if self._sm.is_locked(sid):
-            await update.message.reply_text("⏳ Processing previous message…")
+            await update.message.reply_text("\u23f3 Processing previous message\u2026")
 
-        # React to the message so the user knows the bot saw it
         try:
-            await update.message.set_reaction([ReactionTypeEmoji("👀")])
+            await update.message.set_reaction([ReactionTypeEmoji("\U0001f440")])
         except Exception:
-            pass  # reaction API may fail on older bot API or in groups
+            pass
+
+        chat_input = user_text or ""
+        if has_photo:
+            chat_input = await self._build_image_input(
+                update, user_text or "What's in this image?"
+            )
+
+        token_queue: _queue.Queue[str] = _queue.Queue()
 
-        # Keep "typing…" visible for the entire duration of processing.
-        # Telegram's typing indicator expires after ~5 s, so we resend it
-        # on a loop until the agent finishes.
         typing_task = asyncio.create_task(
             self._keep_typing(update.message.chat_id)
         )
         try:
             async with self._sm.acquire(sid):
                 loop = asyncio.get_event_loop()
-                response = await loop.run_in_executor(None, agent.chat, user_text)
+                future = loop.run_in_executor(
+                    None, agent.chat_stream, chat_input, token_queue.put,
+                )
+                await self._flush_stream(update, token_queue, future)
         except Exception as exc:
-            logger.exception("[Telegram] Agent.chat() raised an exception")
-            response = f"Sorry, something went wrong: {exc}"
+            logger.exception("[Telegram] Agent error")
+            await update.message.reply_text(f"Sorry, something went wrong: {exc}")
         finally:
             typing_task.cancel()
 
-        # Clear the "seen" reaction once we reply
         try:
             await update.message.set_reaction([])
         except Exception:
             pass
 
-        for chunk in _split_message(response or "(no response)"):
-            await update.message.reply_text(chunk)
+    # Max wall-clock time for a single agent invocation (seconds).
+    _AGENT_TIMEOUT = 180
+
+    async def _flush_stream(
+        self,
+        update: Update,
+        token_queue: "_queue.Queue[str]",
+        future: "asyncio.Future[str]",
+    ) -> None:
+        """Progressively stream tokens to Telegram via edit-in-place.
+
+        Uses send-then-edit (like OpenClaw): one live message that gets
+        updated as tokens arrive (~1.5 s throttle).  Tool-call markers
+        produce a short status line and start a fresh message.
+
+        Safeguards against hangs:
+        - **Heartbeat**: if no tokens arrive for 15 s, sends a "still
+          working" notification so the user knows the bot is alive.
+        - **Overall timeout**: after ``_AGENT_TIMEOUT`` seconds the
+          future is abandoned and a timeout message is sent.
+        """
+        buf: list[str] = []
+        live_msg = None
+        live_text = ""
+        sent_any = False
+        THROTTLE = 1.5
+        HEARTBEAT_INTERVAL = 15.0
+        last_edit = time.monotonic()
+        last_token_time = time.monotonic()
+        start_time = time.monotonic()
+        heartbeat_sent = False
+        _MARKER = re.compile(r'`\[calling:\s*([^\]]+)\]`')
+
+        while not future.done():
+            # ── Overall timeout guard ─────────────────────────────────
+            if (time.monotonic() - start_time) > self._AGENT_TIMEOUT:
+                logger.warning(
+                    "[Telegram] Agent timeout after %ds", self._AGENT_TIMEOUT,
+                )
+                try:
+                    await update.message.reply_text(
+                        "\u23f0 The operation timed out. "
+                        "Please try a simpler request."
+                    )
+                except Exception:
+                    pass
+                return
+
+            # ── Drain token queue ─────────────────────────────────────
+            drained = False
+            while True:
+                try:
+                    buf.append(token_queue.get_nowait())
+                    drained = True
+                    last_token_time = time.monotonic()
+                    heartbeat_sent = False
+                except _queue.Empty:
+                    break
+
+            # ── Heartbeat: notify user during long silences ───────────
+            if (
+                not drained
+                and not heartbeat_sent
+                and (time.monotonic() - last_token_time) > HEARTBEAT_INTERVAL
+            ):
+                try:
+                    await update.message.reply_text(
+                        "\u23f3 Still working\u2026"
+                    )
+                except Exception:
+                    pass
+                heartbeat_sent = True
+
+            if not drained:
+                await asyncio.sleep(0.3)
+                continue
+
+            raw = "".join(buf)
+            now = time.monotonic()
+
+            # ── Tool-call marker → status line + new message ──────────
+            marker = _MARKER.search(raw)
+            if marker:
+                before = _clean_response(raw[:marker.start()])
+                if before and before != live_text:
+                    try:
+                        if live_msg:
+                            await live_msg.edit_text(before[:4096])
+                        else:
+                            await update.message.reply_text(before[:4096])
+                    except Exception:
+                        pass
+                live_msg = None
+                live_text = ""
+                tools = marker.group(1)
+                try:
+                    await update.message.reply_text(
+                        f"\U0001f527 {tools}\u2026"
+                    )
+                except Exception:
+                    pass
+                sent_any = True
+                buf = [raw[marker.end():].lstrip()]
+                last_edit = now
+                continue
+
+            # ── Regular text → edit-in-place ──────────────────────────
+            text = _clean_response(raw)
+            if text and text != live_text and (now - last_edit) >= THROTTLE:
+                try:
+                    if live_msg is None:
+                        live_msg = await update.message.reply_text(
+                            text[:4096],
+                        )
+                        live_text = text[:4096]
+                    elif len(text) <= 4096:
+                        await live_msg.edit_text(text)
+                        live_text = text
+                    else:
+                        await live_msg.edit_text(text[:4096])
+                        live_msg = None
+                        live_text = ""
+                        buf = [text[4096:]]
+                    sent_any = True
+                except Exception:
+                    pass
+                last_edit = now
+
+            await asyncio.sleep(0.3)
+
+        # ── Final drain ───────────────────────────────────────────────
+        response = future.result()
+        while True:
+            try:
+                buf.append(token_queue.get_nowait())
+            except _queue.Empty:
+                break
+
+        remaining = _clean_response("".join(buf).strip())
+        if remaining and remaining != live_text:
+            try:
+                if live_msg and len(remaining) <= 4096:
+                    await live_msg.edit_text(remaining)
+                elif live_msg:
+                    await live_msg.edit_text(remaining[:4096])
+                    for chunk in _split_message(remaining[4096:]):
+                        await update.message.reply_text(chunk)
+                else:
+                    for chunk in _split_message(remaining):
+                        await update.message.reply_text(chunk)
+                sent_any = True
+            except Exception:
+                pass
+
+        if not sent_any:
+            text = _clean_response(response or "(no response)")
+            for chunk in _split_message(text):
+                await update.message.reply_text(chunk)
+
+    async def _build_image_input(self, update: Update, caption: str) -> list:
+        """Download photo and build a multimodal content array."""
+        photo = update.message.photo[-1]  # highest resolution
+        file = await photo.get_file()
+        data = await file.download_as_bytearray()
+        b64 = base64.b64encode(bytes(data)).decode()
+
+        return [
+            {"type": "text", "text": caption},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{b64}",
+                },
+            },
+        ]
 
     async def _keep_typing(self, chat_id: int) -> None:
         """Re-send the 'typing' chat action every 4 s until cancelled."""
@@ -220,7 +446,10 @@ class TelegramBot:
         app.add_handler(CommandHandler("reset", self._cmd_reset))
         app.add_handler(CommandHandler("status", self._cmd_status))
         app.add_handler(CommandHandler("compact", self._cmd_compact))
-        app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self._handle_message))
+        app.add_handler(MessageHandler(
+            (filters.TEXT | filters.PHOTO) & ~filters.COMMAND,
+            self._handle_message,
+        ))
         self._app = app
         return app
 
@@ -228,7 +457,12 @@ class TelegramBot:
         """Register slash-commands with Telegram so they appear in the menu."""
         try:
             await self._app.bot.set_my_commands(self._BOT_COMMANDS)
-            logger.info("[Telegram] Registered %d bot commands", len(self._BOT_COMMANDS))
+            me = await self._app.bot.get_me()
+            self._bot_username = me.username
+            logger.info(
+                "[Telegram] Registered %d bot commands, username=@%s",
+                len(self._BOT_COMMANDS), self._bot_username,
+            )
         except Exception:
             logger.warning("[Telegram] Failed to register bot commands", exc_info=True)
 
@@ -259,14 +493,44 @@ class TelegramBot:
 
 # ── Utility ───────────────────────────────────────────────────────────────────
 
+_LEAKED_TOOL_RE = re.compile(
+    r'<\s*\|?\s*(?:DSML|antml)\s*\|\s*function_calls[^>]*>'
+    r'[\s\S]*?'
+    r'<\s*/\s*\|?\s*(?:DSML|antml)\s*\|\s*function_calls\s*>',
+    re.IGNORECASE,
+)
+
+
+def _clean_response(text: str) -> str:
+    """Strip leaked tool-call XML/DSML markup from LLM output."""
+    text = _LEAKED_TOOL_RE.sub('', text)
+    text = re.sub(r'\n{3,}', '\n\n', text)
+    return text.strip()
+
+
 def _split_message(text: str, limit: int = 4096) -> list[str]:
-    """Split a long string into chunks that fit within Telegram's message limit."""
+    """Split text into chunks respecting natural boundaries.
+
+    Tries paragraph breaks first, then newlines, then word boundaries,
+    and only falls back to a hard character cut as a last resort.
+    """
     if len(text) <= limit:
         return [text]
-    chunks = []
+    chunks: list[str] = []
+    min_break = limit // 3
     while text:
-        chunks.append(text[:limit])
-        text = text[limit:]
+        if len(text) <= limit:
+            chunks.append(text)
+            break
+        split_at = text.rfind('\n\n', min_break, limit)
+        if split_at < min_break:
+            split_at = text.rfind('\n', min_break, limit)
+        if split_at < min_break:
+            split_at = text.rfind(' ', min_break, limit)
+        if split_at < min_break:
+            split_at = limit
+        chunks.append(text[:split_at].rstrip())
+        text = text[split_at:].lstrip()
     return chunks
 
 
@@ -280,10 +544,14 @@ def create_bot(session_manager: "SessionManager") -> TelegramBot:
     allowed_users = config.get_int_list(
         "channels", "telegram", "allowedUsers", env="TELEGRAM_ALLOWED_USERS",
     )
+    require_mention = config.get_bool(
+        "channels", "telegram", "requireMention", default=False,
+    )
     return TelegramBot(
         session_manager=session_manager,
         token=token,
         allowed_users=allowed_users or None,
+        require_mention=require_mention,
     )