@grinev/opencode-telegram-bot 0.6.1 → 0.8.0

package/.env.example

@@ -36,6 +36,10 @@ OPENCODE_MODEL_ID=big-pickle
 # Bot Configuration (optional)
 # Maximum number of sessions shown in /sessions (default: 10)
 # SESSIONS_LIST_LIMIT=10
+
+# Maximum number of projects shown in /projects (default: 10)
+# PROJECTS_LIST_LIMIT=10
+
 # Bot locale: en or ru (default: en)
 # BOT_LOCALE=en
 
@@ -50,6 +54,20 @@ OPENCODE_MODEL_ID=big-pickle
 # Hide tool call service messages (default: false)
 # HIDE_TOOL_CALL_MESSAGES=false
 
+# Assistant message formatting mode (default: markdown)
+# markdown = convert assistant replies to Telegram MarkdownV2
+# raw = show assistant replies as plain text
+# MESSAGE_FORMAT_MODE=markdown
+
 # Code File Settings (optional)
 # Maximum file size in KB to send as document (default: 100)
 # CODE_FILE_MAX_SIZE_KB=100
+
+# Speech-to-Text / Voice Recognition (optional)
+# Enable voice message transcription by setting a Whisper-compatible API URL.
+# Works with OpenAI, Groq, or any Whisper-compatible endpoint.
+# If STT_API_URL is not set, voice messages will get a "not configured" reply.
+# STT_API_URL=
+# STT_API_KEY=
+# STT_MODEL=
+# STT_LANGUAGE=

package/README.md

@@ -25,7 +25,10 @@ Quick start: `npx @grinev/opencode-telegram-bot`
 - **Model switching** — pick any model from your OpenCode favorites directly in the chat
 - **Agent modes** — switch between Plan and Build modes on the fly
 - **Interactive Q&A** — answer agent questions and approve permissions via inline buttons
+- **Voice prompts** — send voice/audio messages, transcribe them via a Whisper-compatible API, then forward recognized text to OpenCode
 - **Context control** — compact context when it gets too large, right from the chat
+- **Input flow control** — when an interactive flow is active, the bot accepts only relevant input to keep context consistent and avoid accidental actions
+- **Configurable reply formatting** — assistant replies use Telegram MarkdownV2 by default, with optional raw mode (`MESSAGE_FORMAT_MODE=markdown|raw`)
 - **Security** — strict user ID whitelist; no one else can access your bot, even if they find it
 - **Localization** — English and Russian UI (`BOT_LOCALE=en|ru`)
 
@@ -102,15 +105,7 @@ opencode-telegram config
 | `/opencode_stop`  | Stop the OpenCode server remotely                       |
 | `/help`           | Show available commands                                 |
 
-Any regular text message is sent as a prompt to the coding agent only when no blocking interaction is active.
-
-### Interaction Rules
-
-- Only one interactive flow can be active at a time (inline menus, permission request, question flow, rename)
-- While an interaction is active, the bot accepts only relevant input for that flow and blocks unrelated actions
-- Allowed utility commands remain available during active interactions: `/help`, `/status`, `/stop`
-- Unknown slash commands return an explicit fallback message instead of being silently ignored
-- Interaction flows do not expire automatically and wait until explicit completion (`answer`, `cancel`, `/stop`, or reset/cleanup)
+Any regular text message is sent as a prompt to the coding agent only when no blocking interaction is active. Voice/audio messages are transcribed and then sent as prompts when STT is configured.
 
 > `/opencode_start` and `/opencode_stop` are intended as emergency commands — for example, if you need to restart a stuck server while away from your computer. Under normal usage, start `opencode serve` yourself before launching the bot.
 
@@ -124,26 +119,55 @@ When installed via npm, the configuration wizard handles the initial setup. The
 - **Windows:** `%APPDATA%\opencode-telegram-bot\.env`
 - **Linux:** `~/.config/opencode-telegram-bot/.env`
 
