@markusylisiurunen/tau 0.2.63 → 0.2.65

package/dist/core/async/telegram.js

@@ -1,8 +1,9 @@
 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 { isRecord } from "../utils/type_guards.js";
+import { formatZodError } from "../utils/zod.js";
 import { AsyncSessionManagerError, createScopedAsyncSessionManager, } from "./session_manager.js";
 const DEFAULT_POLL_INTERVAL_MS = 1000;
 const DEFAULT_REQUEST_TIMEOUT_SECONDS = 30;
@@ -23,6 +24,7 @@ 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 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([
     ".txt",
     ".md",
@@ -91,17 +93,10 @@ async function sweepStaleTelegramAttachmentTempDirs() {
         return;
     }
 }
-const TELEGRAM_COMMANDS = [
-    { command: "help", description: "show supported commands" },
-    { command: "new", description: "start a new session" },
-    { command: "projects", description: "list configured projects" },
-    { command: "use", description: "switch active session" },
-    { command: "sessions", description: "list sessions" },
-    { command: "status", description: "show active session status" },
-    { command: "interrupt", description: "interrupt active run" },
-    { command: "close", description: "close session(s)" },
-    { command: "verbose", description: "stream progress updates" },
-    { command: "quiet", description: "only send final assistant message" },
+const QUICK_ACTION_ROWS = [
+    ["new", "sessions", "status"],
+    ["interrupt", "close"],
+    ["quiet", "verbose"],
 ];
 function splitCommandText(text) {
     return text
@@ -251,9 +246,76 @@ function describeSession(session, details = {}) {
 function formatSessionHeadline(sessionId, label) {
     return `(${sessionId}) ${label}`;
 }
+const telegramObject = (shape) => z.object(shape).passthrough();
+const telegramPartialObject = (shape) => telegramObject(shape).partial();
+function parseOrThrow(schema, raw, message) {
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`${message}: ${formatZodError(parsed.error)}`);
+    }
+    return parsed.data;
+}
+const TelegramEnvelopeSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        description: z.string().optional(),
+        result: z.unknown(),
+    }),
+    z.object({
+        ok: z.literal(false),
+        description: z.string().optional(),
+        result: z.unknown().optional(),
+    }),
+]);
+const TelegramChatSchema = telegramObject({ id: z.number(), type: z.string() });
+const TelegramUserSchema = telegramObject({ id: z.number() });
+const TELEGRAM_FILE_SHAPE = {
+    file_id: z.string(),
+    file_name: z.string(),
+    mime_type: z.string(),
+    file_size: z.number(),
+};
+const TelegramFileSchema = telegramPartialObject(TELEGRAM_FILE_SHAPE);
+const TelegramPhotoVariantSchema = telegramPartialObject({
+    file_id: z.string(),
+    file_size: z.number(),
+    width: z.number(),
+    height: z.number(),
+});
+const TelegramVoiceSchema = TelegramFileSchema.pick({ file_id: true, mime_type: true });
+const TelegramAudioSchema = TelegramFileSchema.pick({
+    file_id: true,
+    mime_type: true,
+    file_name: true,
+});
+const TelegramMessageSchema = telegramPartialObject({
+    message_id: z.number(),
+    chat: TelegramChatSchema,
+    from: TelegramUserSchema,
+    text: z.string(),
+    caption: z.string(),
+    photo: z.array(TelegramPhotoVariantSchema),
+    document: TelegramFileSchema,
+    voice: TelegramVoiceSchema,
+    audio: TelegramAudioSchema,
+});
+const TelegramCallbackQuerySchema = telegramPartialObject({
+    id: z.string(),
+    from: TelegramUserSchema,
+    data: z.string(),
+    message: telegramPartialObject({ chat: TelegramChatSchema }),
+});
+const TelegramUpdateSchema = telegramPartialObject({
+    update_id: z.number(),
+    message: TelegramMessageSchema,
+    callback_query: TelegramCallbackQuerySchema,
+});
+const TelegramGetUpdatesResultSchema = z.array(TelegramUpdateSchema);
+const TelegramGetFileResultSchema = z.object({ file_path: z.string() });
+const TelegramAckResultSchema = z.literal(true);
 function createTelegramApi(botToken) {
     const apiUrl = `https://api.telegram.org/bot${botToken}`;
-    async function callTelegramMethod(method, payload) {
+    async function callTelegramMethod(method, payload, resultSchema) {
         const response = await fetch(`${apiUrl}/${method}`, {
             method: "POST",
             headers: {
@@ -265,43 +327,40 @@ function createTelegramApi(botToken) {
             const detail = (await response.text()).trim();
             throw new Error(detail || `telegram ${method} failed: HTTP ${response.status}`);
         }
-        let data;
+        let raw;
         try {
-            data = await response.json();
+            raw = await response.json();
         }
         catch {
             throw new Error(`telegram ${method} returned invalid JSON`);
         }
-        if (!isRecord(data)) {
-            throw new Error(`telegram ${method} returned an invalid response payload`);
-        }
-        if (data.ok !== true) {
-            const detail = typeof data.description === "string" ? data.description.trim() : "";
+        const envelope = parseOrThrow(TelegramEnvelopeSchema, raw, `telegram ${method} returned an invalid response payload`);
+        if (!envelope.ok) {
+            const detail = envelope.description?.trim() ?? "";
             throw new Error(detail || `telegram ${method} request failed`);
         }
-        return data.result;
+        return parseOrThrow(resultSchema, envelope.result, `telegram ${method} returned an invalid result`);
     }
     return {
         async getUpdates(args) {
-            const updates = await callTelegramMethod("getUpdates", {
+            return callTelegramMethod("getUpdates", {
                 offset: args.offset,
                 timeout: args.timeoutSeconds,
                 allowed_updates: args.allowedUpdates,
-            });
-            return updates;
+            }, TelegramGetUpdatesResultSchema);
         },
         async sendMessage(chatId, text, options) {
             await callTelegramMethod("sendMessage", {
                 chat_id: chatId,
                 text,
                 ...(options?.replyMarkup ? { reply_markup: options.replyMarkup } : {}),
-            });
+            }, z.unknown());
         },
         async downloadFile(fileId) {
-            const file = await callTelegramMethod("getFile", {
+            const parsed = await callTelegramMethod("getFile", {
                 file_id: fileId,
-            });
-            const filePath = file.file_path?.trim();
+            }, TelegramGetFileResultSchema);
+            const filePath = parsed.file_path?.trim();
             if (!filePath) {
                 throw new Error("telegram file path is missing");
             }
@@ -316,20 +375,20 @@ function createTelegramApi(botToken) {
         async setCommands(commands) {
             await callTelegramMethod("setMyCommands", {
                 commands,
-            });
+            }, TelegramAckResultSchema);
         },
         async setMessageReaction(chatId, messageId) {
             await callTelegramMethod("setMessageReaction", {
                 chat_id: chatId,
                 message_id: messageId,
                 reaction: [{ type: "emoji", emoji: MESSAGE_QUEUED_REACTION_EMOJI }],
-            });
+            }, TelegramAckResultSchema);
         },
         async answerCallbackQuery(callbackQueryId, text) {
             await callTelegramMethod("answerCallbackQuery", {
                 callback_query_id: callbackQueryId,
                 ...(text ? { text } : {}),
-            });
+            }, TelegramAckResultSchema);
         },
     };
 }
