@jungjaehoon/mama-os 0.25.0 → 0.27.0

package/dist/gateways/telegram.js

@@ -3,24 +3,56 @@
  * Telegram Gateway for MAMA Standalone
  *
  * Production-hardened Telegram bot integration using grammY:
- * - 2-stage message dedup (message_id + content signature)
+ * - Telegram message_id dedup without dropping repeated short replies
+ * - Photo/document/caption ingestion through MAMA content blocks
  * - Group chat filtering (mention/command/reply-to-bot only)
  * - Sticker receive/send with emotion mapping
- * - ToolStatusTracker streaming (placeholder → editMessageText)
+ * - Single-message streaming presenter (placeholder → final answer)
  * - Typing indicator, error handling
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TelegramGateway = void 0;
+const promises_1 = require("node:fs/promises");
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_async_hooks_1 = require("node:async_hooks");
 const grammy_1 = require("grammy");
 const base_gateway_js_1 = require("./base-gateway.js");
 const memory_logger_js_1 = require("../memory/memory-logger.js");
 const untrusted_content_js_1 = require("../utils/untrusted-content.js");
-const tool_status_tracker_js_1 = require("./tool-status-tracker.js");
+const attachment_utils_js_1 = require("./attachment-utils.js");
+const telegram_media_js_1 = require("./telegram-media.js");
+const telegram_response_presenter_js_1 = require("./telegram-response-presenter.js");
+const telegram_message_ledger_js_1 = require("./telegram-message-ledger.js");
 const TELEGRAM_MAX_LENGTH = 4096;
 const MESSAGE_DEDUP_TTL_MS = 60_000;
-const MESSAGE_CONTENT_DEDUP_TTL_MS = 5_000;
 const REJECTED_CHAT_WARN_INTERVAL_MS = 60_000;
 const TYPING_INTERVAL_MS = 4_000;
+function parseOutboundChunkProgress(value) {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== 'object')
+        throw new Error('Invalid Telegram outbound progress');
+    const record = parsed;
+    if (record.version !== 1 ||
+        !Number.isSafeInteger(record.nextIndex) ||
+        record.nextIndex < 0 ||
+        typeof record.uncertain !== 'boolean') {
+        throw new Error('Invalid Telegram outbound progress');
+    }
+    return { nextIndex: record.nextIndex, uncertain: record.uncertain };
+}
+function isDefiniteTelegramApiRejection(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const record = error;
+    if (Number.isSafeInteger(record.error_code))
+        return true;
+    const response = record.response;
+    return (Boolean(response) &&
+        typeof response === 'object' &&
+        Number.isSafeInteger(response.error_code));
+}
 const EMOTION_EMOJI = {
     happy: ['😊', '😀', '😄', '🙂'],
     laugh: ['😂', '🤣', '😆'],
@@ -51,9 +83,13 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
     botUsername = '';
     lastError = null;
     lastMessageAt;
-    // Dedup maps
+    mediaRoot;
+    fetchImpl;
+    messageLedger;
+    chatTails = new Map();
+    activeChat = new node_async_hooks_1.AsyncLocalStorage();
+    // Telegram update dedup
     recentMessageIds = new Map();
-    recentMessageSignatures = new Map();
     rejectedChatWarnAt = new Map();
     // Dedup cleanup timer
     dedupCleanupTimer = null;
@@ -71,6 +107,13 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
             token: options.token,
             allowedChats: options.config?.allowedChats || [],
         };
+        this.mediaRoot =
+            options.mediaRoot ??
+                (0, node_path_1.join)(process.env.MAMA_WORKSPACE || (0, node_path_1.join)((0, node_os_1.homedir)(), '.mama', 'workspace'), 'media', 'inbound', 'telegram');
+        this.fetchImpl = options.fetchImpl;
+        this.messageLedger = new telegram_message_ledger_js_1.TelegramMessageLedger(options.messageLedgerPath ??
+            process.env.MAMA_TELEGRAM_MESSAGE_LEDGER_PATH ??
+            `${this.mediaRoot}.processed-message-ids.json`, { log: (line) => console.error(line) });
     }
     async start() {
         if (this.connected) {
@@ -93,6 +136,9 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
                         timestamp: new Date(),
                         data: { error: error instanceof Error ? error.message : String(error) },
                     });
