@grinev/opencode-telegram-bot 0.6.1 → 0.7.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
 
@@ -53,3 +57,12 @@ OPENCODE_MODEL_ID=big-pickle
 # 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,9 @@ 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
 - **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 +104,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 +118,54 @@ 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`                  |
+| `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/prompt.js

@@ -0,0 +1,212 @@
+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 both text and voice message handlers.
+ *
+ * @returns true if the prompt was dispatched, false if it was blocked/failed early.
+ */
+export async function processUserPrompt(ctx, text, deps) {
+    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();
+        const promptOptions = {
+            sessionID: currentSession.id,
+            directory: currentSession.directory,
+            parts: [{ type: "text", text }],
+            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,
+        };
+        logger.info(`[Bot] Calling session.prompt (fire-and-forget) with agent=${currentAgent}...`);
+        // 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(() => { });
+        }
+    }
+}

package/dist/bot/index.js

@@ -33,23 +33,18 @@ import { questionManager } from "../question/manager.js";
 import { interactionManager } from "../interaction/manager.js";
 import { clearAllInteractionState } from "../interaction/cleanup.js";
 import { keyboardManager } from "../keyboard/manager.js";
-import { stopEventListening, subscribeToEvents } from "../opencode/events.js";
+import { subscribeToEvents } from "../opencode/events.js";
 import { summaryAggregator } from "../summary/aggregator.js";
 import { formatSummary, formatToolInfo } from "../summary/formatter.js";
 import { ToolMessageBatcher } from "../summary/tool-message-batcher.js";
-import { opencodeClient } from "../opencode/client.js";
-import { clearSession, getCurrentSession, setCurrentSession } from "../session/manager.js";
+import { getCurrentSession } 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 { logger } from "../utils/logger.js";
 import { safeBackgroundTask } from "../utils/safe-background-task.js";
-import { formatErrorDetails } from "../utils/error-format.js";
 import { pinnedMessageManager } from "../pinned/manager.js";
 import { t } from "../i18n/index.js";
+import { processUserPrompt } from "./handlers/prompt.js";
+import { handleVoiceMessage } from "./handlers/voice.js";
 let botInstance = null;
 let chatIdInstance = null;
 let commandsInitialized = false;
@@ -310,6 +305,25 @@ async function ensureEventSubscription(directory) {
             logger.error("[Bot] Error reloading context after compaction:", err);
         }
     });
+    summaryAggregator.setOnSessionError(async (sessionId, message) => {
+        if (!botInstance || !chatIdInstance) {
+            return;
+        }
+        const currentSession = getCurrentSession();
+        if (!currentSession || currentSession.id !== sessionId) {
+            return;
+        }
+        await toolMessageBatcher.flushSession(sessionId, "session_error");
+        const normalizedMessage = message.trim() || t("common.unknown_error");
+        const truncatedMessage = normalizedMessage.length > 3500
+            ? `${normalizedMessage.slice(0, 3497)}...`
+            : normalizedMessage;
+        await botInstance.api
+            .sendMessage(chatIdInstance, t("bot.session_error", { message: truncatedMessage }))
+            .catch((err) => {
+            logger.error("[Bot] Failed to send session.error message:", err);
+        });
+    });
     summaryAggregator.setOnSessionDiff(async (_sessionId, diffs) => {
         if (!pinnedMessageManager.isInitialized()) {
             return;
@@ -353,41 +367,6 @@ async function ensureEventSubscription(directory) {
         logger.error("Failed to subscribe to events:", err);
     });
 }
-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);
-    }
-}
 export function createBot() {
     clearAllInteractionState("bot_startup");
     toolMessageBatcher.setIntervalSeconds(config.bot.serviceMessagesIntervalSec);
@@ -591,6 +570,20 @@ export function createBot() {
             logger.warn("[Bot] Could not clear global commands:", result.error);
         },
     });