@@ -349,6 +408,9 @@ class AsyncTelegramAdapterImpl {
     api;
     fetchImpl;
     onLog;
+    commandDefinitions;
+    commandHandlers;
+    callbackActionHandlers;
     abortController = new AbortController();
     activeSessionsByChat = new Map();
     sessionsByChat = new Map();
@@ -390,6 +452,15 @@ class AsyncTelegramAdapterImpl {
         this.api = options.api ?? createTelegramApi(options.botToken);
         this.fetchImpl = options.fetchImpl;
         this.onLog = options.onLog;
+        this.commandDefinitions = this.createCommandDefinitions();
+        this.commandHandlers = new Map();
+        this.callbackActionHandlers = new Map();
+        for (const definition of this.commandDefinitions) {
+            this.commandHandlers.set(definition.command, definition.handler);
+            if (definition.callbackAction) {
+                this.callbackActionHandlers.set(definition.callbackAction, definition.handler);
+            }
+        }
         this.unsubscribeSessionEvents = this.sessionManager.onEvent((event) => {
             this.onSessionEvent(event);
         });
@@ -422,13 +493,88 @@ class AsyncTelegramAdapterImpl {
     log(level, message, data) {
         this.onLog?.({ level, message, ...(data === undefined ? {} : { data }) });
     }
+    createCommandDefinitions() {
+        return [
+            {
+                command: "/help",
+                description: "show supported commands",
+                usage: "/help",
+                handler: async (chatId) => this.handleHelp(chatId),
+            },
+            {
+                command: "/new",
+                description: "start a new session",
+                usage: "/new [projectId]",
+                callbackAction: "new",
+                handler: async (chatId, args) => this.handleNew(chatId, args),
+            },
+            {
+                command: "/projects",
+                description: "list configured projects",
+                usage: "/projects",
+                handler: async (chatId) => this.handleProjects(chatId),
+            },
+            {
+                command: "/use",
+                description: "switch active session",
+                usage: "/use <sessionId|prefix|index>",
+                handler: async (chatId, args) => this.handleUse(chatId, args),
+            },
+            {
+                command: "/sessions",
+                description: "list sessions",
+                usage: "/sessions",
+                callbackAction: "sessions",
+                handler: async (chatId) => this.handleSessions(chatId),
+            },
+            {
+                command: "/status",
+                description: "show active session status",
+                usage: "/status",
+                callbackAction: "status",
+                handler: async (chatId) => this.handleStatus(chatId),
+            },
+            {
+                command: "/interrupt",
+                description: "interrupt active run",
+                usage: "/interrupt",
+                callbackAction: "interrupt",
+                handler: async (chatId) => this.handleInterrupt(chatId),
+            },
+            {
+                command: "/close",
+                description: "close session(s)",
+                usage: "/close [<sessionId>|all]",
+                callbackAction: "close",
+                handler: async (chatId, args) => this.handleClose(chatId, args),
+            },
+            {
+                command: "/verbose",
+                description: "stream progress updates",
+                usage: "/verbose",
+                callbackAction: "verbose",
+                handler: async (chatId) => this.handleVerbosityCommand(chatId, "verbose"),
+            },
+            {
+                command: "/quiet",
+                description: "only send final assistant message",
+                usage: "/quiet",
+                callbackAction: "quiet",
+                handler: async (chatId) => this.handleVerbosityCommand(chatId, "quiet"),
+            },
+        ];
+    }
     async syncCommands() {
         if (!this.api.setCommands) {
             return;
         }
+        const commands = this.commandDefinitions.map((definition) => ({
+            command: definition.command.slice(1),
+            description: definition.description,
+        }));
         try {
-            await this.api.setCommands(TELEGRAM_COMMANDS);
-            this.log("info", "telegram commands synced", { count: TELEGRAM_COMMANDS.length });
+            await this.api.setCommands(commands);
+            this.log("info", "telegram commands synced", { count: commands.length });
         }
         catch (error) {
             this.log("warn", "failed to sync telegram commands", {
@@ -471,7 +617,7 @@ class AsyncTelegramAdapterImpl {
         if (updates === undefined) {
             return [];
         }
-        return updates.filter((entry) => isRecord(entry));
+        return updates;
     }
     async raceWithAbort(promise) {
         if (this.abortController.signal.aborted) {
@@ -624,9 +770,8 @@ class AsyncTelegramAdapterImpl {
         if (parsedAttachments.length === 0) {
             return;
         }
-        const session = this.getActiveOrSingleSession(chatId);
+        const session = await this.requireActiveOrSingleSession(chatId);
         if (!session) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
             return;
         }
         const pending = this.pendingAttachmentsBySession.get(session.id) ?? [];
@@ -636,17 +781,21 @@ class AsyncTelegramAdapterImpl {
         for (const attachment of parsedAttachments) {
             const attachmentLabel = describeAttachment(attachment.fileName, attachment.mimeType);
             if (pending.length >= MAX_TELEGRAM_ATTACHMENTS_PER_TURN) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds attachment limit (${MAX_TELEGRAM_ATTACHMENTS_PER_TURN} files per turn)`);
+                await this.replySkippedAttachment(chatId, attachmentLabel, `exceeds attachment limit (${MAX_TELEGRAM_ATTACHMENTS_PER_TURN} files per turn)`);
                 continue;
             }
-            if (typeof attachment.sizeBytes === "number" &&
-                attachment.sizeBytes > MAX_TELEGRAM_ATTACHMENT_FILE_BYTES) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds per-file limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_FILE_BYTES)})`);
+            const declaredFileLimitReason = typeof attachment.sizeBytes === "number"
+                ? this.getAttachmentPerFileLimitReason(attachment.sizeBytes)
+                : undefined;
+            if (declaredFileLimitReason) {
+                await this.replySkippedAttachment(chatId, attachmentLabel, declaredFileLimitReason);
                 continue;
             }
-            if (typeof attachment.sizeBytes === "number" &&
-                totalSizeBytes + attachment.sizeBytes > MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds per-turn total limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES)})`);
+            const declaredTotalLimitReason = typeof attachment.sizeBytes === "number"
+                ? this.getAttachmentTotalLimitReason(totalSizeBytes, attachment.sizeBytes)
+                : undefined;
+            if (declaredTotalLimitReason) {
+                await this.replySkippedAttachment(chatId, attachmentLabel, declaredTotalLimitReason);
                 continue;
             }
             let bytes;
@@ -658,12 +807,14 @@ class AsyncTelegramAdapterImpl {
                 continue;
             }
             const sizeBytes = bytes.byteLength;
-            if (sizeBytes > MAX_TELEGRAM_ATTACHMENT_FILE_BYTES) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds per-file limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_FILE_BYTES)})`);
+            const fileLimitReason = this.getAttachmentPerFileLimitReason(sizeBytes);
+            if (fileLimitReason) {
+                await this.replySkippedAttachment(chatId, attachmentLabel, fileLimitReason);
                 continue;
             }
-            if (totalSizeBytes + sizeBytes > MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds per-turn total limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES)})`);
+            const totalLimitReason = this.getAttachmentTotalLimitReason(totalSizeBytes, sizeBytes);
+            if (totalLimitReason) {
+                await this.replySkippedAttachment(chatId, attachmentLabel, totalLimitReason);
                 continue;
             }
             const tempDirPath = await this.getOrCreatePendingAttachmentTempDir(session.id);
@@ -727,12 +878,14 @@ class AsyncTelegramAdapterImpl {
                 await this.reply(chatId, `skipped attachment ${attachmentLabel}: local temp file is missing`);
                 continue;
             }
-            if (materialized.sizeBytes > MAX_TELEGRAM_ATTACHMENT_FILE_BYTES) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds per-file limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_FILE_BYTES)})`);
+            const fileLimitReason = this.getAttachmentPerFileLimitReason(materialized.sizeBytes);
+            if (fileLimitReason) {
+                await this.replySkippedAttachment(chatId, attachmentLabel, fileLimitReason);
                 continue;
             }
-            if (totalSizeBytes + materialized.sizeBytes > MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES) {
-                await this.reply(chatId, `skipped attachment ${attachmentLabel}: exceeds per-turn total limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES)})`);
+            const totalLimitReason = this.getAttachmentTotalLimitReason(totalSizeBytes, materialized.sizeBytes);
+            if (totalLimitReason) {
+                await this.replySkippedAttachment(chatId, attachmentLabel, totalLimitReason);
                 continue;
             }
             totalSizeBytes += materialized.sizeBytes;
@@ -826,47 +979,12 @@ class AsyncTelegramAdapterImpl {
         const parts = splitCommandText(text);
         const command = stripCommandMention(parts[0] ?? "");
         const args = parts.slice(1);
-        if (command === "/help") {
-            await this.handleHelp(chatId);
-            return;
-        }
-        if (command === "/new") {
-            await this.handleNew(chatId, args);
-            return;
-        }
-        if (command === "/projects") {
-            await this.handleProjects(chatId);
-            return;
-        }
-        if (command === "/use") {
-            await this.handleUse(chatId, args);
-            return;
-        }
-        if (command === "/sessions") {
-            await this.handleSessions(chatId);
-            return;
-        }
-        if (command === "/status") {
-            await this.handleStatus(chatId);
-            return;
-        }
-        if (command === "/interrupt") {
-            await this.handleInterrupt(chatId);
-            return;
-        }
-        if (command === "/close") {
-            await this.handleClose(chatId, args);
-            return;
-        }
-        if (command === "/verbose") {
-            await this.handleVerbosityCommand(chatId, "verbose");
+        const handler = this.commandHandlers.get(command);
+        if (!handler) {
+            await this.reply(chatId, "unsupported command. use /help");
             return;
         }
-        if (command === "/quiet") {
-            await this.handleVerbosityCommand(chatId, "quiet");
-            return;
-        }
-        await this.reply(chatId, "unsupported command. use /help");
+        await handler(chatId, args);
     }
     async handleCallback(chatId, callbackData) {
         if (callbackData.startsWith(CALLBACK_USE_PREFIX)) {
@@ -880,50 +998,18 @@ class AsyncTelegramAdapterImpl {
         if (!callbackData.startsWith(CALLBACK_ACTION_PREFIX)) {
             return false;
         }
-        const action = callbackData.slice(CALLBACK_ACTION_PREFIX.length);
-        if (action === "new") {
-            await this.handleNew(chatId, []);
-            return true;
-        }
-        if (action === "sessions") {
-            await this.handleSessions(chatId);
-            return true;
-        }
-        if (action === "status") {
-            await this.handleStatus(chatId);
-            return true;
-        }
-        if (action === "interrupt") {
-            await this.handleInterrupt(chatId);
-            return true;
-        }
-        if (action === "close") {
-            await this.handleClose(chatId, []);
-            return true;
-        }
-        if (action === "quiet") {
-            await this.handleVerbosityCommand(chatId, "quiet");
-            return true;
-        }
-        if (action === "verbose") {
-            await this.handleVerbosityCommand(chatId, "verbose");
-            return true;
+        const action = callbackData.slice(CALLBACK_ACTION_PREFIX.length).trim();
+        const handler = this.callbackActionHandlers.get(action);
+        if (!handler) {
+            return false;
         }
-        return false;
+        await handler(chatId, []);
+        return true;
     }
     async handleHelp(chatId) {
         const lines = [
             "commands:",
-            "/help",
-            "/new [projectId]",
-            "/projects",
-            "/sessions",
-            "/use <sessionId|prefix|index>",
-            "/status",
-            "/interrupt",
-            "/close [<sessionId>|all]",
-            "/verbose",
-            "/quiet",
+            ...this.commandDefinitions.map((definition) => definition.usage),
             "",
             "tip: use /sessions and tap a session button to switch quickly",
         ];
@@ -1113,27 +1199,15 @@ class AsyncTelegramAdapterImpl {
     }
     buildQuickActionsKeyboard() {
         return {
-            inline_keyboard: [
-                [
-                    { text: "/new", callback_data: `${CALLBACK_ACTION_PREFIX}new` },
-                    { text: "/sessions", callback_data: `${CALLBACK_ACTION_PREFIX}sessions` },
-                    { text: "/status", callback_data: `${CALLBACK_ACTION_PREFIX}status` },
-                ],
-                [
-                    { text: "/interrupt", callback_data: `${CALLBACK_ACTION_PREFIX}interrupt` },
-                    { text: "/close", callback_data: `${CALLBACK_ACTION_PREFIX}close` },
-                ],
-                [
-                    { text: "/quiet", callback_data: `${CALLBACK_ACTION_PREFIX}quiet` },
-                    { text: "/verbose", callback_data: `${CALLBACK_ACTION_PREFIX}verbose` },
-                ],
-            ],
+            inline_keyboard: QUICK_ACTION_ROWS.map((row) => row.map((action) => ({
+                text: `/${action}`,
+                callback_data: `${CALLBACK_ACTION_PREFIX}${action}`,
+            }))),
         };
     }
     async handleStatus(chatId) {
-        const session = this.getActiveSession(chatId);
+        const session = await this.requireActiveSession(chatId);
         if (!session) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
             return;
         }
         await this.reply(chatId, describeSession(session, {
@@ -1145,9 +1219,8 @@ class AsyncTelegramAdapterImpl {
         });
     }
     async handleInterrupt(chatId) {
-        const session = this.getActiveSession(chatId);
+        const session = await this.requireActiveSession(chatId);
         if (!session) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
             return;
         }
         try {
@@ -1190,7 +1263,7 @@ class AsyncTelegramAdapterImpl {
         }
         const sessionId = target ?? this.getActiveSession(chatId)?.id;
         if (!sessionId) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
+            await this.reply(chatId, NO_ACTIVE_SESSION_MESSAGE);
             return;
         }
         try {
@@ -1204,38 +1277,28 @@ class AsyncTelegramAdapterImpl {
         }
     }
     async handleVerbosityCommand(chatId, verbosity) {
-        const session = this.getActiveSession(chatId);
+        const session = await this.requireActiveSession(chatId);
         if (!session) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
             return;
         }
         this.sessionVerbosityBySession.set(session.id, verbosity);
         await this.reply(chatId, formatSessionHeadline(session.id, `verbosity set to ${verbosity}`));
     }
     async handleMessage(chatId, text, sourceMessageId) {
-        const session = this.getActiveOrSingleSession(chatId);
+        const session = await this.requireActiveOrSingleSession(chatId);
         if (!session) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
             return;
         }
         try {
-            const textWithAttachments = await this.buildMessageTextWithAttachments(session.id, text, chatId);
-            const sessionManager = this.getSessionManagerForChat(chatId);
-            await sessionManager.sendMessage(session.id, textWithAttachments, this.systemMessage ? { additionalSystemMessage: this.systemMessage } : undefined);
-            this.resetPendingAttachmentQueue(session.id);
-            await this.reactToQueuedMessage(chatId, sourceMessageId);
-            if (this.isVerboseSession(session.id)) {
-                await this.reply(chatId, this.formatMessageQueued(session.id));
-            }
+            await this.submitSessionMessage(chatId, session.id, text, sourceMessageId);
         }
         catch (error) {
             await this.reply(chatId, this.formatManagerError(error));
         }
     }
     async handleAudioMessage(chatId, message, sourceMessageId) {
-        const session = this.getActiveOrSingleSession(chatId);
+        const session = await this.requireActiveOrSingleSession(chatId);
         if (!session) {
-            await this.reply(chatId, "no active session. use /new or /sessions");
             return;
         }
         if (!this.mistralApiKey) {
@@ -1262,19 +1325,53 @@ class AsyncTelegramAdapterImpl {
             return;
         }
         try {
-            const textWithAttachments = await this.buildMessageTextWithAttachments(session.id, transcript, chatId);
-            const sessionManager = this.getSessionManagerForChat(chatId);
-            await sessionManager.sendMessage(session.id, textWithAttachments, this.systemMessage ? { additionalSystemMessage: this.systemMessage } : undefined);
-            this.resetPendingAttachmentQueue(session.id);
-            await this.reactToQueuedMessage(chatId, sourceMessageId);
-            if (this.isVerboseSession(session.id)) {
-                await this.reply(chatId, this.formatMessageQueued(session.id));
-            }
+            await this.submitSessionMessage(chatId, session.id, transcript, sourceMessageId);
         }
         catch (error) {
             await this.reply(chatId, this.formatManagerError(error));
         }
     }
+    async requireActiveSession(chatId) {
+        const session = this.getActiveSession(chatId);
+        if (!session) {
+            await this.reply(chatId, NO_ACTIVE_SESSION_MESSAGE);
+            return undefined;
+        }
+        return session;
+    }
+    async requireActiveOrSingleSession(chatId) {
+        const session = this.getActiveOrSingleSession(chatId);
+        if (!session) {
+            await this.reply(chatId, NO_ACTIVE_SESSION_MESSAGE);
+            return undefined;
+        }
+        return session;
+    }
+    async submitSessionMessage(chatId, sessionId, text, sourceMessageId) {
+        const textWithAttachments = 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);
+        await this.reactToQueuedMessage(chatId, sourceMessageId);
+        if (this.isVerboseSession(sessionId)) {
+            await this.reply(chatId, this.formatMessageQueued(sessionId));
+        }
+    }
+    getAttachmentPerFileLimitReason(sizeBytes) {
+        if (sizeBytes <= MAX_TELEGRAM_ATTACHMENT_FILE_BYTES) {
+            return undefined;
+        }
+        return `exceeds per-file limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_FILE_BYTES)})`;
+    }
+    getAttachmentTotalLimitReason(totalSizeBytes, nextSizeBytes) {
+        if (totalSizeBytes + nextSizeBytes <= MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES) {
+            return undefined;
+        }
+        return `exceeds per-turn total limit (${describeAttachmentLimitBytes(MAX_TELEGRAM_ATTACHMENT_TOTAL_BYTES)})`;
+    }
+    async replySkippedAttachment(chatId, attachmentLabel, reason) {
+        await this.reply(chatId, `skipped attachment ${attachmentLabel}: ${reason}`);
+    }
     getActiveSession(chatId) {
         const sessionId = this.activeSessionsByChat.get(chatId);
         if (!sessionId) {