+                    // Let grammY treat the update as failed. The durable message ledger
+                    // prevents unsafe turn re-execution and replays a ready outbox response.
+                    throw error;
                 }
             });
             this.bot.catch((err) => {
@@ -103,6 +149,7 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
             this.botId = this.bot.botInfo.id;
             this.botUsername = this.bot.botInfo.username || '';
             console.log(`Telegram bot logged in as @${this.botUsername}`);
+            await this.recoverPendingInboundDeliveries();
             if (this.config.allowedChats && this.config.allowedChats.length > 0) {
                 console.log(`[Telegram] Inbound allowlist active: ${this.config.allowedChats.length} chat(s)`);
             }
@@ -113,6 +160,7 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
             }
             this.connected = true;
             this.lastError = null;
+            await (0, telegram_media_js_1.pruneTelegramMediaRoot)(this.mediaRoot);
             // Periodic dedup cleanup
             this.dedupCleanupTimer = setInterval(() => {
                 const now = Date.now();
@@ -120,15 +168,17 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
                     if (now - ts > MESSAGE_DEDUP_TTL_MS)
                         this.recentMessageIds.delete(key);
                 }
-                for (const [key, ts] of this.recentMessageSignatures) {
-                    if (now - ts > MESSAGE_CONTENT_DEDUP_TTL_MS)
-                        this.recentMessageSignatures.delete(key);
-                }
                 for (const [key, ts] of this.rejectedChatWarnAt) {
                     if (now - ts > REJECTED_CHAT_WARN_INTERVAL_MS) {
                         this.rejectedChatWarnAt.delete(key);
                     }
                 }
+                void (0, telegram_media_js_1.pruneTelegramMediaRoot)(this.mediaRoot).catch((error) => {
+                    console.error(`[Telegram] media retention cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+                void this.recoverPendingInboundDeliveries().catch((error) => {
+                    console.error(`[Telegram] pending response recovery failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
             }, 60_000);
             this.emitEvent({
                 type: 'connected',
@@ -179,32 +229,47 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
         });
     }
     async handleMessage(msg) {
+        const chatKey = String(msg.chat?.id ?? 'unknown');
+        await this.runInChatQueue(chatKey, () => this.processMessage(msg));
+    }
+    async runInChatQueue(chatKey, work, allowReentrant = false) {
+        if (allowReentrant && this.activeChat.getStore() === chatKey)
+            return work();
+        const previous = this.chatTails.get(chatKey);
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const currentTail = (previous ?? Promise.resolve()).catch(() => { }).then(() => gate);
+        this.chatTails.set(chatKey, currentTail);
+        try {
+            if (previous)
+                await previous.catch(() => { });
+            return await this.activeChat.run(chatKey, work);
+        }
+        finally {
+            release();
+            if (this.chatTails.get(chatKey) === currentTail)
+                this.chatTails.delete(chatKey);
+        }
+    }
+    async processMessage(msg) {
         if (!msg.from || !msg.chat)
             return;
         const now = Date.now();
-        // Stage 1: message_id dedup (60s TTL)
+        // Telegram update dedup (60s TTL). Do not deduplicate by text content:
+        // repeated short replies and emoji are distinct conversation turns.
         const messageKey = `${msg.chat.id}:${msg.message_id}`;
+        if (this.messageLedger.get(messageKey)?.state === 'delivered')
+            return;
         if (this.recentMessageIds.has(messageKey))
             return;
         this.recentMessageIds.set(messageKey, now);
-        // Stage 2: content signature dedup (5s TTL)
-        const rawText = msg.text || msg.sticker?.emoji || '';
-        const signature = `${msg.chat.id}:${msg.from.id}:${rawText.trim()}`;
-        if (rawText.trim()) {
-            const seenAt = this.recentMessageSignatures.get(signature);
-            if (seenAt && now - seenAt < MESSAGE_CONTENT_DEDUP_TTL_MS)
-                return;
-            this.recentMessageSignatures.set(signature, now);
-        }
         // Cleanup expired entries
         for (const [key, ts] of this.recentMessageIds) {
             if (now - ts > MESSAGE_DEDUP_TTL_MS)
                 this.recentMessageIds.delete(key);
         }
-        for (const [key, ts] of this.recentMessageSignatures) {
-            if (now - ts > MESSAGE_CONTENT_DEDUP_TTL_MS)
-                this.recentMessageSignatures.delete(key);
-        }
         // Allowed chats filter
         if (this.config.allowedChats && this.config.allowedChats.length > 0) {
             if (!this.config.allowedChats.includes(String(msg.chat.id))) {
@@ -218,38 +283,193 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
                 return;
             }
         }
+        const hasMedia = Boolean((msg.photo && msg.photo.length > 0) || msg.document);
+        if (hasMedia && (!this.config.allowedChats || this.config.allowedChats.length === 0)) {
+            const lastWarn = this.rejectedChatWarnAt.get(String(msg.chat.id)) ?? 0;
+            if (now - lastWarn > REJECTED_CHAT_WARN_INTERVAL_MS) {
+                this.rejectedChatWarnAt.set(String(msg.chat.id), now);
+                console.warn('[Telegram] Dropped media because telegram.allowed_chats is not configured');
+            }
+            return;
+        }
+        const selectedText = msg.text ?? msg.caption ?? '';
+        const selectedEntities = msg.text !== undefined ? msg.entities : msg.caption_entities;
         // Group chat filtering
         const isGroup = msg.chat.type === 'group' || msg.chat.type === 'supergroup';
         if (isGroup) {
-            const text = msg.text || '';
             const isMention = this.botUsername &&
-                msg.entities?.some((e) => e.type === 'mention' &&
-                    text.slice(e.offset, e.offset + e.length).toLowerCase() ===
+                selectedEntities?.some((e) => e.type === 'mention' &&
+                    selectedText.slice(e.offset, e.offset + e.length).toLowerCase() ===
                         `@${this.botUsername.toLowerCase()}`);
-            const isBotCommand = msg.entities?.some((e) => e.type === 'bot_command');
+            const isBotCommand = selectedEntities?.some((e) => e.type === 'bot_command');
             const isReplyToBot = msg.reply_to_message?.from?.id === this.botId;
             if (!isMention && !isBotCommand && !isReplyToBot)
                 return;
         }
-        // Process text (sticker conversion, mention stripping)
-        let text = msg.text || '';
+        let text = selectedText;
         if (msg.sticker) {
             text = `[sticker: ${msg.sticker.emoji || '😊'}]`;
         }
-        if (!text.trim())
-            return;
+        if (isGroup && this.botUsername) {
+            const escaped = this.botUsername.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            text = text.replace(new RegExp(`@${escaped}\\b`, 'gi'), '').trim();
+        }
         // Provenance labeling: a FORWARDED message is third-party content the
-        // owner relayed, not the owner speaking. Wrap it so downstream treats it
-        // as data (never instructions), the sensitive-request wall skips it, and
-        // the save-candidate extractor ignores directives inside it.
+        // owner relayed, not the owner speaking. Selection and mention removal
+        // happen first so caption provenance follows the same trust boundary.
         const isForwarded = Boolean(msg.forward_origin);
+        const durableEntry = this.messageLedger.get(messageKey);
+        const numChatId = msg.chat.id;
+        const api = this.bot.api;
+        const presenter = this.createResponsePresenter(numChatId, messageKey, durableEntry?.nextChunkIndex ?? 0);
+        if (durableEntry?.state !== 'ready')
+            await presenter.start();
+        if (durableEntry?.state === 'ready' && durableEntry.response !== undefined) {
+            try {
+                await presenter.finalize(durableEntry.response);
+                this.messageLedger.markDelivered(messageKey);
+            }
+            catch (error) {
+                this.recentMessageIds.delete(messageKey);
+                throw error;
+            }
+            return;
+        }
+        if (durableEntry?.state === 'processing') {
+            const interruptedNotice = 'The previous processing attempt was interrupted. It was not rerun because its external ' +
+                'side effects could not be proven safe to repeat. Please send a new message if you want ' +
+                'to retry it.';
+            this.messageLedger.markReady(messageKey, interruptedNotice);
+            try {
+                await presenter.finalize(interruptedNotice);
+                this.messageLedger.markDelivered(messageKey);
+            }
+            catch (error) {
+                this.recentMessageIds.delete(messageKey);
+                throw error;
+            }
+            return;
+        }
+        const attachments = [];
+        const contentBlocks = [];
+        let transientMediaPath;
+        try {
+            if (msg.photo && msg.photo.length > 0) {
+                const photo = msg.photo[msg.photo.length - 1];
+                const downloaded = await (0, telegram_media_js_1.downloadTelegramMedia)({
+                    botToken: this.token,
+                    fileId: photo.file_id,
+                    fileUniqueId: photo.file_unique_id,
+                    declaredSize: photo.file_size,
+                    kind: 'photo',
+                    mediaRoot: this.mediaRoot,
+                    getFile: (fileId) => api.getFile(fileId),
+                    fetchImpl: this.fetchImpl,
+                });
+                transientMediaPath = downloaded.localPath;
+                const detectedType = (0, attachment_utils_js_1.detectImageType)(await (0, promises_1.readFile)(downloaded.localPath));
+                if (!detectedType) {
+                    await presenter.fail('This image format is not supported.');
+                    return;
+                }
+                const attachment = {
+                    type: 'image',
+                    sourceRef: downloaded.sourceRef,
+                    localPath: downloaded.localPath,
+                    filename: downloaded.filename,
+                    contentType: detectedType,
+                    size: downloaded.size,
+                };
+                attachments.push(attachment);
+                const builtBlocks = await (0, attachment_utils_js_1.buildContentBlocks)([attachment]);
+                const imageBlocks = builtBlocks.filter((block) => block.type === 'image');
+                if (imageBlocks.length === 0) {
+                    await presenter.fail('This image format is not supported.');
+                    return;
+                }
+                for (const block of imageBlocks) {
+                    contentBlocks.push({ type: 'image', source: block.source });
+                }
+                // Keep the private local path for bounded OCR/overlay follow-ups. The
+                // media retention sweeper removes it after the configured TTL/quota.
+                transientMediaPath = undefined;
+                if (!text.trim()) {
+                    text = '[Image]';
+                }
+            }
+            else if (msg.document) {
+                const downloaded = await (0, telegram_media_js_1.downloadTelegramMedia)({
+                    botToken: this.token,
+                    fileId: msg.document.file_id,
+                    fileUniqueId: msg.document.file_unique_id,
+                    filename: msg.document.file_name,
+                    mimeType: msg.document.mime_type,
+                    declaredSize: msg.document.file_size,
+                    kind: 'document',
+                    mediaRoot: this.mediaRoot,
+                    getFile: (fileId) => api.getFile(fileId),
+                    fetchImpl: this.fetchImpl,
+                });
+                transientMediaPath = downloaded.localPath;
+                const detectedType = (0, attachment_utils_js_1.detectImageType)(await (0, promises_1.readFile)(downloaded.localPath));
+                if (downloaded.mimeType.startsWith('image/') && !detectedType) {
+                    await presenter.fail('This image format is not supported.');
+                    return;
+                }
+                const attachment = {
+                    type: detectedType ? 'image' : 'file',
+                    sourceRef: downloaded.sourceRef,
+                    localPath: downloaded.localPath,
+                    filename: downloaded.filename,
+                    contentType: detectedType ?? downloaded.mimeType,
+                    size: downloaded.size,
+                };
+                attachments.push(attachment);
+                if (detectedType) {
+                    const builtBlocks = await (0, attachment_utils_js_1.buildContentBlocks)([attachment]);
+                    const imageBlocks = builtBlocks.filter((block) => block.type === 'image');
+                    if (imageBlocks.length === 0) {
+                        await presenter.fail('This image format is not supported.');
+                        return;
+                    }
+                    for (const block of imageBlocks) {
+                        contentBlocks.push({ type: 'image', source: block.source });
+                    }
+                    if (!text.trim()) {
+                        text = `[Image: ${downloaded.filename}]`;
+                    }
+                    transientMediaPath = undefined;
+                }
+                else {
+                    contentBlocks.push({
+                        type: 'text',
+                        text: `[File: ${downloaded.filename}, type: ${downloaded.mimeType}]`,
+                    });
+                    if (!text.trim()) {
+                        text = `[File: ${downloaded.filename}]`;
+                    }
+                    // Documents remain in the private inbound workspace so the routed
+                    // turn and a bounded follow-up can read the actual attachment.
+                    transientMediaPath = undefined;
+                }
+            }
+        }
+        catch {
+            await presenter.fail(msg.document ? 'The file could not be downloaded.' : 'The image could not be downloaded.');
+            return;
+        }
+        finally {
+            if (transientMediaPath) {
+                await (0, promises_1.unlink)(transientMediaPath).catch(() => { });
+            }
+        }
+        if (!text.trim()) {
+            await presenter.fail('This Telegram message type is not supported.');
+            return;
+        }
         if (isForwarded) {
             text = (0, untrusted_content_js_1.wrapUntrustedContent)('telegram-forward', text);
         }
-        if (isGroup && this.botUsername) {
-            const escaped = this.botUsername.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            text = text.replace(new RegExp(`@${escaped}\\b`, 'gi'), '').trim();
-        }
         const sender = msg.from.username || String(msg.from.id);
         console.log(`[Telegram] Message from ${sender} (${text.length} chars)`);
         const memoryLogger = (0, memory_logger_js_1.getMemoryLogger)();
@@ -265,10 +485,12 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
             channelId: String(msg.chat.id),
             userId: String(msg.from.id),
             text,
+            contentBlocks: contentBlocks.length > 0 ? contentBlocks : undefined,
             metadata: {
                 username: msg.from.username,
                 messageId: String(msg.message_id),
                 chatType: msg.chat.type,
+                attachments: attachments.length > 0 ? attachments : undefined,
                 // Trusted provenance flag: downstream strips untrusted blocks ONLY
                 // when the GATEWAY wrapped them - sender-typed markers are not a
                 // security boundary (forgeable in-band data).
@@ -277,118 +499,233 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
         };
         // Typing indicator
         const chatId = String(msg.chat.id);
-        const numChatId = msg.chat.id;
         const sendTyping = () => this.bot?.api.sendChatAction(numChatId, 'typing').catch(() => { });
         sendTyping();
         const typingInterval = setInterval(sendTyping, TYPING_INTERVAL_MS);
-        // ToolStatusTracker for streaming progress
-        const api = this.bot.api;
-        const telegramAdapter = {
-            postPlaceholder: async (content) => {
-                try {
-                    const sent = await api.sendMessage(numChatId, content);
-                    return String(sent.message_id);
-                }
-                catch {
-                    return null;
-                }
-            },
-            editPlaceholder: async (handle, content) => {
-                try {
-                    await api.editMessageText(numChatId, Number(handle), content);
-                }
-                catch {
-                    /* ignore same-text errors */
-                }
-            },
-            deletePlaceholder: async (handle) => {
+        try {
+            // Process through message router
+            let result;
+            this.messageLedger.claim(messageKey);
+            try {
+                result = await this.messageRouter.process(normalizedMessage, {
+                    onStream: presenter.callbacks(),
+                    onQueued: () => presenter.markQueued(),
+                });
+            }
+            catch (error) {
+                const failureNotice = 'An error occurred while processing the message.';
+                this.messageLedger.markReady(messageKey, failureNotice);
                 try {
-                    await api.editMessageText(numChatId, Number(handle), '✅');
+                    await presenter.fail(failureNotice);
+                    this.messageLedger.markDelivered(messageKey);
                 }
                 catch {
-                    /* ignore */
+                    this.recentMessageIds.delete(messageKey);
                 }
-            },
-        };
-        const tracker = new tool_status_tracker_js_1.ToolStatusTracker(telegramAdapter, {
-            throttleMs: 2000,
-            initialDelayMs: 1000,
-        });
-        const streamCallbacks = tracker.toStreamCallbacks();
-        // Process through message router
-        let result;
-        try {
-            result = await this.messageRouter.process(normalizedMessage, {
-                onStream: streamCallbacks,
+                throw error;
+            }
+            this.messageLedger.markReady(messageKey, result.response);
+            try {
+                await presenter.finalize(result.response);
+                this.messageLedger.markDelivered(messageKey);
+            }
+            catch (error) {
+                this.recentMessageIds.delete(messageKey);
+                throw error;
+            }
+            this.lastMessageAt = Date.now();
+            memoryLogger.logMessage('Telegram', 'MAMA', result.response, true);
+            this.emitEvent({
+                type: 'message_sent',
+                source: 'telegram',
+                timestamp: new Date(),
+                data: {
+                    chatId,
+                    responseLength: result.response.length,
+                    duration: result.duration,
+                },
             });
         }
         finally {
             clearInterval(typingInterval);
-            await tracker.cleanup();
         }
-        this.lastMessageAt = Date.now();
-        memoryLogger.logMessage('Telegram', 'MAMA', result.response, true);
-        await this.sendMessage(chatId, result.response);
-        this.emitEvent({
-            type: 'message_sent',
-            source: 'telegram',
-            timestamp: new Date(),
-            data: {
-                chatId,
-                responseLength: result.response.length,
-                duration: result.duration,
-            },
-        });
     }
-    async sendMessage(chatId, text) {
+    async sendMessage(chatId, text, idempotencyKey) {
+        if (!this.bot)
+            throw new Error('Telegram gateway not connected');
+        if (!text.trim())
+            return;
+        await this.runInChatQueue(chatId, () => this.sendMessageNow(chatId, text, idempotencyKey));
+    }
+    async sendMessageFromActiveTurn(chatId, text, idempotencyKey) {
         if (!this.bot)
             throw new Error('Telegram gateway not connected');
         if (!text.trim())
             return;
-        const chunks = this.splitMessage(text, TELEGRAM_MAX_LENGTH);
+        await this.runInChatQueue(chatId, () => this.sendMessageNow(chatId, text, idempotencyKey), true);
+    }
+    async sendMessageNow(chatId, text, idempotencyKey) {
+        const bot = this.bot;
+        if (!bot)
+            throw new Error('Telegram gateway not connected');
+        const chunks = (0, telegram_response_presenter_js_1.splitTelegramMessage)(text, TELEGRAM_MAX_LENGTH);
         const numChatId = Number(chatId);
-        for (const chunk of chunks) {
+        if (!idempotencyKey) {
+            for (const chunk of chunks)
+                await bot.api.sendMessage(numChatId, chunk);
+            return;
+        }
+        const ledgerKey = this.outboundLedgerKey(idempotencyKey, 'text');
+        const existing = this.messageLedger.get(ledgerKey);
+        if (existing?.state === 'delivered')
+            return;
+        if (!existing)
+            this.messageLedger.claim(ledgerKey);
+        let nextIndex = 0;
+        if (existing?.state === 'ready' && existing.response) {
+            const progress = parseOutboundChunkProgress(existing.response);
+            nextIndex = progress.nextIndex;
+            if (progress.uncertain) {
+                console.warn(`[Telegram] Retrying delivery ${ledgerKey} from chunk ${nextIndex} after an ` +
+                    'ambiguous prior acceptance; at-least-once delivery may duplicate that chunk');
+            }
+        }
+        for (let index = nextIndex; index < chunks.length; index += 1) {
+            this.messageLedger.markReady(ledgerKey, JSON.stringify({ version: 1, nextIndex: index, uncertain: true }));
             try {
-                await this.bot.api.sendMessage(numChatId, chunk, { parse_mode: 'Markdown' });
+                await bot.api.sendMessage(numChatId, chunks[index]);
             }
-            catch (err) {
-                // Retry as plain text only for Markdown parse errors (400)
-                const status = err?.error_code;
-                if (status === 400) {
-                    await this.bot.api.sendMessage(numChatId, chunk);
-                }
-                else {
-                    throw err;
+            catch (error) {
+                if (isDefiniteTelegramApiRejection(error)) {
+                    this.messageLedger.markReady(ledgerKey, JSON.stringify({ version: 1, nextIndex: index, uncertain: false }));
                 }
+                throw error;
             }
+            this.messageLedger.markReady(ledgerKey, JSON.stringify({ version: 1, nextIndex: index + 1, uncertain: false }));
         }
+        this.messageLedger.markDelivered(ledgerKey);
+    }
+    async sendFile(chatId, filePath, caption, idempotencyKey) {
+        if (!this.bot)
+            throw new Error('Telegram gateway not connected');
+        const { InputFile } = await import('grammy');
+        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'file', () => this.bot.api.sendDocument(Number(chatId), new InputFile(filePath), { caption }).then(() => { })));
+    }
+    async sendFileFromActiveTurn(chatId, filePath, caption, idempotencyKey) {
+        if (!this.bot)
+            throw new Error('Telegram gateway not connected');
+        const { InputFile } = await import('grammy');
+        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'file', () => this.bot.api.sendDocument(Number(chatId), new InputFile(filePath), { caption }).then(() => { })), true);
     }
-    async sendFile(chatId, filePath, caption) {
+    async sendImage(chatId, imagePath, caption, idempotencyKey) {
         if (!this.bot)
             throw new Error('Telegram gateway not connected');
         const { InputFile } = await import('grammy');
-        await this.bot.api.sendDocument(Number(chatId), new InputFile(filePath), { caption });
+        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'image', () => this.bot.api.sendPhoto(Number(chatId), new InputFile(imagePath), { caption }).then(() => { })));
     }
-    async sendImage(chatId, imagePath, caption) {
+    async sendImageFromActiveTurn(chatId, imagePath, caption, idempotencyKey) {
         if (!this.bot)
             throw new Error('Telegram gateway not connected');
         const { InputFile } = await import('grammy');
-        await this.bot.api.sendPhoto(Number(chatId), new InputFile(imagePath), { caption });
+        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'image', () => this.bot.api.sendPhoto(Number(chatId), new InputFile(imagePath), { caption }).then(() => { })), true);
+    }
+    async sendOutboundOnce(idempotencyKey, kind, send) {
+        if (!idempotencyKey) {
+            await send();
+            return;
+        }
+        const ledgerKey = this.outboundLedgerKey(idempotencyKey, kind);
+        const existing = this.messageLedger.get(ledgerKey);
+        if (existing?.state === 'delivered')
+            return;
+        if (!existing)
+            this.messageLedger.claim(ledgerKey);
+        await send();
+        this.messageLedger.markDelivered(ledgerKey);
+    }
+    async recoverPendingInboundDeliveries() {
+        for (const snapshot of this.messageLedger.listUndelivered()) {
+            if (snapshot.key.startsWith('outbound:'))
+                continue;
+            const separator = snapshot.key.lastIndexOf(':');
+            if (separator <= 0)
+                continue;
+            const chatId = snapshot.key.slice(0, separator);
+            await this.runInChatQueue(chatId, async () => {
+                const entry = this.messageLedger.get(snapshot.key);
+                if (!entry || entry.state === 'delivered')
+                    return;
+                if (entry.state === 'processing' && this.messageLedger.isOwnedByCurrentProcess(entry)) {
+                    return;
+                }
+                const response = entry.state === 'ready' && entry.response !== undefined
+                    ? entry.response
+                    : 'The previous processing attempt was interrupted. It was not rerun because its ' +
+                        'external side effects could not be proven safe to repeat. Please send a new message ' +
+                        'if you want to retry it.';
+                if (entry.state !== 'ready')
+                    this.messageLedger.markReady(entry.key, response);
+                if (entry.deliveryUncertain) {
+                    console.warn(`[Telegram] Resuming inbound delivery ${entry.key} from uncertain chunk ` +
+                        `${entry.nextChunkIndex ?? 0}; that chunk may appear twice`);
+                }
+                const presenter = this.createResponsePresenter(Number(chatId), entry.key, entry.nextChunkIndex ?? 0);
+                await presenter.finalize(response);
+                this.messageLedger.markDelivered(entry.key);
+            });
+        }
+    }
+    createResponsePresenter(chatId, messageKey, resumeFromChunk = 0) {
+        const api = this.bot.api;
+        return new telegram_response_presenter_js_1.TelegramResponsePresenter({
+            send: async (content) => {
+                const sent = await api.sendMessage(chatId, content);
+                return String(sent.message_id);
+            },
+            edit: async (handle, content) => {
+                await api.editMessageText(chatId, Number(handle), content);
+            },
+            delete: async (handle) => {
+                await api.deleteMessage(chatId, Number(handle));
+            },
+        }, {
+            resumeFromChunk,
+            onChunkProgress: (nextIndex, uncertain) => {
+                if (this.messageLedger.get(messageKey)?.state === 'ready') {
+                    this.messageLedger.markDeliveryProgress(messageKey, nextIndex, uncertain);
+                }
+            },
+        });
+    }
+    outboundLedgerKey(idempotencyKey, kind) {
+        const digest = (0, node_crypto_1.createHash)('sha256').update(`${kind}\0${idempotencyKey}`).digest('hex');
+        return `outbound:${digest}`;
     }
     async sendSticker(chatId, emotion) {
         if (!this.bot)
             throw new Error('Telegram gateway not connected');
+        return this.runInChatQueue(String(chatId), () => this.sendStickerNow(chatId, emotion));
+    }
+    async sendStickerFromActiveTurn(chatId, emotion) {
+        if (!this.bot)
+            throw new Error('Telegram gateway not connected');
+        return this.runInChatQueue(String(chatId), () => this.sendStickerNow(chatId, emotion), true);
+    }
+    async sendStickerNow(chatId, emotion) {
+        const bot = this.bot;
+        if (!bot)
+            throw new Error('Telegram gateway not connected');
         await this.loadStickerSet();
         const candidates = EMOTION_EMOJI[emotion] ?? EMOTION_EMOJI.happy;
         const numChatId = typeof chatId === 'string' ? Number(chatId) : chatId;
         for (const emoji of candidates) {
             const fileId = this.stickerCache.get(emoji);
             if (fileId) {
-                await this.bot.api.sendSticker(numChatId, fileId);
+                await bot.api.sendSticker(numChatId, fileId);
                 return true;
             }
         }
-        await this.bot.api.sendMessage(numChatId, candidates[0]);
+        await bot.api.sendMessage(numChatId, candidates[0]);
         return false;
     }
     getLastError() {
@@ -397,23 +734,6 @@ class TelegramGateway extends base_gateway_js_1.BaseGateway {
     getLastMessageAt() {
         return this.lastMessageAt;
     }
-    splitMessage(text, maxLength) {
-        if (text.length <= maxLength)
-            return [text];
-        const chunks = [];
-        let remaining = text;
-        while (remaining.length > 0) {
-            if (remaining.length <= maxLength) {
-                chunks.push(remaining);
-                break;
-            }
-            const newline = remaining.lastIndexOf('\n', maxLength);
-            const splitAt = newline > maxLength * 0.3 ? newline + 1 : maxLength;
-            chunks.push(remaining.slice(0, splitAt));
-            remaining = remaining.slice(splitAt);
-        }
-        return chunks;
-    }
     async loadStickerSet() {
         if (this.stickerSetLoaded || !this.bot)
             return;