opc-agent 4.0.11 → 4.0.12

package/dist/channels/telegram.d.ts

@@ -1,33 +1,55 @@
 import type { Message } from '../core/types';
 import { BaseChannel } from './index';
 /**
- * Telegram channel — supports both long-polling and webhook modes.
+ * Telegram channel — production-quality Telegram bot integration.
  *
- * Config:
- *   token: bot token (or TELEGRAM_BOT_TOKEN env var)
- *   mode: 'polling' | 'webhook' (default: 'polling')
- *   webhookUrl: required for webhook mode
- *   port: webhook server port (default: 3001)
- *
- * Polling mode requires no public URL — ideal for dev/local.
- * Webhook mode is more efficient for production.
+ * Features (aligned with OpenClaw):
+ * - Live stream preview (sendMessage + editMessageText)
+ * - Ack reaction on message receipt
+ * - Typing indicator throughout processing
+ * - HTML parse mode with Markdown fallback
+ * - Smart text chunking (paragraph-aware)
+ * - /start, /help, /status commands
+ * - Photo/document caption handling
+ * - Callback query (inline button) support
+ * - Reply threading
+ * - Error recovery with plain-text fallback
+ * - Forum topic support
+ * - Group mention filtering
  */
 export interface TelegramChannelConfig {
     token?: string;
     mode?: 'polling' | 'webhook';
     webhookUrl?: string;
+    webhookSecret?: string;
     port?: number;
+    streaming?: boolean | 'off' | 'partial';
+    ackReaction?: string;
+    linkPreview?: boolean;
+    textChunkLimit?: number;
+    requireMention?: boolean;
+    botUsername?: string;
 }
 export declare class TelegramChannel extends BaseChannel {
     readonly type = "telegram";
     private token;
     private mode;
     private webhookUrl?;
+    private webhookSecret?;
     private port;
+    private botUsername;
+    private botInfo;
+    private streamingEnabled;
+    private ackReaction;
+    private linkPreview;
+    private textChunkLimit;
+    private requireMention;
     private offset;
     private polling;
     private server;
+    private streamHandler?;
     constructor(config?: TelegramChannelConfig);
+    setStreamHandler(handler: (msg: Message) => AsyncIterable<string>): void;
     start(): Promise<void>;
     stop(): Promise<void>;
     private startPolling;
@@ -36,12 +58,27 @@ export declare class TelegramChannel extends BaseChannel {
     private startWebhook;
     private stopWebhook;
     private processUpdate;
+    private handleCommand;
+    private handleCallbackQuery;
     private streamResponse;
-    private streamHandler?;
-    setStreamHandler(handler: (msg: Message) => AsyncIterable<string>): void;
-    sendMarkdown(chatId: number | string, text: string, replyTo?: number): Promise<any>;
+    sendFormattedMessage(chatId: number | string, text: string, replyTo?: number, threadId?: number): Promise<any>;
     sendMessage(chatId: number | string, text: string): Promise<void>;
+    private setReaction;
+    private sendTyping;
+    private isGroupChat;
+    private isMentioned;
+    private getSessionId;
+    private escapeHtml;
+    /**
+     * Convert basic Markdown to Telegram-safe HTML.
+     * Handles: bold, italic, code, code blocks, links.
+     */
+    private markdownToHtml;
+    /**
+     * Smart text splitting — prefer paragraph boundaries (blank lines) before hard length split.
+     * Aligned with OpenClaw's chunkMode="newline" behavior.
+     */
+    private smartSplit;
     private apiCall;
-    private splitText;
 }
 //# sourceMappingURL=telegram.d.ts.map

package/dist/channels/telegram.js

@@ -40,24 +40,57 @@ class TelegramChannel extends index_1.BaseChannel {
     token;
     mode;
     webhookUrl;
+    webhookSecret;
     port;
+    botUsername = '';
+    botInfo = null;
+    // Config
+    streamingEnabled;
+    ackReaction;
+    linkPreview;
+    textChunkLimit;
+    requireMention;
     // Polling state
     offset = 0;
     polling = false;
     // Webhook state
     server = null;
+    // Stream handler — set by runtime when provider supports streaming
+    streamHandler;
     constructor(config = {}) {
         super();
         this.token = config.token ?? process.env.TELEGRAM_BOT_TOKEN ?? '';
         this.mode = config.mode ?? 'polling';
         this.webhookUrl = config.webhookUrl;
+        this.webhookSecret = config.webhookSecret;
         this.port = config.port ?? 3001;
+        // Feature config
+        this.streamingEnabled = config.streaming !== false && config.streaming !== 'off';
+        this.ackReaction = config.ackReaction ?? '👀';
+        this.linkPreview = config.linkPreview ?? true;
+        this.textChunkLimit = config.textChunkLimit ?? 4000;
+        this.requireMention = config.requireMention ?? false;
+        if (config.botUsername)
+            this.botUsername = config.botUsername.replace('@', '').toLowerCase();
+    }
+    setStreamHandler(handler) {
+        this.streamHandler = handler;
     }
     async start() {
         if (!this.token) {
             console.warn('[TelegramChannel] No bot token provided. Set TELEGRAM_BOT_TOKEN or pass token in config.');
             return;
         }
+        // Fetch bot info for username detection
+        try {
+            const me = await this.apiCall('getMe');
+            if (me?.result) {
+                this.botInfo = me.result;
+                this.botUsername = (me.result.username ?? '').toLowerCase();
+                console.log(`[TelegramChannel] Bot: @${this.botUsername}`);
+            }
+        }
+        catch { }
         if (this.mode === 'webhook') {
             await this.startWebhook();
         }
@@ -75,7 +108,6 @@ class TelegramChannel extends index_1.BaseChannel {
     }
     // ─── Polling Mode ────────────────────────────────────────
     async startPolling() {
-        // Delete any existing webhook so polling works
         await this.apiCall('deleteWebhook');
         console.log(`[TelegramChannel] Started long-polling mode`);
         this.polling = true;
@@ -86,12 +118,14 @@ class TelegramChannel extends index_1.BaseChannel {
             try {
                 const updates = await this.getUpdates();
                 for (const update of updates) {
-                    await this.processUpdate(update);
+                    // Don't await — process concurrently for better responsiveness
+                    this.processUpdate(update).catch((err) => {
+                        console.error('[TelegramChannel] Update processing error:', err);
+                    });
                 }
             }
             catch (err) {
                 console.error('[TelegramChannel] Polling error:', err);
-                // Back off on error
                 if (this.polling) {
                     await new Promise((r) => setTimeout(r, 5000));
                 }
@@ -99,9 +133,9 @@ class TelegramChannel extends index_1.BaseChannel {
         }
     }
     async getUpdates() {
-        const url = `https://api.telegram.org/bot${this.token}/getUpdates?offset=${this.offset}&timeout=30&allowed_updates=["message"]`;
+        const url = `https://api.telegram.org/bot${this.token}/getUpdates?offset=${this.offset}&timeout=30&allowed_updates=${encodeURIComponent('["message","callback_query","message_reaction"]')}`;
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 40000); // 30s long-poll + 10s buffer
+        const timeout = setTimeout(() => controller.abort(), 40000);
         try {
             const res = await fetch(url, { signal: controller.signal });
             const data = (await res.json());
@@ -117,14 +151,28 @@ class TelegramChannel extends index_1.BaseChannel {
     // ─── Webhook Mode ────────────────────────────────────────
     async startWebhook() {
         if (this.webhookUrl) {
-            await this.apiCall('setWebhook', { url: `${this.webhookUrl}/webhook/${this.token}` });
+            const params = {
+                url: `${this.webhookUrl}/webhook/${this.token}`,
+                allowed_updates: ['message', 'callback_query', 'message_reaction'],
+            };
+            if (this.webhookSecret)
+                params.secret_token = this.webhookSecret;
+            await this.apiCall('setWebhook', params);
         }
         const express = (await Promise.resolve().then(() => __importStar(require('express')))).default;
         const app = express();
         app.use(express.json());
         app.post(`/webhook/${this.token}`, async (req, res) => {
+            // Verify secret if configured
+            if (this.webhookSecret && req.headers['x-telegram-bot-api-secret-token'] !== this.webhookSecret) {
+                res.status(403).json({ error: 'Forbidden' });
+                return;
+            }
             try {
-                await this.processUpdate(req.body);
+                // Don't await — respond quickly, process in background
+                this.processUpdate(req.body).catch((err) => {
+                    console.error('[TelegramChannel] Webhook processing error:', err);
+                });
                 res.json({ ok: true });
             }
             catch (err) {
@@ -133,7 +181,7 @@ class TelegramChannel extends index_1.BaseChannel {
             }
         });
         app.get('/health', (_req, res) => {
-            res.json({ status: 'ok', channel: 'telegram', mode: 'webhook' });
+            res.json({ status: 'ok', channel: 'telegram', mode: 'webhook', bot: this.botUsername });
         });
         return new Promise((resolve) => {
             this.server = app.listen(this.port, () => {
@@ -149,159 +197,337 @@ class TelegramChannel extends index_1.BaseChannel {
             this.server.close((err) => (err ? reject(err) : resolve()));
         });
     }
-    // ─── Shared ──────────────────────────────────────────────
+    // ─── Update Processing ──────────────────────────────────
     async processUpdate(update) {
+        // Handle callback queries (inline buttons)
+        if (update.callback_query) {
+            await this.handleCallbackQuery(update.callback_query);
+            return;
+        }
         const message = update.message || update.edited_message;
         if (!message || !this.handler)
             return;
-        // Handle /start command
-        if (message.text === '/start') {
-            await this.sendMarkdown(message.chat.id, '👋 Hello! I\'m ready to help. Send me a message to get started.');
-            return;
+        // Handle commands
+        if (message.text?.startsWith('/')) {
+            const handled = await this.handleCommand(message);
+            if (handled)
+                return;
         }
-        // Handle text, photo captions, document captions
+        // Extract text from various message types
         const text = message.text || message.caption;
         if (!text)
             return;
+        // Group mention filtering
+        if (this.isGroupChat(message) && this.requireMention) {
+            if (!this.isMentioned(text))
+                return;
+        }
+        // Build message object
         const msg = {
             id: `tg_${message.message_id}`,
             role: 'user',
             content: text,
             timestamp: message.date * 1000,
             metadata: {
-                sessionId: `tg_${message.chat.id}`,
+                sessionId: this.getSessionId(message),
                 chatId: message.chat.id,
                 userId: message.from?.id,
                 username: message.from?.username,
                 firstName: message.from?.first_name,
+                lastName: message.from?.last_name,
                 platform: 'telegram',
                 chatType: message.chat.type,
+                messageThreadId: message.message_thread_id,
                 replyToMessageId: message.message_id,
             },
         };
-        // Show typing indicator
-        await this.apiCall('sendChatAction', { chat_id: message.chat.id, action: 'typing' });
+        // Ack reaction — immediate visual feedback
+        if (this.ackReaction) {
+            this.setReaction(message.chat.id, message.message_id, this.ackReaction).catch(() => { });
+        }
+        // Typing indicator
+        const threadId = message.message_thread_id;
+        await this.sendTyping(message.chat.id, threadId);
         const typingInterval = setInterval(() => {
-            this.apiCall('sendChatAction', { chat_id: message.chat.id, action: 'typing' }).catch(() => { });
+            this.sendTyping(message.chat.id, threadId).catch(() => { });
         }, 4000);
         try {
-            // Try streaming if provider supports it
-            if (this.streamHandler) {
-                await this.streamResponse(message.chat.id, msg, message.message_id);
+            if (this.streamingEnabled && this.streamHandler) {
+                await this.streamResponse(message.chat.id, msg, message.message_id, threadId);
             }
             else {
                 const response = await this.handler(msg);
-                await this.sendMarkdown(message.chat.id, response.content, message.message_id);
+                await this.sendFormattedMessage(message.chat.id, response.content, message.message_id, threadId);
+            }
+            // Remove ack reaction after successful response
+            if (this.ackReaction) {
+                this.setReaction(message.chat.id, message.message_id, '').catch(() => { });
             }
         }
         catch (err) {
             console.error('[TelegramChannel] Error processing message:', err);
-            await this.sendMarkdown(message.chat.id, '⚠️ Sorry, something went wrong. Please try again.');
+            await this.sendFormattedMessage(message.chat.id, '⚠️ Sorry, something went wrong. Please try again.', message.message_id, threadId);
         }
         finally {
             clearInterval(typingInterval);
         }
     }
-    async streamResponse(chatId, msg, replyTo) {
+    // ─── Commands ───────────────────────────────────────────
+    async handleCommand(message) {
+        const text = message.text ?? '';
+        const command = text.split(' ')[0].split('@')[0].toLowerCase(); // Strip @botname
+        switch (command) {
+            case '/start':
+                await this.sendFormattedMessage(message.chat.id, `👋 <b>Hello${message.from?.first_name ? ' ' + this.escapeHtml(message.from.first_name) : ''}!</b>\n\nI'm ready to help. Send me a message to get started.\n\nCommands:\n/help — Show available commands\n/status — Check bot status`, undefined, message.message_thread_id);
+                return true;
+            case '/help':
+                await this.sendFormattedMessage(message.chat.id, `📖 <b>Available Commands</b>\n\n/start — Start conversation\n/help — Show this help\n/status — Bot status\n\nJust send a message and I'll respond!`, undefined, message.message_thread_id);
+                return true;
+            case '/status':
+                const uptime = process.uptime();
+                const hours = Math.floor(uptime / 3600);
+                const mins = Math.floor((uptime % 3600) / 60);
+                await this.sendFormattedMessage(message.chat.id, `🟢 <b>Bot Status</b>\n\n⏱ Uptime: ${hours}h ${mins}m\n🤖 Bot: @${this.botUsername}\n💬 Mode: ${this.mode}\n📡 Streaming: ${this.streamingEnabled ? 'on' : 'off'}`, undefined, message.message_thread_id);
+                return true;
+            default:
+                return false; // Not a recognized command, let it flow through as normal message
+        }
+    }
+    // ─── Callback Queries (Inline Buttons) ──────────────────
+    async handleCallbackQuery(query) {
+        // Answer the callback to remove loading state
+        await this.apiCall('answerCallbackQuery', { callback_query_id: query.id });
+        if (!this.handler || !query.data)
+            return;
+        const msg = {
+            id: `tg_cb_${query.id}`,
+            role: 'user',
+            content: `callback_data: ${query.data}`,
+            timestamp: Date.now(),
+            metadata: {
+                sessionId: `tg_${query.message?.chat?.id ?? query.from.id}`,
+                chatId: query.message?.chat?.id ?? query.from.id,
+                userId: query.from.id,
+                username: query.from.username,
+                firstName: query.from.first_name,
+                platform: 'telegram',
+                chatType: query.message?.chat?.type ?? 'private',
+                isCallback: true,
+            },
+        };
+        try {
+            const response = await this.handler(msg);
+            const chatId = query.message?.chat?.id ?? query.from.id;
+            await this.sendFormattedMessage(chatId, response.content);
+        }
+        catch (err) {
+            console.error('[TelegramChannel] Callback query error:', err);
+        }
+    }
+    // ─── Streaming ──────────────────────────────────────────
+    async streamResponse(chatId, msg, replyTo, threadId) {
         if (!this.streamHandler)
             return;
         let sentMessageId = null;
         let fullText = '';
         let lastEditTime = 0;
-        const EDIT_INTERVAL = 1000; // Edit at most once per second
-        let pendingEdit = false;
-        const doEdit = async () => {
+        const EDIT_INTERVAL = 800; // Edit slightly faster than before
+        const MIN_FIRST_SEND = 20; // Min chars before first send (avoid tiny initial message)
+        const doEdit = async (final = false) => {
             if (!sentMessageId || !fullText)
                 return;
-            pendingEdit = false;
+            const displayText = final ? fullText : fullText + ' ▍'; // Cursor indicator while streaming
             try {
                 await this.apiCall('editMessageText', {
                     chat_id: chatId,
                     message_id: sentMessageId,
-                    text: fullText,
-                    parse_mode: 'Markdown',
+                    text: displayText,
+                    parse_mode: 'HTML',
+                    disable_web_page_preview: !this.linkPreview,
                 });
                 lastEditTime = Date.now();
             }
-            catch (err) {
-                // If Markdown fails, try plain text
-                if (err?.message?.includes('parse') || err?.message?.includes('entities')) {
-                    try {
-                        await this.apiCall('editMessageText', {
-                            chat_id: chatId,
-                            message_id: sentMessageId,
-                            text: fullText,
-                        });
-                    }
-                    catch { }
+            catch {
+                // HTML parse failed, try plain text
+                try {
+                    await this.apiCall('editMessageText', {
+                        chat_id: chatId,
+                        message_id: sentMessageId,
+                        text: displayText,
+                    });
+                    lastEditTime = Date.now();
                 }
+                catch { }
             }
         };
         try {
             for await (const chunk of this.streamHandler(msg)) {
                 fullText += chunk;
-                if (!sentMessageId) {
-                    // Send first message
-                    const result = await this.sendMarkdown(chatId, fullText, replyTo);
+                if (!sentMessageId && fullText.length >= MIN_FIRST_SEND) {
+                    const result = await this.sendFormattedMessage(chatId, fullText + ' ▍', replyTo, threadId);
                     sentMessageId = result?.message_id;
                     lastEditTime = Date.now();
                 }
-                else {
+                else if (sentMessageId) {
                     const now = Date.now();
                     if (now - lastEditTime >= EDIT_INTERVAL) {
                         await doEdit();
                     }
-                    else if (!pendingEdit) {
-                        pendingEdit = true;
-                    }
                 }
             }
-            // Final edit with complete text
+            // Final edit — remove cursor, clean formatting
             if (sentMessageId && fullText) {
-                await doEdit();
+                await doEdit(true);
+            }
+            else if (!sentMessageId && fullText) {
+                // Never sent first message (very short response)
+                await this.sendFormattedMessage(chatId, fullText, replyTo, threadId);
             }
         }
         catch (err) {
-            // If streaming fails, send what we have
             if (!sentMessageId && fullText) {
-                await this.sendMarkdown(chatId, fullText, replyTo);
+                await this.sendFormattedMessage(chatId, fullText, replyTo, threadId);
             }
             throw err;
         }
     }
-    // Stream handler — set by runtime when provider supports streaming
-    streamHandler;
-    setStreamHandler(handler) {
-        this.streamHandler = handler;
-    }
-    async sendMarkdown(chatId, text, replyTo) {
-        const chunks = this.splitText(text, 4096);
+    // ─── Message Sending ───────────────────────────────────
+    async sendFormattedMessage(chatId, text, replyTo, threadId) {
+        const chunks = this.smartSplit(text, this.textChunkLimit);
         let lastResult = null;
         for (const chunk of chunks) {
+            const baseParams = {
+                chat_id: chatId,
+                disable_web_page_preview: !this.linkPreview,
+                ...(replyTo ? { reply_to_message_id: replyTo } : {}),
+                ...(threadId ? { message_thread_id: threadId } : {}),
+            };
+            // Try HTML first (richer formatting)
             try {
+                const htmlText = this.markdownToHtml(chunk);
                 lastResult = await this.apiCall('sendMessage', {
-                    chat_id: chatId,
-                    text: chunk,
-                    parse_mode: 'Markdown',
-                    ...(replyTo ? { reply_to_message_id: replyTo } : {}),
+                    ...baseParams,
+                    text: htmlText,
+                    parse_mode: 'HTML',
                 });
-                // Only reply to first chunk
-                replyTo = undefined;
             }
-            catch (err) {
-                // Markdown parse failed — send as plain text
-                lastResult = await this.apiCall('sendMessage', {
-                    chat_id: chatId,
-                    text: chunk,
-                    ...(replyTo ? { reply_to_message_id: replyTo } : {}),
-                });
-                replyTo = undefined;
+            catch {
+                // HTML failed, try Markdown
+                try {
+                    lastResult = await this.apiCall('sendMessage', {
+                        ...baseParams,
+                        text: chunk,
+                        parse_mode: 'Markdown',
+                    });
+                }
+                catch {
+                    // All parsing failed, send plain text
+                    lastResult = await this.apiCall('sendMessage', {
+                        ...baseParams,
+                        text: chunk,
+                    });
+                }
             }
+            // Only reply to first chunk
+            replyTo = undefined;
         }
         return lastResult?.result;
     }
     async sendMessage(chatId, text) {
-        await this.sendMarkdown(chatId, text);
+        await this.sendFormattedMessage(chatId, text);
+    }
+    // ─── Reactions ──────────────────────────────────────────
+    async setReaction(chatId, messageId, emoji) {
+        try {
+            await this.apiCall('setMessageReaction', {
+                chat_id: chatId,
+                message_id: messageId,
+                reaction: emoji ? [{ type: 'emoji', emoji }] : [],
+            });
+        }
+        catch {
+            // Reactions may not be available in all chats
+        }
+    }
+    // ─── Typing ─────────────────────────────────────────────
+    async sendTyping(chatId, threadId) {
+        await this.apiCall('sendChatAction', {
+            chat_id: chatId,
+            action: 'typing',
+            ...(threadId ? { message_thread_id: threadId } : {}),
+        }).catch(() => { });
+    }
+    // ─── Helpers ────────────────────────────────────────────
+    isGroupChat(message) {
+        return message.chat.type === 'group' || message.chat.type === 'supergroup';
+    }
+    isMentioned(text) {
+        if (!this.botUsername)
+            return true;
+        const lower = text.toLowerCase();
+        return lower.includes(`@${this.botUsername}`);
+    }
+    getSessionId(message) {
+        const chatId = message.chat.id;
+        const threadId = message.message_thread_id;
+        if (threadId && message.chat.is_forum) {
+            return `tg_${chatId}_topic_${threadId}`;
+        }
+        return `tg_${chatId}`;
+    }
+    escapeHtml(text) {
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;');
+    }
+    /**
+     * Convert basic Markdown to Telegram-safe HTML.
+     * Handles: bold, italic, code, code blocks, links.
+     */
+    markdownToHtml(text) {
+        let html = this.escapeHtml(text);
+        // Code blocks (```...```)
+        html = html.replace(/```(\w*)\n?([\s\S]*?)```/g, (_m, lang, code) => {
+            return `<pre${lang ? ` class="language-${lang}"` : ''}>${code}</pre>`;
+        });
+        // Inline code (`...`)
+        html = html.replace(/`([^`]+)`/g, '<code>$1</code>');
+        // Bold (**...**)
+        html = html.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+        // Italic (*...*)
+        html = html.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '<i>$1</i>');
+        // Links [text](url)
+        html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+        return html;
+    }
+    /**
+     * Smart text splitting — prefer paragraph boundaries (blank lines) before hard length split.
+     * Aligned with OpenClaw's chunkMode="newline" behavior.
+     */
+    smartSplit(text, maxLen) {
+        if (text.length <= maxLen)
+            return [text];
+        const parts = [];
+        let remaining = text;
+        while (remaining.length > maxLen) {
+            // Try to find a paragraph break (double newline) near the limit
+            let splitAt = remaining.lastIndexOf('\n\n', maxLen);
+            if (splitAt < maxLen * 0.3) {
+                // No good paragraph break, try single newline
+                splitAt = remaining.lastIndexOf('\n', maxLen);
+            }
+            if (splitAt < maxLen * 0.3) {
+                // No good newline, hard split at limit
+                splitAt = maxLen;
+            }
+            parts.push(remaining.slice(0, splitAt).trimEnd());
+            remaining = remaining.slice(splitAt).trimStart();
+        }
+        if (remaining)
+            parts.push(remaining);
+        return parts;
     }
     async apiCall(method, body) {
         const url = `https://api.telegram.org/bot${this.token}/${method}`;
@@ -311,22 +537,21 @@ class TelegramChannel extends index_1.BaseChannel {
                 headers: { 'Content-Type': 'application/json' },
                 body: body ? JSON.stringify(body) : undefined,
             });
-            return await res.json();
+            const data = await res.json();
+            if (!data.ok) {
+                const err = new Error(`Telegram API ${method} failed: ${data.description}`);
+                err.telegramError = data;
+                throw err;
+            }
+            return data;
         }
         catch (err) {
+            if (err.telegramError)
+                throw err;
             console.error(`[TelegramChannel] API call ${method} failed:`, err);
             throw err;
         }
     }
-    splitText(text, maxLen) {
-        if (text.length <= maxLen)
-            return [text];
-        const parts = [];
-        for (let i = 0; i < text.length; i += maxLen) {
-            parts.push(text.slice(i, i + maxLen));
-        }
-        return parts;
-    }
 }
 exports.TelegramChannel = TelegramChannel;
 //# sourceMappingURL=telegram.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opc-agent",
-  "version": "4.0.11",
+  "version": "4.0.12",
   "description": "Open Agent Framework — Build, test, and run AI Agents for business workstations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/channels/telegram.ts

@@ -1,25 +1,37 @@
 import type { Message } from '../core/types';
-import type { LLMProvider } from '../providers/index';
 import { BaseChannel } from './index';
 
 /**
- * Telegram channel — supports both long-polling and webhook modes.
+ * Telegram channel — production-quality Telegram bot integration.
  *
- * Config:
- *   token: bot token (or TELEGRAM_BOT_TOKEN env var)
- *   mode: 'polling' | 'webhook' (default: 'polling')
- *   webhookUrl: required for webhook mode
- *   port: webhook server port (default: 3001)
- *
- * Polling mode requires no public URL — ideal for dev/local.
- * Webhook mode is more efficient for production.
+ * Features (aligned with OpenClaw):
+ * - Live stream preview (sendMessage + editMessageText)
+ * - Ack reaction on message receipt
+ * - Typing indicator throughout processing
+ * - HTML parse mode with Markdown fallback
+ * - Smart text chunking (paragraph-aware)
+ * - /start, /help, /status commands
+ * - Photo/document caption handling
+ * - Callback query (inline button) support
+ * - Reply threading
+ * - Error recovery with plain-text fallback
+ * - Forum topic support
+ * - Group mention filtering
  */
 
 export interface TelegramChannelConfig {
   token?: string;
   mode?: 'polling' | 'webhook';
   webhookUrl?: string;
+  webhookSecret?: string;
   port?: number;
+  // Feature flags
+  streaming?: boolean | 'off' | 'partial';
+  ackReaction?: string; // emoji to react with on receipt, e.g. "👀"
+  linkPreview?: boolean;
+  textChunkLimit?: number;
+  requireMention?: boolean; // for groups
+  botUsername?: string; // for mention detection
 }
 
 export class TelegramChannel extends BaseChannel {
@@ -27,7 +39,17 @@ export class TelegramChannel extends BaseChannel {
   private token: string;
   private mode: 'polling' | 'webhook';
   private webhookUrl?: string;
+  private webhookSecret?: string;
   private port: number;
+  private botUsername: string = '';
+  private botInfo: any = null;
+
+  // Config
+  private streamingEnabled: boolean;
+  private ackReaction: string;
+  private linkPreview: boolean;
+  private textChunkLimit: number;
+  private requireMention: boolean;
 
   // Polling state
   private offset: number = 0;
@@ -36,12 +58,28 @@ export class TelegramChannel extends BaseChannel {
   // Webhook state
   private server: import('http').Server | null = null;
 
+  // Stream handler — set by runtime when provider supports streaming
+  private streamHandler?: (msg: Message) => AsyncIterable<string>;
+
   constructor(config: TelegramChannelConfig = {}) {
     super();
     this.token = config.token ?? process.env.TELEGRAM_BOT_TOKEN ?? '';
     this.mode = config.mode ?? 'polling';
     this.webhookUrl = config.webhookUrl;
+    this.webhookSecret = config.webhookSecret;
     this.port = config.port ?? 3001;
+
+    // Feature config
+    this.streamingEnabled = config.streaming !== false && config.streaming !== 'off';
+    this.ackReaction = config.ackReaction ?? '👀';
+    this.linkPreview = config.linkPreview ?? true;
+    this.textChunkLimit = config.textChunkLimit ?? 4000;
+    this.requireMention = config.requireMention ?? false;
+    if (config.botUsername) this.botUsername = config.botUsername.replace('@', '').toLowerCase();
+  }
+
+  setStreamHandler(handler: (msg: Message) => AsyncIterable<string>): void {
+    this.streamHandler = handler;
   }
 
   async start(): Promise<void> {
@@ -50,6 +88,16 @@ export class TelegramChannel extends BaseChannel {
       return;
     }
 
+    // Fetch bot info for username detection
+    try {
+      const me = await this.apiCall('getMe');
+      if (me?.result) {
+        this.botInfo = me.result;
+        this.botUsername = (me.result.username ?? '').toLowerCase();
+        console.log(`[TelegramChannel] Bot: @${this.botUsername}`);
+      }
+    } catch {}
+
     if (this.mode === 'webhook') {
       await this.startWebhook();
     } else {
@@ -68,7 +116,6 @@ export class TelegramChannel extends BaseChannel {
   // ─── Polling Mode ────────────────────────────────────────
 
   private async startPolling(): Promise<void> {
-    // Delete any existing webhook so polling works
     await this.apiCall('deleteWebhook');
     console.log(`[TelegramChannel] Started long-polling mode`);
     this.polling = true;
@@ -80,11 +127,13 @@ export class TelegramChannel extends BaseChannel {
       try {
         const updates = await this.getUpdates();
         for (const update of updates) {
-          await this.processUpdate(update);
+          // Don't await — process concurrently for better responsiveness
+          this.processUpdate(update).catch((err) => {
+            console.error('[TelegramChannel] Update processing error:', err);
+          });
         }
       } catch (err) {
         console.error('[TelegramChannel] Polling error:', err);
-        // Back off on error
         if (this.polling) {
           await new Promise((r) => setTimeout(r, 5000));
         }
@@ -93,9 +142,9 @@ export class TelegramChannel extends BaseChannel {
   }
 
   private async getUpdates(): Promise<any[]> {
-    const url = `https://api.telegram.org/bot${this.token}/getUpdates?offset=${this.offset}&timeout=30&allowed_updates=["message"]`;
+    const url = `https://api.telegram.org/bot${this.token}/getUpdates?offset=${this.offset}&timeout=30&allowed_updates=${encodeURIComponent('["message","callback_query","message_reaction"]')}`;
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 40000); // 30s long-poll + 10s buffer
+    const timeout = setTimeout(() => controller.abort(), 40000);
 
     try {
       const res = await fetch(url, { signal: controller.signal });
@@ -113,7 +162,12 @@ export class TelegramChannel extends BaseChannel {
 
   private async startWebhook(): Promise<void> {
     if (this.webhookUrl) {
-      await this.apiCall('setWebhook', { url: `${this.webhookUrl}/webhook/${this.token}` });
+      const params: Record<string, unknown> = {
+        url: `${this.webhookUrl}/webhook/${this.token}`,
+        allowed_updates: ['message', 'callback_query', 'message_reaction'],
+      };
+      if (this.webhookSecret) params.secret_token = this.webhookSecret;
+      await this.apiCall('setWebhook', params);
     }
 
     const express = (await import('express')).default;
@@ -121,8 +175,16 @@ export class TelegramChannel extends BaseChannel {
     app.use(express.json());
 
     app.post(`/webhook/${this.token}`, async (req, res) => {
+      // Verify secret if configured
+      if (this.webhookSecret && req.headers['x-telegram-bot-api-secret-token'] !== this.webhookSecret) {
+        res.status(403).json({ error: 'Forbidden' });
+        return;
+      }
       try {
-        await this.processUpdate(req.body);
+        // Don't await — respond quickly, process in background
+        this.processUpdate(req.body).catch((err) => {
+          console.error('[TelegramChannel] Webhook processing error:', err);
+        });
         res.json({ ok: true });
       } catch (err) {
         console.error('[TelegramChannel] Webhook error:', err);
@@ -131,7 +193,7 @@ export class TelegramChannel extends BaseChannel {
     });
 
     app.get('/health', (_req, res) => {
-      res.json({ status: 'ok', channel: 'telegram', mode: 'webhook' });
+      res.json({ status: 'ok', channel: 'telegram', mode: 'webhook', bot: this.botUsername });
     });
 
     return new Promise((resolve) => {
@@ -149,92 +211,194 @@ export class TelegramChannel extends BaseChannel {
     });
   }
 
-  // ─── Shared ──────────────────────────────────────────────
+  // ─── Update Processing ──────────────────────────────────
 
   private async processUpdate(update: any): Promise<void> {
+    // Handle callback queries (inline buttons)
+    if (update.callback_query) {
+      await this.handleCallbackQuery(update.callback_query);
+      return;
+    }
+
     const message = update.message || update.edited_message;
     if (!message || !this.handler) return;
 
-    // Handle /start command
-    if (message.text === '/start') {
-      await this.sendMarkdown(message.chat.id, '👋 Hello! I\'m ready to help. Send me a message to get started.');
-      return;
+    // Handle commands
+    if (message.text?.startsWith('/')) {
+      const handled = await this.handleCommand(message);
+      if (handled) return;
     }
 
-    // Handle text, photo captions, document captions
+    // Extract text from various message types
     const text = message.text || message.caption;
     if (!text) return;
 
+    // Group mention filtering
+    if (this.isGroupChat(message) && this.requireMention) {
+      if (!this.isMentioned(text)) return;
+    }
+
+    // Build message object
     const msg: Message = {
       id: `tg_${message.message_id}`,
       role: 'user',
       content: text,
       timestamp: message.date * 1000,
       metadata: {
-        sessionId: `tg_${message.chat.id}`,
+        sessionId: this.getSessionId(message),
         chatId: message.chat.id,
         userId: message.from?.id,
         username: message.from?.username,
         firstName: message.from?.first_name,
+        lastName: message.from?.last_name,
         platform: 'telegram',
         chatType: message.chat.type,
+        messageThreadId: message.message_thread_id,
         replyToMessageId: message.message_id,
       },
     };
 
-    // Show typing indicator
-    await this.apiCall('sendChatAction', { chat_id: message.chat.id, action: 'typing' });
+    // Ack reaction — immediate visual feedback
+    if (this.ackReaction) {
+      this.setReaction(message.chat.id, message.message_id, this.ackReaction).catch(() => {});
+    }
+
+    // Typing indicator
+    const threadId = message.message_thread_id;
+    await this.sendTyping(message.chat.id, threadId);
     const typingInterval = setInterval(() => {
-      this.apiCall('sendChatAction', { chat_id: message.chat.id, action: 'typing' }).catch(() => {});
+      this.sendTyping(message.chat.id, threadId).catch(() => {});
     }, 4000);
 
     try {
-      // Try streaming if provider supports it
-      if (this.streamHandler) {
-        await this.streamResponse(message.chat.id, msg, message.message_id);
+      if (this.streamingEnabled && this.streamHandler) {
+        await this.streamResponse(message.chat.id, msg, message.message_id, threadId);
       } else {
         const response = await this.handler(msg);
-        await this.sendMarkdown(message.chat.id, response.content, message.message_id);
+        await this.sendFormattedMessage(message.chat.id, response.content, message.message_id, threadId);
+      }
+
+      // Remove ack reaction after successful response
+      if (this.ackReaction) {
+        this.setReaction(message.chat.id, message.message_id, '').catch(() => {});
       }
     } catch (err) {
       console.error('[TelegramChannel] Error processing message:', err);
-      await this.sendMarkdown(message.chat.id, '⚠️ Sorry, something went wrong. Please try again.');
+      await this.sendFormattedMessage(message.chat.id, '⚠️ Sorry, something went wrong. Please try again.', message.message_id, threadId);
     } finally {
       clearInterval(typingInterval);
     }
   }
 
-  private async streamResponse(chatId: number | string, msg: Message, replyTo?: number): Promise<void> {
+  // ─── Commands ───────────────────────────────────────────
+
+  private async handleCommand(message: any): Promise<boolean> {
+    const text = message.text ?? '';
+    const command = text.split(' ')[0].split('@')[0].toLowerCase(); // Strip @botname
+
+    switch (command) {
+      case '/start':
+        await this.sendFormattedMessage(
+          message.chat.id,
+          `👋 <b>Hello${message.from?.first_name ? ' ' + this.escapeHtml(message.from.first_name) : ''}!</b>\n\nI'm ready to help. Send me a message to get started.\n\nCommands:\n/help — Show available commands\n/status — Check bot status`,
+          undefined,
+          message.message_thread_id
+        );
+        return true;
+
+      case '/help':
+        await this.sendFormattedMessage(
+          message.chat.id,
+          `📖 <b>Available Commands</b>\n\n/start — Start conversation\n/help — Show this help\n/status — Bot status\n\nJust send a message and I'll respond!`,
+          undefined,
+          message.message_thread_id
+        );
+        return true;
+
+      case '/status':
+        const uptime = process.uptime();
+        const hours = Math.floor(uptime / 3600);
+        const mins = Math.floor((uptime % 3600) / 60);
+        await this.sendFormattedMessage(
+          message.chat.id,
+          `🟢 <b>Bot Status</b>\n\n⏱ Uptime: ${hours}h ${mins}m\n🤖 Bot: @${this.botUsername}\n💬 Mode: ${this.mode}\n📡 Streaming: ${this.streamingEnabled ? 'on' : 'off'}`,
+          undefined,
+          message.message_thread_id
+        );
+        return true;
+
+      default:
+        return false; // Not a recognized command, let it flow through as normal message
+    }
+  }
+
+  // ─── Callback Queries (Inline Buttons) ──────────────────
+
+  private async handleCallbackQuery(query: any): Promise<void> {
+    // Answer the callback to remove loading state
+    await this.apiCall('answerCallbackQuery', { callback_query_id: query.id });
+
+    if (!this.handler || !query.data) return;
+
+    const msg: Message = {
+      id: `tg_cb_${query.id}`,
+      role: 'user',
+      content: `callback_data: ${query.data}`,
+      timestamp: Date.now(),
+      metadata: {
+        sessionId: `tg_${query.message?.chat?.id ?? query.from.id}`,
+        chatId: query.message?.chat?.id ?? query.from.id,
+        userId: query.from.id,
+        username: query.from.username,
+        firstName: query.from.first_name,
+        platform: 'telegram',
+        chatType: query.message?.chat?.type ?? 'private',
+        isCallback: true,
+      },
+    };
+
+    try {
+      const response = await this.handler(msg);
+      const chatId = query.message?.chat?.id ?? query.from.id;
+      await this.sendFormattedMessage(chatId, response.content);
+    } catch (err) {
+      console.error('[TelegramChannel] Callback query error:', err);
+    }
+  }
+
+  // ─── Streaming ──────────────────────────────────────────
+
+  private async streamResponse(chatId: number | string, msg: Message, replyTo?: number, threadId?: number): Promise<void> {
     if (!this.streamHandler) return;
 
     let sentMessageId: number | null = null;
     let fullText = '';
     let lastEditTime = 0;
-    const EDIT_INTERVAL = 1000; // Edit at most once per second
-    let pendingEdit = false;
+    const EDIT_INTERVAL = 800; // Edit slightly faster than before
+    const MIN_FIRST_SEND = 20; // Min chars before first send (avoid tiny initial message)
 
-    const doEdit = async () => {
+    const doEdit = async (final: boolean = false) => {
       if (!sentMessageId || !fullText) return;
-      pendingEdit = false;
+      const displayText = final ? fullText : fullText + ' ▍'; // Cursor indicator while streaming
       try {
         await this.apiCall('editMessageText', {
           chat_id: chatId,
           message_id: sentMessageId,
-          text: fullText,
-          parse_mode: 'Markdown',
+          text: displayText,
+          parse_mode: 'HTML',
+          disable_web_page_preview: !this.linkPreview,
         });
         lastEditTime = Date.now();
-      } catch (err: any) {
-        // If Markdown fails, try plain text
-        if (err?.message?.includes('parse') || err?.message?.includes('entities')) {
-          try {
-            await this.apiCall('editMessageText', {
-              chat_id: chatId,
-              message_id: sentMessageId,
-              text: fullText,
-            });
-          } catch {}
-        }
+      } catch {
+        // HTML parse failed, try plain text
+        try {
+          await this.apiCall('editMessageText', {
+            chat_id: chatId,
+            message_id: sentMessageId,
+            text: displayText,
+          });
+          lastEditTime = Date.now();
+        } catch {}
       }
     };
 
@@ -242,69 +406,190 @@ export class TelegramChannel extends BaseChannel {
       for await (const chunk of this.streamHandler(msg)) {
         fullText += chunk;
 
-        if (!sentMessageId) {
-          // Send first message
-          const result = await this.sendMarkdown(chatId, fullText, replyTo);
+        if (!sentMessageId && fullText.length >= MIN_FIRST_SEND) {
+          const result = await this.sendFormattedMessage(chatId, fullText + ' ▍', replyTo, threadId);
           sentMessageId = result?.message_id;
           lastEditTime = Date.now();
-        } else {
+        } else if (sentMessageId) {
           const now = Date.now();
           if (now - lastEditTime >= EDIT_INTERVAL) {
             await doEdit();
-          } else if (!pendingEdit) {
-            pendingEdit = true;
           }
         }
       }
 
-      // Final edit with complete text
+      // Final edit — remove cursor, clean formatting
       if (sentMessageId && fullText) {
-        await doEdit();
+        await doEdit(true);
+      } else if (!sentMessageId && fullText) {
+        // Never sent first message (very short response)
+        await this.sendFormattedMessage(chatId, fullText, replyTo, threadId);
       }
     } catch (err) {
-      // If streaming fails, send what we have
       if (!sentMessageId && fullText) {
-        await this.sendMarkdown(chatId, fullText, replyTo);
+        await this.sendFormattedMessage(chatId, fullText, replyTo, threadId);
       }
       throw err;
     }
   }
 
-  // Stream handler — set by runtime when provider supports streaming
-  private streamHandler?: (msg: Message) => AsyncIterable<string>;
-
-  setStreamHandler(handler: (msg: Message) => AsyncIterable<string>): void {
-    this.streamHandler = handler;
-  }
+  // ─── Message Sending ───────────────────────────────────
 
-  async sendMarkdown(chatId: number | string, text: string, replyTo?: number): Promise<any> {
-    const chunks = this.splitText(text, 4096);
+  async sendFormattedMessage(chatId: number | string, text: string, replyTo?: number, threadId?: number): Promise<any> {
+    const chunks = this.smartSplit(text, this.textChunkLimit);
     let lastResult: any = null;
+
     for (const chunk of chunks) {
+      const baseParams: Record<string, unknown> = {
+        chat_id: chatId,
+        disable_web_page_preview: !this.linkPreview,
+        ...(replyTo ? { reply_to_message_id: replyTo } : {}),
+        ...(threadId ? { message_thread_id: threadId } : {}),
+      };
+
+      // Try HTML first (richer formatting)
       try {
+        const htmlText = this.markdownToHtml(chunk);
         lastResult = await this.apiCall('sendMessage', {
-          chat_id: chatId,
-          text: chunk,
-          parse_mode: 'Markdown',
-          ...(replyTo ? { reply_to_message_id: replyTo } : {}),
-        });
-        // Only reply to first chunk
-        replyTo = undefined;
-      } catch (err: any) {
-        // Markdown parse failed — send as plain text
-        lastResult = await this.apiCall('sendMessage', {
-          chat_id: chatId,
-          text: chunk,
-          ...(replyTo ? { reply_to_message_id: replyTo } : {}),
+          ...baseParams,
+          text: htmlText,
+          parse_mode: 'HTML',
         });
-        replyTo = undefined;
+      } catch {
+        // HTML failed, try Markdown
+        try {
+          lastResult = await this.apiCall('sendMessage', {
+            ...baseParams,
+            text: chunk,
+            parse_mode: 'Markdown',
+          });
+        } catch {
+          // All parsing failed, send plain text
+          lastResult = await this.apiCall('sendMessage', {
+            ...baseParams,
+            text: chunk,
+          });
+        }
       }
+
+      // Only reply to first chunk
+      replyTo = undefined;
     }
     return lastResult?.result;
   }
 
   async sendMessage(chatId: number | string, text: string): Promise<void> {
-    await this.sendMarkdown(chatId, text);
+    await this.sendFormattedMessage(chatId, text);
+  }
+
+  // ─── Reactions ──────────────────────────────────────────
+
+  private async setReaction(chatId: number | string, messageId: number, emoji: string): Promise<void> {
+    try {
+      await this.apiCall('setMessageReaction', {
+        chat_id: chatId,
+        message_id: messageId,
+        reaction: emoji ? [{ type: 'emoji', emoji }] : [],
+      });
+    } catch {
+      // Reactions may not be available in all chats
+    }
+  }
+
+  // ─── Typing ─────────────────────────────────────────────
+
+  private async sendTyping(chatId: number | string, threadId?: number): Promise<void> {
+    await this.apiCall('sendChatAction', {
+      chat_id: chatId,
+      action: 'typing',
+      ...(threadId ? { message_thread_id: threadId } : {}),
+    }).catch(() => {});
+  }
+
+  // ─── Helpers ────────────────────────────────────────────
+
+  private isGroupChat(message: any): boolean {
+    return message.chat.type === 'group' || message.chat.type === 'supergroup';
+  }
+
+  private isMentioned(text: string): boolean {
+    if (!this.botUsername) return true;
+    const lower = text.toLowerCase();
+    return lower.includes(`@${this.botUsername}`);
+  }
+
+  private getSessionId(message: any): string {
+    const chatId = message.chat.id;
+    const threadId = message.message_thread_id;
+    if (threadId && message.chat.is_forum) {
+      return `tg_${chatId}_topic_${threadId}`;
+    }
+    return `tg_${chatId}`;
+  }
+
+  private escapeHtml(text: string): string {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  /**
+   * Convert basic Markdown to Telegram-safe HTML.
+   * Handles: bold, italic, code, code blocks, links.
+   */
+  private markdownToHtml(text: string): string {
+    let html = this.escapeHtml(text);
+
+    // Code blocks (```...```)
+    html = html.replace(/```(\w*)\n?([\s\S]*?)```/g, (_m, lang, code) => {
+      return `<pre${lang ? ` class="language-${lang}"` : ''}>${code}</pre>`;
+    });
+
+    // Inline code (`...`)
+    html = html.replace(/`([^`]+)`/g, '<code>$1</code>');
+
+    // Bold (**...**)
+    html = html.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+
+    // Italic (*...*)
+    html = html.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '<i>$1</i>');
+
+    // Links [text](url)
+    html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+    return html;
+  }
+
+  /**
+   * Smart text splitting — prefer paragraph boundaries (blank lines) before hard length split.
+   * Aligned with OpenClaw's chunkMode="newline" behavior.
+   */
+  private smartSplit(text: string, maxLen: number): string[] {
+    if (text.length <= maxLen) return [text];
+
+    const parts: string[] = [];
+    let remaining = text;
+
+    while (remaining.length > maxLen) {
+      // Try to find a paragraph break (double newline) near the limit
+      let splitAt = remaining.lastIndexOf('\n\n', maxLen);
+      if (splitAt < maxLen * 0.3) {
+        // No good paragraph break, try single newline
+        splitAt = remaining.lastIndexOf('\n', maxLen);
+      }
+      if (splitAt < maxLen * 0.3) {
+        // No good newline, hard split at limit
+        splitAt = maxLen;
+      }
+
+      parts.push(remaining.slice(0, splitAt).trimEnd());
+      remaining = remaining.slice(splitAt).trimStart();
+    }
+
+    if (remaining) parts.push(remaining);
+    return parts;
   }
 
   private async apiCall(method: string, body?: Record<string, unknown>): Promise<any> {
@@ -315,19 +600,17 @@ export class TelegramChannel extends BaseChannel {
         headers: { 'Content-Type': 'application/json' },
         body: body ? JSON.stringify(body) : undefined,
       });
-      return await res.json();
+      const data = await res.json() as { ok: boolean; result?: any; description?: string };
+      if (!data.ok) {
+        const err = new Error(`Telegram API ${method} failed: ${data.description}`);
+        (err as any).telegramError = data;
+        throw err;
+      }
+      return data;
     } catch (err) {
+      if ((err as any).telegramError) throw err;
       console.error(`[TelegramChannel] API call ${method} failed:`, err);
       throw err;
     }
   }
-
-  private splitText(text: string, maxLen: number): string[] {
-    if (text.length <= maxLen) return [text];
-    const parts: string[] = [];
-    for (let i = 0; i < text.length; i += maxLen) {
-      parts.push(text.slice(i, i + maxLen));
-    }
-    return parts;
-  }
 }