+    // Voice and audio message handlers (STT transcription -> prompt)
+    const voicePromptDeps = { bot, ensureEventSubscription };
+    bot.on("message:voice", async (ctx) => {
+        logger.debug(`[Bot] Received voice message, chatId=${ctx.chat.id}`);
+        botInstance = bot;
+        chatIdInstance = ctx.chat.id;
+        await handleVoiceMessage(ctx, voicePromptDeps);
+    });
+    bot.on("message:audio", async (ctx) => {
+        logger.debug(`[Bot] Received audio message, chatId=${ctx.chat.id}`);
+        botInstance = bot;
+        chatIdInstance = ctx.chat.id;
+        await handleVoiceMessage(ctx, voicePromptDeps);
+    });
     bot.on("message:text", async (ctx) => {
         const text = ctx.message?.text;
         if (!text) {
@@ -607,145 +600,10 @@ export function createBot() {
         if (handledRename) {
             return;
         }
-        const currentProject = getCurrentProject();
-        if (!currentProject) {
-            await ctx.reply(t("bot.project_not_selected"));
-            return;
-        }
         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;
-        }
-        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;
-            }
-            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;
-        }
-        try {
-            const currentAgent = getStoredAgent();
-            const storedModel = getStoredModel();
-            const promptOptions = {
-                sessionID: currentSession.id,
-                directory: currentSession.directory,
-                parts: [{ type: "text", text }],
-                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,
-            };
-            logger.info(`[Bot] Calling session.prompt (fire-and-forget) with agent=${currentAgent}...`);
-            // 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(() => { });
-                },
-            });
-        }
-        catch (err) {
-            logger.error("Error in prompt handler:", err);
-            if (interactionManager.getSnapshot()) {
-                clearAllInteractionState("message_handler_error");
-            }
-            await ctx.reply(t("error.generic"));
-        }
+        const promptDeps = { bot, ensureEventSubscription };
+        await processUserPrompt(ctx, text, promptDeps);
         logger.debug("[Bot] message:text handler completed (prompt sent in background)");
     });
     bot.catch((err) => {

package/dist/config.js

@@ -82,6 +82,7 @@ export const config = {
     },
     bot: {
         sessionsListLimit: getOptionalPositiveIntEnvVar("SESSIONS_LIST_LIMIT", 10),
+        projectsListLimit: getOptionalPositiveIntEnvVar("PROJECTS_LIST_LIMIT", 10),
         locale: getOptionalLocaleEnvVar("BOT_LOCALE", "en"),
         serviceMessagesIntervalSec: getOptionalNonNegativeIntEnvVarFromKeys(["SERVICE_MESSAGES_INTERVAL_SEC", "TOOL_MESSAGES_INTERVAL_SEC"], 5),
         hideThinkingMessages: getOptionalBooleanEnvVar("HIDE_THINKING_MESSAGES", false),
@@ -90,4 +91,10 @@ export const config = {
     files: {
         maxFileSizeKb: parseInt(getEnvVar("CODE_FILE_MAX_SIZE_KB", false) || "100", 10),
     },
+    stt: {
+        apiUrl: getEnvVar("STT_API_URL", false),
+        apiKey: getEnvVar("STT_API_KEY", false),
+        model: getEnvVar("STT_MODEL", false) || "whisper-large-v3-turbo",
+        language: getEnvVar("STT_LANGUAGE", false),
+    },
 };

package/dist/i18n/en.js

@@ -41,6 +41,7 @@ export const en = {
     "bot.session_busy": "⏳ Agent is already running a task. Wait for completion or use /stop to interrupt current run.",
     "bot.session_reset_project_mismatch": "⚠️ Active session does not match the selected project, so it was reset. Use /sessions to pick one or /new to create a new session.",
     "bot.prompt_send_error": "Failed to send request to OpenCode.",
+    "bot.session_error": "🔴 OpenCode returned an error: {message}",
     "bot.unknown_command": "⚠️ Unknown command: {command}. Use /help to see available commands.",
     "status.header_running": "🟢 **OpenCode Server is running**",
     "status.health.healthy": "Healthy",
@@ -229,4 +230,9 @@ export const en = {
     "legacy.models.no_provider_models": "  ⚠️ No available models\n",
     "legacy.models.env_hint": "💡 To use model in .env:\n",
     "legacy.models.error": "🔴 An error occurred while loading models list.",
+    "stt.recognizing": "🎤 Recognizing audio...",
+    "stt.recognized": "🎤 Recognized:\n{text}",
+    "stt.not_configured": "🎤 Voice recognition is not configured.\n\nSet STT_API_URL and STT_API_KEY in .env to enable it.",
+    "stt.error": "🔴 Failed to recognize audio: {error}",
+    "stt.empty_result": "🎤 No speech detected in the audio message.",
 };

package/dist/i18n/ru.js

@@ -41,6 +41,7 @@ export const ru = {
     "bot.session_busy": "⏳ Агент уже выполняет задачу. Дождитесь завершения или используйте /stop, чтобы прервать текущий запуск.",
     "bot.session_reset_project_mismatch": "⚠️ Активная сессия не соответствует выбранному проекту, поэтому была сброшена. Используйте /sessions для выбора или /new для создания новой сессии.",
     "bot.prompt_send_error": "Не удалось отправить запрос в OpenCode.",
+    "bot.session_error": "🔴 OpenCode вернул ошибку: {message}",
     "bot.unknown_command": "⚠️ Неизвестная команда: {command}. Используйте /help для списка команд.",
     "status.header_running": "🟢 **OpenCode Server запущен**",
     "status.health.healthy": "Healthy",
@@ -229,4 +230,9 @@ export const ru = {
     "legacy.models.no_provider_models": "  ⚠️ Нет доступных моделей\n",
     "legacy.models.env_hint": "💡 Для использования модели в .env:\n",
     "legacy.models.error": "🔴 Произошла ошибка при получении списка моделей.",
+    "stt.recognizing": "🎤 Распознаю аудио...",
+    "stt.recognized": "🎤 Распознано:\n{text}",
+    "stt.not_configured": "🎤 Распознавание голоса не настроено.\n\nУстановите STT_API_URL и STT_API_KEY в .env для включения.",
+    "stt.error": "🔴 Не удалось распознать аудио: {error}",
+    "stt.empty_result": "🎤 В аудиосообщении не обнаружена речь.",
 };

package/dist/interaction/guard.js

@@ -75,7 +75,10 @@ export function resolveInteractionGuardDecision(ctx) {
         return createBlockDecision(inputType, state, "command_not_allowed", command);
     }
     if (state.expectedInput === "mixed") {
-        return createAllowDecision(inputType, state, command);
+        if (inputType === "callback" || inputType === "text") {
+            return createAllowDecision(inputType, state, command);
+        }
+        return createBlockDecision(inputType, state, "expected_text", command);
     }
     if (inputType === "callback" && isAllowedRenameCancelCallback(ctx, state)) {
         return createAllowDecision(inputType, state, command);

package/dist/stt/client.js

@@ -0,0 +1,64 @@
+import { config } from "../config.js";
+import { logger } from "../utils/logger.js";
+const STT_REQUEST_TIMEOUT_MS = 60_000;
+/**
+ * Returns true if STT is configured (API URL and API key are set).
+ */
+export function isSttConfigured() {
+    return Boolean(config.stt.apiUrl && config.stt.apiKey);
+}
+/**
+ * Transcribes an audio buffer using a Whisper-compatible API (OpenAI / Groq / etc.).
+ *
+ * Sends a multipart/form-data POST to `{STT_API_URL}/audio/transcriptions`.
+ *
+ * @param audioBuffer - Raw audio file bytes (ogg, mp3, wav, m4a, webm, etc.)
+ * @param filename    - Original filename with extension (used by the API to detect format)
+ * @returns Transcribed text
+ * @throws Error if STT is not configured, the request fails, or the response is invalid
+ */
+export async function transcribeAudio(audioBuffer, filename) {
+    if (!isSttConfigured()) {
+        throw new Error("STT is not configured: STT_API_URL and STT_API_KEY are required");
+    }
+    const url = `${config.stt.apiUrl}/audio/transcriptions`;
+    const formData = new FormData();
+    formData.append("file", new Blob([new Uint8Array(audioBuffer)]), filename);
+    formData.append("model", config.stt.model);
+    formData.append("response_format", "json");
+    if (config.stt.language) {
+        formData.append("language", config.stt.language);
+    }
+    logger.debug(`[STT] Sending transcription request: url=${url}, model=${config.stt.model}, filename=${filename}, size=${audioBuffer.length} bytes`);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), STT_REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${config.stt.apiKey}`,
+            },
+            body: formData,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            throw new Error(`STT API returned HTTP ${response.status}: ${errorBody || response.statusText}`);
+        }
+        const data = (await response.json());
+        if (typeof data.text !== "string") {
+            throw new Error("STT API response does not contain a text field");
+        }
+        logger.debug(`[STT] Transcription result: ${data.text.length} chars`);
+        return { text: data.text };
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`STT request timed out after ${STT_REQUEST_TIMEOUT_MS}ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/summary/aggregator.js

@@ -39,11 +39,13 @@ class SummaryAggregator {
     onThinkingCallback = null;
     onTokensCallback = null;
     onSessionCompactedCallback = null;
+    onSessionErrorCallback = null;
     onPermissionCallback = null;
     onSessionDiffCallback = null;
     onFileChangeCallback = null;
     onClearedCallback = null;
     processedToolStates = new Set();
+    thinkingFiredForMessages = new Set();
     bot = null;
     chatId = null;
     typingTimer = null;
@@ -76,6 +78,9 @@ class SummaryAggregator {
     setOnSessionCompacted(callback) {
         this.onSessionCompactedCallback = callback;
     }
+    setOnSessionError(callback) {
+        this.onSessionErrorCallback = callback;
+    }
     setOnPermission(callback) {
         this.onPermissionCallback = callback;
     }
@@ -133,6 +138,9 @@ class SummaryAggregator {
             case "session.compacted":
                 this.handleSessionCompacted(event);
                 break;
+            case "session.error":
+                this.handleSessionError(event);
+                break;
             case "question.asked":
                 this.handleQuestionAsked(event);
                 break;
@@ -170,6 +178,7 @@ class SummaryAggregator {
         this.messages.clear();
         this.partHashes.clear();
         this.processedToolStates.clear();
+        this.thinkingFiredForMessages.clear();
         this.messageCount = 0;
         this.lastUpdated = 0;
         if (this.onClearedCallback) {
@@ -193,16 +202,6 @@ class SummaryAggregator {
                 this.currentMessageParts.set(messageID, []);
                 this.messageCount++;
                 this.startTypingIndicator();
-                const isSummaryMessage = info.summary === true;
-                // Notify that agent started thinking
-                if (!isSummaryMessage && this.onThinkingCallback) {
-                    const callback = this.onThinkingCallback;
-                    setImmediate(() => {
-                        if (typeof callback === "function") {
-                            callback(info.sessionID);
-                        }
-                    });
-                }
             }
             const pending = this.pendingParts.get(messageID) || [];
             const current = this.currentMessageParts.get(messageID) || [];
@@ -250,7 +249,21 @@ class SummaryAggregator {
         }
         const messageID = part.messageID;
         const messageInfo = this.messages.get(messageID);
-        if (part.type === "text" && "text" in part && part.text) {
+        if (part.type === "reasoning") {
+            // Fire the thinking callback once per message on the first reasoning part.
+            // This is the signal that the model is actually doing extended thinking.
+            if (!this.thinkingFiredForMessages.has(messageID) && this.onThinkingCallback) {
+                this.thinkingFiredForMessages.add(messageID);
+                const callback = this.onThinkingCallback;
+                const sessionID = part.sessionID;
+                setImmediate(() => {
+                    if (typeof callback === "function") {
+                        callback(sessionID);
+                    }
+                });
+            }
+        }
+        else if (part.type === "text" && "text" in part && part.text) {
             const partHash = this.hashString(part.text);
             if (!this.partHashes.has(messageID)) {
                 this.partHashes.set(messageID, new Set());
@@ -452,6 +465,21 @@ class SummaryAggregator {
             });
         }
     }
+    handleSessionError(event) {
+        const { sessionID, error } = event.properties;
+        if (sessionID !== this.currentSessionId) {
+            return;
+        }
+        const message = error?.data?.message || error?.message || error?.name || "Unknown session error";
+        logger.warn(`[Aggregator] Session error: ${sessionID}: ${message}`);
+        this.stopTypingIndicator();
+        if (this.onSessionErrorCallback) {
+            const callback = this.onSessionErrorCallback;
+            setImmediate(() => {
+                callback(sessionID, message);
+            });
+        }
+    }
     handleQuestionAsked(event) {
         const { id, sessionID, questions } = event.properties;
         if (sessionID !== this.currentSessionId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grinev/opencode-telegram-bot",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Telegram bot client for OpenCode to run and monitor coding tasks from chat.",
   "type": "module",
   "main": "./dist/index.js",