-| Variable                        | Description                                                                                                  | Required | Default                 |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------ | :------: | ----------------------- |
-| `TELEGRAM_BOT_TOKEN`            | Bot token from @BotFather                                                                                    |   Yes    | —                       |
-| `TELEGRAM_ALLOWED_USER_ID`      | Your numeric Telegram user ID                                                                                |   Yes    | —                       |
-| `TELEGRAM_PROXY_URL`            | Proxy URL for Telegram API (SOCKS5/HTTP)                                                                     |    No    | —                       |
-| `OPENCODE_API_URL`              | OpenCode server URL                                                                                          |    No    | `http://localhost:4096` |
-| `OPENCODE_SERVER_USERNAME`      | Server auth username                                                                                         |    No    | `opencode`              |
-| `OPENCODE_SERVER_PASSWORD`      | Server auth password                                                                                         |    No    | —                       |
-| `OPENCODE_MODEL_PROVIDER`       | Default model provider                                                                                       |   Yes    | `opencode`              |
-| `OPENCODE_MODEL_ID`             | Default model ID                                                                                             |   Yes    | `big-pickle`            |
-| `BOT_LOCALE`                    | Bot UI language (`en` or `ru`)                                                                               |    No    | `en`                    |
-| `SESSIONS_LIST_LIMIT`           | Max sessions shown in `/sessions`                                                                            |    No    | `10`                    |
-| `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                     |
-| `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                 |
-| `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                 |
-| `CODE_FILE_MAX_SIZE_KB`         | Max file size (KB) to send as document                                                                       |    No    | `100`                   |
-| `LOG_LEVEL`                     | Log level (`debug`, `info`, `warn`, `error`)                                                                 |    No    | `info`                  |
+| Variable                        | Description                                                                                                  | Required | Default                  |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------ | :------: | ------------------------ |
+| `TELEGRAM_BOT_TOKEN`            | Bot token from @BotFather                                                                                    |   Yes    | —                        |
+| `TELEGRAM_ALLOWED_USER_ID`      | Your numeric Telegram user ID                                                                                |   Yes    | —                        |
+| `TELEGRAM_PROXY_URL`            | Proxy URL for Telegram API (SOCKS5/HTTP)                                                                     |    No    | —                        |
+| `OPENCODE_API_URL`              | OpenCode server URL                                                                                          |    No    | `http://localhost:4096`  |
+| `OPENCODE_SERVER_USERNAME`      | Server auth username                                                                                         |    No    | `opencode`               |
+| `OPENCODE_SERVER_PASSWORD`      | Server auth password                                                                                         |    No    | —                        |
+| `OPENCODE_MODEL_PROVIDER`       | Default model provider                                                                                       |   Yes    | `opencode`               |
+| `OPENCODE_MODEL_ID`             | Default model ID                                                                                             |   Yes    | `big-pickle`             |
+| `BOT_LOCALE`                    | Bot UI language (`en` or `ru`)                                                                               |    No    | `en`                     |
+| `SESSIONS_LIST_LIMIT`           | Max sessions shown in `/sessions`                                                                            |    No    | `10`                     |
+| `PROJECTS_LIST_LIMIT`           | Max projects shown in `/projects`                                                                            |    No    | `10`                     |
+| `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                      |
+| `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                  |
+| `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                  |
+| `MESSAGE_FORMAT_MODE`           | Assistant reply formatting mode: `markdown` (Telegram MarkdownV2) or `raw`                                   |    No    | `markdown`               |
+| `CODE_FILE_MAX_SIZE_KB`         | Max file size (KB) to send as document                                                                       |    No    | `100`                    |
+| `STT_API_URL`                   | Whisper-compatible API base URL (enables voice/audio transcription)                                          |    No    | —                        |
+| `STT_API_KEY`                   | API key for your STT provider                                                                                |    No    | —                        |
+| `STT_MODEL`                     | STT model name passed to `/audio/transcriptions`                                                             |    No    | `whisper-large-v3-turbo` |
+| `STT_LANGUAGE`                  | Optional language hint (empty = provider auto-detect)                                                        |    No    | —                        |
+| `LOG_LEVEL`                     | Log level (`debug`, `info`, `warn`, `error`)                                                                 |    No    | `info`                   |
 
 > **Keep your `.env` file private.** It contains your bot token. Never commit it to version control.
 
+### Voice and Audio Transcription (Optional)
+
+If `STT_API_URL` and `STT_API_KEY` are set, the bot will:
+
+1. Accept `voice` and `audio` Telegram messages
+2. Transcribe them via `POST {STT_API_URL}/audio/transcriptions`
+3. Show recognized text in chat
+4. Send the recognized text to OpenCode as a normal prompt
+
+Supported provider examples (Whisper-compatible):
+
+- **OpenAI**
+  - `STT_API_URL=https://api.openai.com/v1`
+  - `STT_MODEL=whisper-1`
+- **Groq**
+  - `STT_API_URL=https://api.groq.com/openai/v1`
+  - `STT_MODEL=whisper-large-v3-turbo`
+- **Together**
+  - `STT_API_URL=https://api.together.xyz/v1`
+  - `STT_MODEL=openai/whisper-large-v3`
+
+If STT variables are not set, voice/audio transcription is disabled and the bot will ask you to configure STT.
+
 ### Model Configuration
 
 The bot picks up your **favorite models** from OpenCode. To add a model to favorites:

