@markusylisiurunen/tau 0.2.122 → 0.2.124

package/dist/core/async/telegram.js

@@ -2,7 +2,7 @@ import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, extname, join } from "node:path";
 import { z } from "zod";
-import { transcribeMistralAudio } from "../utils/mistral_transcription.js";
+import { transcribeAudio } from "../utils/speech_to_text.js";
 import { formatZodError } from "../utils/zod.js";
 import { AsyncSessionManagerError, createScopedAsyncSessionManager, } from "./session_manager.js";
 const DEFAULT_POLL_INTERVAL_MS = 1000;
@@ -27,6 +27,7 @@ const MAX_SESSION_PREVIEW_CHARS = 64;
 const MAX_TELEGRAM_ATTACHMENTS_PER_TURN = 10;
 const MAX_TELEGRAM_ATTACHMENT_FILE_BYTES = 20 * 1024 * 1024;
 const MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES = 50 * 1024 * 1024;
+const MAX_TELEGRAM_GROUP_PENDING_MESSAGES = 50;
 const TELEGRAM_ATTACHMENT_TEMP_DIR_PREFIX = "tau-telegram-attachments-";
 const NO_ACTIVE_SESSION_MESSAGE = "no active session. use /new or /sessions";
 const SUPPORTED_TEXT_ATTACHMENT_EXTENSIONS = new Set([
@@ -116,6 +117,75 @@ function stripCommandMention(command) {
     }
     return command.slice(0, mentionIndex);
 }
+function normalizeTelegramUsername(username) {
+    return username.trim().replace(/^@+/, "").toLowerCase();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasTelegramMention(text, username) {
+    const normalizedUsername = normalizeTelegramUsername(username);
+    if (!normalizedUsername) {
+        return false;
+    }
+    const mentionPattern = new RegExp(`(^|[^A-Za-z0-9_])@${escapeRegExp(normalizedUsername)}(?=$|[^A-Za-z0-9_])`, "i");
+    return mentionPattern.test(text);
+}
+function stripTelegramMention(text, username) {
+    const normalizedUsername = normalizeTelegramUsername(username);
+    if (!normalizedUsername) {
+        return text.trim();
+    }
+    const mentionPattern = new RegExp(`(^|[^A-Za-z0-9_])@${escapeRegExp(normalizedUsername)}(?=$|[^A-Za-z0-9_])`, "gi");
+    return text
+        .replace(mentionPattern, (_match, prefix) => prefix)
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function getCommandMention(command) {
+    if (!command.startsWith("/")) {
+        return undefined;
+    }
+    const mentionIndex = command.indexOf("@");
+    if (mentionIndex === -1) {
+        return undefined;
+    }
+    const mention = normalizeTelegramUsername(command.slice(mentionIndex + 1));
+    return mention || undefined;
+}
+function isTelegramMentionToken(part, username) {
+    return normalizeTelegramUsername(part) === username;
+}
+function getMentionedGroupCommandText(text, username) {
+    const parts = splitCommandText(text);
+    const first = parts[0];
+    if (!first) {
+        return undefined;
+    }
+    if (first.startsWith("/")) {
+        const commandMention = getCommandMention(first);
+        if (commandMention && commandMention !== username) {
+            return undefined;
+        }
+        const mentionIndex = parts.findIndex((part) => isTelegramMentionToken(part, username));
+        if (commandMention === username || mentionIndex !== -1) {
+            return parts.filter((_part, index) => index !== mentionIndex).join(" ");
+        }
+        return undefined;
+    }
+    if (!isTelegramMentionToken(first, username)) {
+        return undefined;
+    }
+    const command = parts[1];
+    if (!command?.startsWith("/")) {
+        return undefined;
+    }
+    const commandMention = getCommandMention(command);
+    if (commandMention && commandMention !== username) {
+        return undefined;
+    }
+    return parts.slice(1).join(" ");
+}
 function truncateText(text, maxChars) {
     const trimmed = text.trim();
     if (trimmed.length <= maxChars) {
@@ -256,6 +326,26 @@ function describeAttachment(fileName, mimeType) {
     }
     return "attachment";
 }
+function formatTelegramSender(user) {
+    if (!user) {
+        return "unknown sender";
+    }
+    const firstName = user.first_name?.trim() ?? "";
+    const lastName = user.last_name?.trim() ?? "";
+    const fullName = [firstName, lastName].filter(Boolean).join(" ");
+    const username = user.username?.trim().replace(/^@+/, "");
+    const usernameLabel = username ? `@${username}` : undefined;
+    if (fullName && usernameLabel) {
+        return `${fullName} (${usernameLabel}, id ${user.id})`;
+    }
+    if (fullName) {
+        return `${fullName} (id ${user.id})`;
+    }
+    if (usernameLabel) {
+        return `${usernameLabel} (id ${user.id})`;
+    }
+    return `id ${user.id}`;
+}
 function describeSession(session, details = {}) {
     return [
         formatSessionHeadline(session.id, "status"),
@@ -296,7 +386,12 @@ const TelegramEnvelopeSchema = z.discriminatedUnion("ok", [
     }),
 ]);
 const TelegramChatSchema = telegramObject({ id: z.number(), type: z.string() });
-const TelegramUserSchema = telegramObject({ id: z.number() });
+const TelegramUserSchema = telegramPartialObject({
+    id: z.number(),
+    first_name: z.string(),
+    last_name: z.string(),
+    username: z.string(),
+}).required({ id: true });
 const TELEGRAM_FILE_SHAPE = {
     file_id: z.string(),
     file_name: z.string(),
@@ -340,6 +435,7 @@ const TelegramUpdateSchema = telegramPartialObject({
 });
 const TelegramGetUpdatesResultSchema = z.array(TelegramUpdateSchema);
 const TelegramGetFileResultSchema = z.object({ file_path: z.string() });
+const TelegramGetMeResultSchema = telegramObject({ username: z.string() });
 const TelegramAckResultSchema = z.literal(true);
 function createTelegramApi(botToken) {
     const apiUrl = `https://api.telegram.org/bot${botToken}`;
@@ -370,6 +466,9 @@ function createTelegramApi(botToken) {
         return parseOrThrow(resultSchema, envelope.result, `telegram ${method} returned an invalid result`);
     }
     return {
+        async getMe() {
+            return callTelegramMethod("getMe", {}, TelegramGetMeResultSchema);
+        },
         async getUpdates(args) {
             return callTelegramMethod("getUpdates", {
                 offset: args.offset,
@@ -426,8 +525,11 @@ class AsyncTelegramAdapterImpl {
     systemMessage;
     allowedUserIds;
     allowedChatIds;
+    botUsername;
     pollIntervalMs;
     requestTimeoutSeconds;
+    speechToTextProvider;
+    geminiApiKey;
     mistralApiKey;
     sessionManager;
     enforceChatOwnership;
@@ -448,6 +550,7 @@ class AsyncTelegramAdapterImpl {
     lastAssistantMessageBySession = new Map();
     latestAssistantMessageByRun = new Map();
     pendingAttachmentsBySession = new Map();
+    pendingGroupMessagesByChat = new Map();
     pendingAttachmentTempDirBySession = new Map();
     attachmentTempDirsBySession = new Map();
     updateQueueTailByKey = new Map();
@@ -472,14 +575,17 @@ class AsyncTelegramAdapterImpl {
             options.allowedChatIds && options.allowedChatIds.length > 0
                 ? new Set(options.allowedChatIds)
                 : undefined;
+        this.botUsername = options.botUsername;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.requestTimeoutSeconds = options.requestTimeoutSeconds ?? DEFAULT_REQUEST_TIMEOUT_SECONDS;
+        this.speechToTextProvider = options.speechToTextProvider ?? "mistral";
+        this.geminiApiKey = options.geminiApiKey?.trim() || undefined;
         this.mistralApiKey = options.mistralApiKey?.trim() || undefined;
         this.sessionManager = options.sessionManager;
         this.enforceChatOwnership = true;
         this.botOwnerPrefix = `telegram:${botId}`;
         this.allowedProjectIds = Object.keys(options.projects);
-        this.api = options.api ?? createTelegramApi(options.botToken);
+        this.api = options.api;
         this.fetchImpl = options.fetchImpl;
         this.onLog = options.onLog;
         this.commandDefinitions = this.createCommandDefinitions();
@@ -723,49 +829,104 @@ class AsyncTelegramAdapterImpl {
     async handleUpdate(update) {
         const message = update.message;
         if (message) {
-            const chat = message.chat;
-            if (!chat || chat.type !== "private") {
-                return;
-            }
-            const chatId = chat.id;
-            if (!this.isChatAllowed(chatId)) {
-                return;
-            }
-            const userId = message.from?.id;
-            if (!this.isUserAllowed(userId)) {
-                return;
-            }
-            const text = typeof message.text === "string" ? message.text.trim() : "";
-            const isCommand = text.startsWith("/");
-            if (!isCommand) {
-                await this.queueMessageAttachments(chatId, message);
-            }
-            if (text) {
-                if (isCommand) {
-                    await this.handleCommand(chatId, text);
-                    return;
-                }
-                await this.handleMessage(chatId, text, message.message_id);
+            await this.handleMessageUpdate(message);
+            return;
+        }
+        const callbackQuery = update.callback_query;
+        if (callbackQuery) {
+            await this.handleCallbackQueryUpdate(callbackQuery);
+        }
+    }
+    async handleMessageUpdate(message) {
+        const chat = message.chat;
+        if (!chat) {
+            return;
+        }
+        if (chat.type === "private") {
+            await this.handlePrivateMessage(chat.id, message);
+            return;
+        }
+        if (chat.type === "group" || chat.type === "supergroup") {
+            await this.handleGroupMessage(chat.id, message);
+        }
+    }
+    async handlePrivateMessage(chatId, message) {
+        if (!this.isChatAllowed(chatId)) {
+            return;
+        }
+        const userId = message.from?.id;
+        if (!this.isUserAllowed(userId)) {
+            return;
+        }
+        const text = typeof message.text === "string" ? message.text.trim() : "";
+        const isCommand = text.startsWith("/");
+        if (!isCommand) {
+            await this.queueMessageAttachments(chatId, message);
+        }
+        if (text) {
+            if (isCommand) {
+                await this.handleCommand(chatId, text);
                 return;
             }
-            const audioMessage = this.parseAudioMessage(message);
-            if (!audioMessage) {
+            await this.handleMessage(chatId, text, message.message_id);
+            return;
+        }
+        const audioMessage = this.parseAudioMessage(message);
+        if (!audioMessage) {
+            return;
+        }
+        await this.handleAudioMessage(chatId, audioMessage, message.message_id);
+    }
+    async handleGroupMessage(chatId, message) {
+        if (!this.isGroupChatAllowed(chatId)) {
+            return;
+        }
+        const text = typeof message.text === "string" ? message.text.trim() : "";
+        const caption = typeof message.caption === "string" ? message.caption.trim() : "";
+        const contentText = text || caption;
+        const groupCommandText = getMentionedGroupCommandText(text, this.botUsername);
+        if (groupCommandText) {
+            if (!this.isUserAllowed(message.from?.id)) {
                 return;
             }
-            await this.handleAudioMessage(chatId, audioMessage, message.message_id);
+            await this.handleCommand(chatId, groupCommandText);
             return;
         }
-        const callbackQuery = update.callback_query;
-        if (!callbackQuery) {
+        if (text.startsWith("/")) {
+            this.bufferGroupMessage(chatId, message, text);
             return;
         }
+        const attachmentResult = await this.queueMessageAttachments(chatId, message, { silent: true });
+        const audioMessage = this.parseAudioMessage(message);
+        const audioResult = audioMessage
+            ? await this.transcribeTelegramAudio(chatId, audioMessage, { silent: true })
+            : {};
+        const errors = [...attachmentResult.errors, ...(audioResult.error ? [audioResult.error] : [])];
+        if (!contentText && !audioResult.transcript && errors.length === 0) {
+            this.bufferGroupMessage(chatId, message, undefined, undefined, attachmentResult.attachments, errors);
+            return;
+        }
+        if (!hasTelegramMention(contentText, this.botUsername)) {
+            this.bufferGroupMessage(chatId, message, contentText, audioResult.transcript, attachmentResult.attachments, errors);
+            return;
+        }
+        if (!this.isUserAllowed(message.from?.id)) {
+            this.bufferGroupMessage(chatId, message, contentText, audioResult.transcript, attachmentResult.attachments, errors);
+            return;
+        }
+        const triggerText = stripTelegramMention(contentText, this.botUsername);
+        await this.handleGroupTriggeredMessage(chatId, message, triggerText, message.message_id, attachmentResult.attachments, audioResult.transcript, errors);
+    }
+    async handleCallbackQueryUpdate(callbackQuery) {
         const chat = callbackQuery.message?.chat;
-        if (!chat || chat.type !== "private") {
+        if (!chat) {
             await this.answerCallbackQuery(callbackQuery.id);
             return;
         }
-        const chatId = chat.id;
-        if (!this.isChatAllowed(chatId)) {
+        const isAllowedChat = chat.type === "private"
+            ? this.isChatAllowed(chat.id)
+            : (chat.type === "group" || chat.type === "supergroup") && this.isGroupChatAllowed(chat.id);
+        if (!isAllowedChat) {
             await this.answerCallbackQuery(callbackQuery.id);
             return;
         }
@@ -778,7 +939,7 @@ class AsyncTelegramAdapterImpl {
             await this.answerCallbackQuery(callbackQuery.id);
             return;
         }
-        const callbackHandled = await this.handleCallback(chatId, callbackData);
+        const callbackHandled = await this.handleCallback(chat.id, callbackData);
         await this.answerCallbackQuery(callbackQuery.id, callbackHandled ? "done" : undefined);
     }
     parseAudioMessage(message) {
@@ -800,7 +961,8 @@ class AsyncTelegramAdapterImpl {
             fileName: message.audio?.file_name?.trim() || DEFAULT_TELEGRAM_AUDIO_FILE_NAME,
         };
     }
-    async queueMessageAttachments(chatId, message) {
+    async queueMessageAttachments(chatId, message, options = {}) {
+        const result = { attachments: [], errors: [] };
         const caption = typeof message.caption === "string" ? message.caption.trim() : "";
         const attachmentCaption = caption || undefined;
         const parsedAttachments = [];
@@ -834,7 +996,13 @@ class AsyncTelegramAdapterImpl {
                 rawMimeType ??
                 DEFAULT_TELEGRAM_DOCUMENT_MIME_TYPE;
             if (!isSupportedDocumentAttachment(mimeType, fileName)) {
-                await this.reply(chatId, `skipped attachment ${describeAttachment(fileName, mimeType)}: unsupported file type`);
+                const errorMessage = `skipped attachment ${describeAttachment(fileName, mimeType)}: unsupported file type`;
+                if (options.silent) {
+                    result.errors.push(errorMessage);
+                }
+                else {
+                    await this.reply(chatId, errorMessage);
+                }
             }
             else {
                 parsedAttachments.push({
@@ -847,11 +1015,16 @@ class AsyncTelegramAdapterImpl {
             }
         }
         if (parsedAttachments.length === 0) {
-            return;
+            return result;
         }
-        const session = await this.requireActiveOrSingleSession(chatId);
+        const session = options.silent
+            ? this.getActiveOrSingleSession(chatId)
+            : await this.requireActiveOrSingleSession(chatId);
         if (!session) {
-            return;
+            if (options.silent) {
+                result.errors.push(NO_ACTIVE_SESSION_MESSAGE);
+            }
+            return result;
         }
         const pending = this.pendingAttachmentsBySession.get(session.id) ?? [];
         let totalSizeBytes = pending.reduce((total, attachment) => {
@@ -860,21 +1033,37 @@ class AsyncTelegramAdapterImpl {
         for (const attachment of parsedAttachments) {
             const attachmentLabel = describeAttachment(attachment.fileName, attachment.mimeType);
             if (pending.length >= MAX_TELEGRAM_ATTACHMENTS_PER_TURN) {
-                await this.replySkippedAttachment(chatId, attachmentLabel, `exceeds attachment limit (${MAX_TELEGRAM_ATTACHMENTS_PER_TURN} files per turn)`);
+                const reason = `exceeds attachment limit (${MAX_TELEGRAM_ATTACHMENTS_PER_TURN} files per turn)`;
+                if (options.silent) {
+                    result.errors.push(`skipped attachment ${attachmentLabel}: ${reason}`);
+                }
+                else {
+                    await this.replySkippedAttachment(chatId, attachmentLabel, reason);
+                }
                 continue;
             }
             const declaredFileLimitReason = typeof attachment.sizeBytes === "number"
                 ? this.getAttachmentPerFileLimitReason(attachment.sizeBytes)
                 : undefined;
             if (declaredFileLimitReason) {
-                await this.replySkippedAttachment(chatId, attachmentLabel, declaredFileLimitReason);
+                if (options.silent) {
+                    result.errors.push(`skipped attachment ${attachmentLabel}: ${declaredFileLimitReason}`);
+                }
+                else {
+                    await this.replySkippedAttachment(chatId, attachmentLabel, declaredFileLimitReason);
+                }
                 continue;
             }
             const declaredTotalLimitReason = typeof attachment.sizeBytes === "number"
                 ? this.getAttachmentTotalLimitReason(totalSizeBytes, attachment.sizeBytes)
                 : undefined;
             if (declaredTotalLimitReason) {
-                await this.replySkippedAttachment(chatId, attachmentLabel, declaredTotalLimitReason);
+                if (options.silent) {
+                    result.errors.push(`skipped attachment ${attachmentLabel}: ${declaredTotalLimitReason}`);
+                }
+                else {
+                    await this.replySkippedAttachment(chatId, attachmentLabel, declaredTotalLimitReason);
+                }
                 continue;
             }
             let bytes;
@@ -882,18 +1071,34 @@ class AsyncTelegramAdapterImpl {
                 bytes = await this.api.downloadFile(attachment.fileId);
             }
             catch (error) {
-                await this.reply(chatId, `failed to download attachment ${attachmentLabel}: ${this.formatManagerError(error)}`);
+                const errorMessage = `failed to download attachment ${attachmentLabel}: ${this.formatManagerError(error)}`;
+                if (options.silent) {
+                    result.errors.push(errorMessage);
+                }
+                else {
+                    await this.reply(chatId, errorMessage);
+                }
                 continue;
             }
             const sizeBytes = bytes.byteLength;
             const fileLimitReason = this.getAttachmentPerFileLimitReason(sizeBytes);
             if (fileLimitReason) {
-                await this.replySkippedAttachment(chatId, attachmentLabel, fileLimitReason);
+                if (options.silent) {
+                    result.errors.push(`skipped attachment ${attachmentLabel}: ${fileLimitReason}`);
+                }
+                else {
+                    await this.replySkippedAttachment(chatId, attachmentLabel, fileLimitReason);
+                }
                 continue;
             }
             const totalLimitReason = this.getAttachmentTotalLimitReason(totalSizeBytes, sizeBytes);
             if (totalLimitReason) {
-                await this.replySkippedAttachment(chatId, attachmentLabel, totalLimitReason);
+                if (options.silent) {
+                    result.errors.push(`skipped attachment ${attachmentLabel}: ${totalLimitReason}`);
+                }
+                else {
+                    await this.replySkippedAttachment(chatId, attachmentLabel, totalLimitReason);
+                }
                 continue;
             }
             const tempDirPath = await this.getOrCreatePendingAttachmentTempDir(session.id);
@@ -903,9 +1108,21 @@ class AsyncTelegramAdapterImpl {
                 await writeFile(filePath, bytes);
             }
             catch (error) {
-                await this.reply(chatId, `failed to materialize attachment ${attachmentLabel}: ${this.formatManagerError(error)}`);
+                const errorMessage = `failed to materialize attachment ${attachmentLabel}: ${this.formatManagerError(error)}`;
+                if (options.silent) {
+                    result.errors.push(errorMessage);
+                }
+                else {
+                    await this.reply(chatId, errorMessage);
+                }
                 continue;
             }
+            const materializedAttachment = {
+                path: filePath,
+                mimeType: attachment.mimeType,
+                sizeBytes,
+                ...(attachment.caption ? { caption: attachment.caption } : {}),
+            };
             pending.push({
                 fileId: attachment.fileId,
                 fileName: attachment.fileName,
@@ -917,18 +1134,32 @@ class AsyncTelegramAdapterImpl {
                     sizeBytes,
                 },
             });
+            result.attachments.push(materializedAttachment);
             totalSizeBytes += sizeBytes;
         }
         if (pending.length > 0) {
             this.pendingAttachmentsBySession.set(session.id, pending);
         }
+        return result;
     }
     async buildMessageTextWithAttachments(sessionId, text, chatId) {
         const attachments = await this.materializePendingAttachments(sessionId, chatId);
         if (attachments.length === 0) {
             return text;
         }
-        return [this.formatAttachmentBlock(attachments), text].join("\n\n");
+        const attachmentBlock = this.formatAttachmentBlock(attachments);
+        const systemEndIndex = text.startsWith("<system>") ? text.indexOf("</system>") : -1;
+        if (systemEndIndex !== -1) {
+            const systemBlockEnd = systemEndIndex + "</system>".length;
+            return [
+                text.slice(0, systemBlockEnd),
+                attachmentBlock,
+                text.slice(systemBlockEnd).trimStart(),
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+        }
+        return [attachmentBlock, text].join("\n\n");
     }
     formatAttachmentBlock(attachments) {
         const lines = ["attachments:"];
@@ -1029,6 +1260,9 @@ class AsyncTelegramAdapterImpl {
         }
         return this.allowedChatIds.has(chatId);
     }
+    isGroupChatAllowed(chatId) {
+        return this.allowedChatIds?.has(chatId) ?? false;
+    }
     isUserAllowed(userId) {
         if (!this.allowedUserIds) {
             return true;
@@ -1375,20 +1609,143 @@ class AsyncTelegramAdapterImpl {
             await this.reply(chatId, this.formatManagerError(error));
         }
     }
-    async handleAudioMessage(chatId, message, sourceMessageId) {
+    async handleGroupTriggeredMessage(chatId, message, triggerText, sourceMessageId, attachments = [], audioTranscript, errors = []) {
         const session = await this.requireActiveOrSingleSession(chatId);
         if (!session) {
             return;
         }
-        if (!this.mistralApiKey) {
-            await this.reply(chatId, "set MISTRAL_API_KEY or apiKeys.mistral to transcribe Telegram audio");
+        try {
+            const text = this.formatGroupTurnText(chatId, message, triggerText, attachments, audioTranscript, errors);
+            const processingErrors = this.collectGroupProcessingErrors(chatId, errors);
+            await this.submitSessionMessage(chatId, session.id, text, sourceMessageId, {
+                includePendingAttachments: false,
+            });
+            this.pendingGroupMessagesByChat.delete(chatId);
+            await this.notifyGroupProcessingErrors(chatId, processingErrors);
+        }
+        catch (error) {
+            await this.reply(chatId, this.formatManagerError(error));
+        }
+    }
+    bufferGroupMessage(chatId, message, text, audioTranscript, attachments = [], errors = []) {
+        const trimmedText = text?.trim();
+        const trimmedAudioTranscript = audioTranscript?.trim();
+        if (!trimmedText &&
+            !trimmedAudioTranscript &&
+            attachments.length === 0 &&
+            errors.length === 0) {
             return;
         }
+        const pending = this.pendingGroupMessagesByChat.get(chatId) ?? [];
+        pending.push({
+            sender: formatTelegramSender(message.from),
+            ...(trimmedText ? { text: trimmedText } : {}),
+            ...(trimmedAudioTranscript ? { audioTranscript: trimmedAudioTranscript } : {}),
+            ...(attachments.length > 0 ? { attachments } : {}),
+            ...(errors.length > 0 ? { errors } : {}),
+        });
+        if (pending.length > MAX_TELEGRAM_GROUP_PENDING_MESSAGES) {
+            pending.splice(0, pending.length - MAX_TELEGRAM_GROUP_PENDING_MESSAGES);
+        }
+        this.pendingGroupMessagesByChat.set(chatId, pending);
+    }
+    collectGroupProcessingErrors(chatId, triggerErrors) {
+        const pending = this.pendingGroupMessagesByChat.get(chatId) ?? [];
+        return [...pending.flatMap((message) => message.errors ?? []), ...triggerErrors];
+    }
+    async notifyGroupProcessingErrors(chatId, errors) {
+        if (errors.length === 0) {
+            return;
+        }
+        const visibleErrors = errors.slice(0, 5).map((error) => `- ${truncateText(error, 160)}`);
+        if (errors.length > visibleErrors.length) {
+            visibleErrors.push(`- and ${errors.length - visibleErrors.length} more`);
+        }
+        await this.reply(chatId, ["some Telegram group context could not be processed:", ...visibleErrors].join("\n"));
+    }
+    formatGroupTurnText(chatId, message, triggerText, triggerAttachments = [], triggerAudioTranscript, triggerErrors = []) {
+        const pending = this.pendingGroupMessagesByChat.get(chatId) ?? [];
+        const lines = [
+            "<system>",
+            pending.length > 0
+                ? "This message came from a Telegram group chat. The <telegram-group-context> block contains recent non-triggering group messages, attachments, audio transcripts, and processing errors since the previous bot-triggering turn. Use it as background context only. The <telegram-trigger-message> block is the message that explicitly mentioned the bot and triggered this turn. Respond to the trigger message."
+                : "This message came from a Telegram group chat. The <telegram-trigger-message> block is the message that explicitly mentioned the bot and triggered this turn. Respond to the trigger message.",
+            "</system>",
+            "",
+        ];
+        if (pending.length > 0) {
+            lines.push("<telegram-group-context>");
+            for (const [index, pendingMessage] of pending.entries()) {
+                lines.push(`${index + 1}. sender: ${pendingMessage.sender}`);
+                if (pendingMessage.text) {
+                    lines.push(`   text: ${JSON.stringify(pendingMessage.text)}`);
+                }
+                if (pendingMessage.audioTranscript) {
+                    lines.push(`   audio_transcript: ${JSON.stringify(pendingMessage.audioTranscript)}`);
+                }
+                this.pushIndentedErrorLines(lines, pendingMessage.errors, "   ");
+                this.pushIndentedAttachmentLines(lines, pendingMessage.attachments, "   ");
+            }
+            lines.push("</telegram-group-context>");
+            lines.push("");
+        }
+        lines.push("<telegram-trigger-message>");
+        lines.push(`sender: ${formatTelegramSender(message.from)}`);
+        lines.push(`text: ${JSON.stringify(triggerText)}`);
+        if (triggerAudioTranscript) {
+            lines.push(`audio_transcript: ${JSON.stringify(triggerAudioTranscript)}`);
+        }
+        this.pushIndentedErrorLines(lines, triggerErrors, "");
+        this.pushIndentedAttachmentLines(lines, triggerAttachments, "");
+        lines.push("</telegram-trigger-message>");
+        return lines.join("\n");
+    }
+    pushIndentedErrorLines(lines, errors, indent) {
+        if (!errors || errors.length === 0) {
+            return;
+        }
+        lines.push(`${indent}errors:`);
+        for (const error of errors) {
+            lines.push(`${indent}- ${JSON.stringify(error)}`);
+        }
+    }
+    pushIndentedAttachmentLines(lines, attachments, indent) {
+        if (!attachments || attachments.length === 0) {
+            return;
+        }
+        lines.push(`${indent}attachments:`);
+        for (const attachment of attachments) {
+            lines.push(`${indent}- path: ${attachment.path}`);
+            lines.push(`${indent}  mime: ${attachment.mimeType}`);
+            lines.push(`${indent}  size_bytes: ${attachment.sizeBytes}`);
+            if (attachment.caption) {
+                lines.push(`${indent}  caption: ${JSON.stringify(attachment.caption)}`);
+            }
+        }
+    }
+    getSpeechToTextApiKey() {
+        return this.speechToTextProvider === "gemini" ? this.geminiApiKey : this.mistralApiKey;
+    }
+    getSpeechToTextApiKeyErrorMessage(action) {
+        return this.speechToTextProvider === "gemini"
+            ? `set GEMINI_API_KEY or apiKeys.google to ${action}`
+            : `set MISTRAL_API_KEY or apiKeys.mistral to ${action}`;
+    }
+    async transcribeTelegramAudio(chatId, message, options = {}) {
+        const apiKey = this.getSpeechToTextApiKey();
+        if (!apiKey) {
+            const error = this.getSpeechToTextApiKeyErrorMessage("transcribe Telegram audio");
+            if (!options.silent) {
+                await this.reply(chatId, error);
+            }
+            return { error };
+        }
         let transcript = "";
         try {
             const audio = await this.api.downloadFile(message.fileId);
-            transcript = (await transcribeMistralAudio({
-                apiKey: this.mistralApiKey,
+            transcript = (await transcribeAudio({
+                provider: this.speechToTextProvider,
+                apiKey,
                 audio,
                 fileName: message.fileName,
                 mimeType: message.mimeType,
@@ -1396,15 +1753,32 @@ class AsyncTelegramAdapterImpl {
             })).trim();
         }
         catch (error) {
-            await this.reply(chatId, `audio transcription failed: ${this.formatManagerError(error)}`);
-            return;
+            const errorMessage = `audio transcription failed: ${this.formatManagerError(error)}`;
+            if (!options.silent) {
+                await this.reply(chatId, errorMessage);
+            }
+            return { error: errorMessage };
         }
         if (!transcript) {
-            await this.reply(chatId, "audio transcription failed: transcription result was empty");
+            const error = "audio transcription failed: transcription result was empty";
+            if (!options.silent) {
+                await this.reply(chatId, error);
+            }
+            return { error };
+        }
+        return { transcript };
+    }
+    async handleAudioMessage(chatId, message, sourceMessageId) {
+        const session = await this.requireActiveOrSingleSession(chatId);
+        if (!session) {
+            return;
+        }
+        const result = await this.transcribeTelegramAudio(chatId, message);
+        if (!result.transcript) {
             return;
         }
         try {
-            await this.submitSessionMessage(chatId, session.id, transcript, sourceMessageId);
+            await this.submitSessionMessage(chatId, session.id, result.transcript, sourceMessageId);
         }
         catch (error) {
             await this.reply(chatId, this.formatManagerError(error));
@@ -1426,8 +1800,10 @@ class AsyncTelegramAdapterImpl {
         }
         return session;
     }
-    async submitSessionMessage(chatId, sessionId, text, sourceMessageId) {
-        const textWithAttachments = await this.buildMessageTextWithAttachments(sessionId, text, chatId);
+    async submitSessionMessage(chatId, sessionId, text, sourceMessageId, options = {}) {
+        const textWithAttachments = options.includePendingAttachments === false
+            ? text
+            : await this.buildMessageTextWithAttachments(sessionId, text, chatId);
         const sessionManager = this.getSessionManagerForChat(chatId);
         await sessionManager.sendMessage(sessionId, textWithAttachments, this.systemMessage ? { additionalSystemMessage: this.systemMessage } : undefined);
         this.resetPendingAttachmentQueue(sessionId);
@@ -1729,7 +2105,16 @@ class AsyncTelegramAdapterImpl {
 }
 export async function startAsyncTelegramAdapter(options) {
     await sweepStaleTelegramAttachmentTempDirs();
-    const adapter = new AsyncTelegramAdapterImpl(options);
+    const api = options.api ?? createTelegramApi(options.botToken);
+    const botUsername = normalizeTelegramUsername((await api.getMe()).username);
+    if (!botUsername) {
+        throw new Error("telegram bot username is missing");
+    }
+    const adapter = new AsyncTelegramAdapterImpl({
+        ...options,
+        api,
+        botUsername,
+    });
     return {
         close: () => adapter.close(),
     };