package/dist/bot/commands/projects.js

@@ -14,8 +14,8 @@ import { createMainKeyboard } from "../utils/keyboard.js";
 import { ensureActiveInlineMenu, replyWithInlineMenu } from "../handlers/inline-menu.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
+import { config } from "../../config.js";
 const MAX_INLINE_BUTTON_LABEL_LENGTH = 64;
-const MAX_PROJECTS_TO_SHOW = 10;
 function formatProjectButtonLabel(label, isActive) {
     const prefix = isActive ? "✅ " : "";
     const availableLength = MAX_INLINE_BUTTON_LABEL_LENGTH - prefix.length;
@@ -28,7 +28,7 @@ export async function projectsCommand(ctx) {
     try {
         await syncSessionDirectoryCache();
         const projects = await getProjects();
-        const projectsToShow = projects.slice(0, MAX_PROJECTS_TO_SHOW);
+        const projectsToShow = projects.slice(0, config.bot.projectsListLimit);
         if (projectsToShow.length === 0) {
             await ctx.reply(t("projects.empty"));
             return;

package/dist/bot/handlers/model.js

@@ -7,8 +7,20 @@ import { createMainKeyboard } from "../utils/keyboard.js";
 import { getStoredAgent } from "../../agent/manager.js";
 import { pinnedMessageManager } from "../../pinned/manager.js";
 import { keyboardManager } from "../../keyboard/manager.js";
+import { config } from "../../config.js";
 import { clearActiveInlineMenu, ensureActiveInlineMenu, replyWithInlineMenu, } from "./inline-menu.js";
 import { t } from "../../i18n/index.js";
+function isOnlyConfigDefaultModel(models) {
+    if (models.length !== 1) {
+        return false;
+    }
+    const defaultProviderID = config.opencode.model.provider;
+    const defaultModelID = config.opencode.model.modelId;
+    if (!defaultProviderID || !defaultModelID) {
+        return false;
+    }
+    return models[0].providerID === defaultProviderID && models[0].modelID === defaultModelID;
+}
 /**
  * Handle model selection callback
  * @param ctx grammY context
@@ -83,9 +95,9 @@ export async function handleModelSelect(ctx) {
  * @param currentModel Current model for highlighting
  * @returns InlineKeyboard with model selection buttons
  */
-export async function buildModelSelectionMenu(currentModel) {
+export async function buildModelSelectionMenu(currentModel, favoriteModels) {
     const keyboard = new InlineKeyboard();
-    const favorites = await getFavoriteModels();
+    const favorites = favoriteModels ?? (await getFavoriteModels());
     if (favorites.length === 0) {
         logger.warn("[ModelHandler] No favorite models found");
         return keyboard;
@@ -109,7 +121,8 @@ export async function buildModelSelectionMenu(currentModel) {
 export async function showModelSelectionMenu(ctx) {
     try {
         const currentModel = fetchCurrentModel();
-        const keyboard = await buildModelSelectionMenu(currentModel);
+        const favorites = await getFavoriteModels();
+        const keyboard = await buildModelSelectionMenu(currentModel, favorites);
         if (keyboard.inline_keyboard.length === 0) {
             await ctx.reply(t("model.menu.empty"));
             return;
@@ -121,6 +134,9 @@ export async function showModelSelectionMenu(ctx) {
             text,
             keyboard,
         });
+        if (isOnlyConfigDefaultModel(favorites)) {
+            await ctx.reply(t("model.menu.favorites_hint"));
+        }
     }
     catch (err) {
         logger.error("[ModelHandler] Error showing model menu:", err);

package/dist/bot/handlers/prompt.js

@@ -0,0 +1,232 @@
+import { opencodeClient } from "../../opencode/client.js";
+import { clearSession, getCurrentSession, setCurrentSession } from "../../session/manager.js";
+import { ingestSessionInfoForCache } from "../../session/cache-manager.js";
+import { getCurrentProject } from "../../settings/manager.js";
+import { getStoredAgent } from "../../agent/manager.js";
+import { getStoredModel } from "../../model/manager.js";
+import { formatVariantForButton } from "../../variant/manager.js";
+import { createMainKeyboard } from "../utils/keyboard.js";
+import { keyboardManager } from "../../keyboard/manager.js";
+import { pinnedMessageManager } from "../../pinned/manager.js";
+import { summaryAggregator } from "../../summary/aggregator.js";
+import { stopEventListening } from "../../opencode/events.js";
+import { interactionManager } from "../../interaction/manager.js";
+import { clearAllInteractionState } from "../../interaction/cleanup.js";
+import { safeBackgroundTask } from "../../utils/safe-background-task.js";
+import { formatErrorDetails } from "../../utils/error-format.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+/** Module-level references for async callbacks that don't have ctx. */
+let botInstance = null;
+let chatIdInstance = null;
+export function getPromptBotInstance() {
+    return botInstance;
+}
+export function getPromptChatId() {
+    return chatIdInstance;
+}
+async function isSessionBusy(sessionId, directory) {
+    try {
+        const { data, error } = await opencodeClient.session.status({ directory });
+        if (error || !data) {
+            logger.warn("[Bot] Failed to check session status before prompt:", error);
+            return false;
+        }
+        const sessionStatus = data[sessionId];
+        if (!sessionStatus) {
+            return false;
+        }
+        logger.debug(`[Bot] Current session status before prompt: ${sessionStatus.type || "unknown"}`);
+        return sessionStatus.type === "busy";
+    }
+    catch (err) {
+        logger.warn("[Bot] Error checking session status before prompt:", err);
+        return false;
+    }
+}
+async function resetMismatchedSessionContext() {
+    stopEventListening();
+    summaryAggregator.clear();
+    clearAllInteractionState("session_mismatch_reset");
+    clearSession();
+    keyboardManager.clearContext();
+    if (!pinnedMessageManager.isInitialized()) {
+        return;
+    }
+    try {
+        await pinnedMessageManager.clear();
+    }
+    catch (err) {
+        logger.error("[Bot] Failed to clear pinned message during session reset:", err);
+    }
+}
+/**
+ * Processes a user prompt: ensures project/session, subscribes to events, and sends
+ * the prompt to OpenCode. Used by text, voice, and photo message handlers.
+ *
+ * @param ctx - Grammy context
+ * @param text - Text content of the prompt
+ * @param deps - Dependencies (bot and event subscription)
+ * @param fileParts - Optional file parts (for photo/document attachments)
+ * @returns true if the prompt was dispatched, false if it was blocked/failed early.
+ */
+export async function processUserPrompt(ctx, text, deps, fileParts = []) {
+    const { bot, ensureEventSubscription } = deps;
+    const currentProject = getCurrentProject();
+    if (!currentProject) {
+        await ctx.reply(t("bot.project_not_selected"));
+        return false;
+    }
+    botInstance = bot;
+    chatIdInstance = ctx.chat.id;
+    // Initialize pinned message manager if not already
+    if (!pinnedMessageManager.isInitialized()) {
+        pinnedMessageManager.initialize(bot.api, ctx.chat.id);
+    }
+    // Initialize keyboard manager if not already
+    keyboardManager.initialize(bot.api, ctx.chat.id);
+    let currentSession = getCurrentSession();
+    if (currentSession && currentSession.directory !== currentProject.worktree) {
+        logger.warn(`[Bot] Session/project mismatch detected. sessionDirectory=${currentSession.directory}, projectDirectory=${currentProject.worktree}. Resetting session context.`);
+        await resetMismatchedSessionContext();
+        await ctx.reply(t("bot.session_reset_project_mismatch"));
+        return false;
+    }
+    if (!currentSession) {
+        await ctx.reply(t("bot.creating_session"));
+        const { data: session, error } = await opencodeClient.session.create({
+            directory: currentProject.worktree,
+        });
+        if (error || !session) {
+            await ctx.reply(t("bot.create_session_error"));
+            return false;
+        }
+        logger.info(`[Bot] Created new session: id=${session.id}, title="${session.title}", project=${currentProject.worktree}`);
+        currentSession = {
+            id: session.id,
+            title: session.title,
+            directory: currentProject.worktree,
+        };
+        setCurrentSession(currentSession);
+        await ingestSessionInfoForCache(session);
+        // Create pinned message for new session
+        try {
+            await pinnedMessageManager.onSessionChange(session.id, session.title);
+        }
+        catch (err) {
+            logger.error("[Bot] Error creating pinned message for new session:", err);
+        }
+        const currentAgent = getStoredAgent();
+        const currentModel = getStoredModel();
+        const contextInfo = pinnedMessageManager.getContextInfo();
+        const variantName = formatVariantForButton(currentModel.variant || "default");
+        const keyboard = createMainKeyboard(currentAgent, currentModel, contextInfo ?? undefined, variantName);
+        await ctx.reply(t("bot.session_created", { title: session.title }), {
+            reply_markup: keyboard,
+        });
+    }
+    else {
+        logger.info(`[Bot] Using existing session: id=${currentSession.id}, title="${currentSession.title}"`);
+        // Ensure pinned message exists for existing session
+        if (!pinnedMessageManager.getState().messageId) {
+            try {
+                await pinnedMessageManager.onSessionChange(currentSession.id, currentSession.title);
+            }
+            catch (err) {
+                logger.error("[Bot] Error creating pinned message for existing session:", err);
+            }
+        }
+    }
+    await ensureEventSubscription(currentSession.directory);
+    summaryAggregator.setSession(currentSession.id);
+    summaryAggregator.setBotAndChatId(bot, ctx.chat.id);
+    const sessionIsBusy = await isSessionBusy(currentSession.id, currentSession.directory);
+    if (sessionIsBusy) {
+        logger.info(`[Bot] Ignoring new prompt: session ${currentSession.id} is busy`);
+        await ctx.reply(t("bot.session_busy"));
+        return false;
+    }
+    try {
+        const currentAgent = getStoredAgent();
+        const storedModel = getStoredModel();
+        // Build parts array with text and files
+        const parts = [];
+        // Add text part if present
+        if (text.trim().length > 0) {
+            parts.push({ type: "text", text });
+        }
+        // Add file parts
+        parts.push(...fileParts);
+        // If no text and files exist, use a placeholder
+        if (parts.length === 0 || (parts.length > 0 && parts.every((p) => p.type === "file"))) {
+            if (fileParts.length > 0) {
+                // Files without text - add a minimal system prompt
+                parts.unshift({ type: "text", text: "See attached file" });
+            }
+        }
+        const promptOptions = {
+            sessionID: currentSession.id,
+            directory: currentSession.directory,
+            parts,
+            agent: currentAgent,
+        };
+        // Use stored model (from settings or config)
+        if (storedModel.providerID && storedModel.modelID) {
+            promptOptions.model = {
+                providerID: storedModel.providerID,
+                modelID: storedModel.modelID,
+            };
+            // Add variant if specified
+            if (storedModel.variant) {
+                promptOptions.variant = storedModel.variant;
+            }
+        }
+        const promptErrorLogContext = {
+            sessionId: currentSession.id,
+            directory: currentSession.directory,
+            agent: currentAgent || "default",
+            modelProvider: storedModel.providerID || "default",
+            modelId: storedModel.modelID || "default",
+            variant: storedModel.variant || "default",
+            promptLength: text.length,
+            fileCount: fileParts.length,
+        };
+        logger.info(`[Bot] Calling session.prompt (fire-and-forget) with agent=${currentAgent}, fileCount=${fileParts.length}...`);
+        // CRITICAL: DO NOT wait for session.prompt to complete.
+        // If we wait, the handler will not finish and grammY will not call getUpdates,
+        // which blocks receiving button callback_query updates.
+        // The processing result will arrive via SSE events.
+        safeBackgroundTask({
+            taskName: "session.prompt",
+            task: () => opencodeClient.session.prompt(promptOptions),
+            onSuccess: ({ error }) => {
+                if (error) {
+                    const details = formatErrorDetails(error, 6000);
+                    logger.error("[Bot] OpenCode API returned an error for session.prompt", promptErrorLogContext);
+                    logger.error("[Bot] session.prompt error details:", details);
+                    logger.error("[Bot] session.prompt raw API error object:", error);
+                    // Send user-friendly error via API directly because ctx is no longer available
+                    void bot.api.sendMessage(ctx.chat.id, t("bot.prompt_send_error")).catch(() => { });
+                    return;
+                }
+                logger.info("[Bot] session.prompt completed");
+            },
+            onError: (error) => {
+                const details = formatErrorDetails(error, 6000);
+                logger.error("[Bot] session.prompt background task failed", promptErrorLogContext);
+                logger.error("[Bot] session.prompt background failure details:", details);
+                logger.error("[Bot] session.prompt raw background error object:", error);
+                void bot.api.sendMessage(ctx.chat.id, t("bot.prompt_send_error")).catch(() => { });
+            },
+        });
+        return true;
+    }
+    catch (err) {
+        logger.error("Error in prompt handler:", err);
+        if (interactionManager.getSnapshot()) {
+            clearAllInteractionState("message_handler_error");
+        }
+        await ctx.reply(t("error.generic"));
+        return false;
+    }
+}

package/dist/bot/handlers/voice.js

@@ -0,0 +1,170 @@
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { SocksProxyAgent } from "socks-proxy-agent";
+import { config } from "../../config.js";
+import { isSttConfigured, transcribeAudio } from "../../stt/client.js";
+import { processUserPrompt } from "./prompt.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+const TELEGRAM_DOWNLOAD_TIMEOUT_MS = 30_000;
+const TELEGRAM_DOWNLOAD_MAX_REDIRECTS = 3;
+let telegramDownloadAgent;
+function getTelegramDownloadAgent() {
+    if (telegramDownloadAgent !== undefined) {
+        return telegramDownloadAgent || undefined;
+    }
+    const proxyUrl = config.telegram.proxyUrl.trim();
+    if (!proxyUrl) {
+        telegramDownloadAgent = null;
+        return undefined;
+    }
+    telegramDownloadAgent = proxyUrl.startsWith("socks")
+        ? new SocksProxyAgent(proxyUrl)
+        : new HttpsProxyAgent(proxyUrl);
+    logger.info(`[Voice] Using Telegram download proxy: ${proxyUrl.replace(/\/\/.*@/, "//***@")}`);
+    return telegramDownloadAgent;
+}
+async function downloadTelegramFileByUrl(url, redirectDepth = 0) {
+    return new Promise((resolve, reject) => {
+        const targetUrl = new URL(url);
+        const requestModule = targetUrl.protocol === "http:" ? http : https;
+        const request = requestModule.get(targetUrl, { agent: getTelegramDownloadAgent() }, (response) => {
+            const statusCode = response.statusCode ?? 0;
+            if (statusCode >= 300 && statusCode < 400 && response.headers.location) {
+                response.resume();
+                if (redirectDepth >= TELEGRAM_DOWNLOAD_MAX_REDIRECTS) {
+                    reject(new Error("Too many redirects while downloading Telegram file"));
+                    return;
+                }
+                const redirectUrl = new URL(response.headers.location, targetUrl).toString();
+                void downloadTelegramFileByUrl(redirectUrl, redirectDepth + 1)
+                    .then(resolve)
+                    .catch(reject);
+                return;
+            }
+            if (statusCode < 200 || statusCode >= 300) {
+                response.resume();
+                reject(new Error(`Telegram file download failed with HTTP ${statusCode}`));
+                return;
+            }
+            const chunks = [];
+            response.on("data", (chunk) => {
+                chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+            });
+            response.on("end", () => {
+                resolve(Buffer.concat(chunks));
+            });
+            response.on("error", reject);
+        });
+        request.on("error", reject);
+        request.setTimeout(TELEGRAM_DOWNLOAD_TIMEOUT_MS, () => {
+            request.destroy(new Error(`Telegram file download timed out after ${TELEGRAM_DOWNLOAD_TIMEOUT_MS}ms`));
+        });
+    });
+}
+/**
+ * Downloads the audio file from Telegram servers.
+ *
+ * @returns Buffer with file content, or null on failure
+ */
+async function downloadTelegramFile(ctx, fileId) {
+    try {
+        const file = await ctx.api.getFile(fileId);
+        if (!file.file_path) {
+            logger.error("[Voice] Telegram getFile returned no file_path");
+            return null;
+        }
+        const fileUrl = `https://api.telegram.org/file/bot${ctx.api.token}/${file.file_path}`;
+        logger.debug(`[Voice] Downloading file: ${file.file_path} (${file.file_size ?? "?"} bytes)`);
+        const buffer = await downloadTelegramFileByUrl(fileUrl);
+        // Extract filename from file_path (e.g., "voice/file_123.oga" -> "file_123.oga")
+        const filename = file.file_path.split("/").pop() || "audio.ogg";
+        logger.debug(`[Voice] Downloaded file: ${filename} (${buffer.length} bytes)`);
+        return { buffer, filename };
+    }
+    catch (err) {
+        logger.error("[Voice] Error downloading file from Telegram:", err);
+        return null;
+    }
+}
+/**
+ * Creates the voice message handler function.
+ *
+ * The factory pattern is used so that `bot` and `ensureEventSubscription` dependencies
+ * can be injected from createBot() without circular imports.
+ */
+export function createVoiceHandler(deps) {
+    return async (ctx) => {
+        await handleVoiceMessage(ctx, deps);
+    };
+}
+/**
+ * Handles incoming voice and audio messages:
+ * 1. Checks if STT is configured
+ * 2. Downloads the audio file from Telegram
+ * 3. Sends "recognizing..." status message
+ * 4. Calls STT API
+ * 5. Shows recognized text
+ * 6. Passes text to processUserPrompt
+ */
+export async function handleVoiceMessage(ctx, deps) {
+    const sttConfigured = deps.isSttConfigured ?? isSttConfigured;
+    const downloadFile = deps.downloadTelegramFile ?? downloadTelegramFile;
+    const transcribe = deps.transcribeAudio ?? transcribeAudio;
+    const processPrompt = deps.processPrompt ?? processUserPrompt;
+    // Determine file_id from voice or audio message
+    const voice = ctx.message?.voice;
+    const audio = ctx.message?.audio;
+    const fileId = voice?.file_id ?? audio?.file_id;
+    if (!fileId) {
+        logger.warn("[Voice] Received voice/audio message with no file_id");
+        return;
+    }
+    // Check if STT is configured
+    if (!sttConfigured()) {
+        await ctx.reply(t("stt.not_configured"));
+        return;
+    }
+    // Send "recognizing..." status message (will be edited later)
+    const statusMessage = await ctx.reply(t("stt.recognizing"));
+    try {
+        // Download the audio file from Telegram
+        const fileData = await downloadFile(ctx, fileId);
+        if (!fileData) {
+            await ctx.api.editMessageText(ctx.chat.id, statusMessage.message_id, t("stt.error", { error: "download failed" }));
+            return;
+        }
+        // Transcribe the audio
+        const result = await transcribe(fileData.buffer, fileData.filename);
+        const recognizedText = result.text.trim();
+        if (!recognizedText) {
+            await ctx.api.editMessageText(ctx.chat.id, statusMessage.message_id, t("stt.empty_result"));
+            return;
+        }
+        // Show the recognized text by editing the status message.
+        // IMPORTANT: even if this edit fails (e.g. Telegram message length limits),
+        // we still send the recognized text to OpenCode as a prompt.
+        try {
+            await ctx.api.editMessageText(ctx.chat.id, statusMessage.message_id, t("stt.recognized", { text: recognizedText }));
+        }
+        catch (editError) {
+            logger.warn("[Voice] Failed to edit status message with recognized text:", editError);
+        }
+        logger.info(`[Voice] Transcribed audio: ${recognizedText.length} chars`);
+        // Process the recognized text as a prompt
+        await processPrompt(ctx, recognizedText, deps);
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "unknown error";
+        logger.error("[Voice] Error processing voice message:", err);
+        try {
+            await ctx.api.editMessageText(ctx.chat.id, statusMessage.message_id, t("stt.error", { error: errorMessage }));
+        }
+        catch {
+            // If we can't edit the status message, try sending a new one
+            await ctx.reply(t("stt.error", { error: errorMessage })).catch(() => { });
+        }
+    }
+}