@grinev/opencode-telegram-bot 0.7.0 → 0.9.0

package/.env.example

@@ -40,7 +40,8 @@ OPENCODE_MODEL_ID=big-pickle
 # Maximum number of projects shown in /projects (default: 10)
 # PROJECTS_LIST_LIMIT=10
 
-# Bot locale: en or ru (default: en)
+# Bot locale: supported locale code (default: en)
+# Supported locales: en, de, es, ru, zh
 # BOT_LOCALE=en
 
 # Service message batching interval in seconds (thinking + tool calls, default: 5)
@@ -54,6 +55,11 @@ 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

package/README.md

@@ -11,6 +11,8 @@ Run AI coding tasks, monitor progress, switch models, and manage sessions from y
 
 No open ports, no exposed APIs. The bot communicates with your local OpenCode server and the Telegram Bot API only.
 
+Languages: English (`en`), Deutsch (`de`), Español (`es`), Русский (`ru`), 简体中文 (`zh`)
+
 Quick start: `npx @grinev/opencode-telegram-bot`
 
 <p align="center">
@@ -28,8 +30,9 @@ Quick start: `npx @grinev/opencode-telegram-bot`
 - **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`)
+- **Localization** — English, German, Spanish, Russian, and Simplified Chinese UI (`BOT_LOCALE=en|de|es|ru|zh`)
 
 ## Prerequisites
 
@@ -65,7 +68,7 @@ The fastest way — run directly with `npx`:
 npx @grinev/opencode-telegram-bot
 ```
 
-On first launch, an interactive wizard will guide you through the configuration — it will ask for your bot token, user ID, and OpenCode API URL. After that, you're ready to go. Open your bot in Telegram and start sending tasks.
+On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, and OpenCode API URL. After that, you're ready to go. Open your bot in Telegram and start sending tasks.
 
 #### Alternative: Global Install
 
@@ -110,6 +113,12 @@ Any regular text message is sent as a prompt to the coding agent only when no bl
 
 ## Configuration
 
+### Localization
+
+- Supported locales: `en`, `de`, `es`, `ru`, `zh`
+- The setup wizard asks for language first
+- You can change locale later with `BOT_LOCALE`
+
 ### Environment Variables
 
 When installed via npm, the configuration wizard handles the initial setup. The `.env` file is stored in your platform's app data directory:
@@ -128,12 +137,13 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `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`                     |
+| `BOT_LOCALE`                    | Bot UI language (supported locale code, e.g. `en`, `de`, `es`, `ru`, `zh`)                                   |    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    | —                        |

package/dist/bot/commands/sessions.js

@@ -10,7 +10,7 @@ import { ensureActiveInlineMenu, replyWithInlineMenu } from "../handlers/inline-
 import { logger } from "../../utils/logger.js";
 import { safeBackgroundTask } from "../../utils/safe-background-task.js";
 import { config } from "../../config.js";
-import { getLocale, t } from "../../i18n/index.js";
+import { getDateLocale, t } from "../../i18n/index.js";
 export async function sessionsCommand(ctx) {
     try {
         const maxSessions = config.bot.sessionsListLimit;
@@ -36,7 +36,7 @@ export async function sessionsCommand(ctx) {
             return;
         }
         const keyboard = new InlineKeyboard();
-        const localeForDate = getLocale() === "ru" ? "ru-RU" : "en-US";
+        const localeForDate = getDateLocale();
         sessions.forEach((session, index) => {
             const date = new Date(session.time.created).toLocaleDateString(localeForDate);
             const label = `${index + 1}. ${session.title} (${date})`;

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

@@ -62,11 +62,15 @@ async function resetMismatchedSessionContext() {
 }
 /**
  * Processes a user prompt: ensures project/session, subscribes to events, and sends
- * the prompt to OpenCode. Used by both text and voice message handlers.
+ * 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) {
+export async function processUserPrompt(ctx, text, deps, fileParts = []) {
     const { bot, ensureEventSubscription } = deps;
     const currentProject = getCurrentProject();
     if (!currentProject) {
@@ -145,10 +149,25 @@ export async function processUserPrompt(ctx, text, deps) {
     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: [{ type: "text", text }],
+            parts,
             agent: currentAgent,
         };
         // Use stored model (from settings or config)
@@ -170,8 +189,9 @@ export async function processUserPrompt(ctx, text, deps) {
             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}...`);
+        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.

package/dist/bot/index.js

@@ -35,7 +35,7 @@ import { clearAllInteractionState } from "../interaction/cleanup.js";
 import { keyboardManager } from "../keyboard/manager.js";
 import { subscribeToEvents } from "../opencode/events.js";
 import { summaryAggregator } from "../summary/aggregator.js";
-import { formatSummary, formatToolInfo } from "../summary/formatter.js";
+import { formatSummary, formatToolInfo, getAssistantParseMode } from "../summary/formatter.js";
 import { ToolMessageBatcher } from "../summary/tool-message-batcher.js";
 import { getCurrentSession } from "../session/manager.js";
 import { ingestSessionInfoForCache } from "../session/cache-manager.js";
@@ -45,6 +45,10 @@ import { pinnedMessageManager } from "../pinned/manager.js";
 import { t } from "../i18n/index.js";
 import { processUserPrompt } from "./handlers/prompt.js";
 import { handleVoiceMessage } from "./handlers/voice.js";
+import { downloadTelegramFile, toDataUri } from "./utils/file-download.js";
+import { sendMessageWithMarkdownFallback } from "./utils/send-with-markdown-fallback.js";
+import { getModelCapabilities, supportsInput } from "../model/capabilities.js";
+import { getStoredModel } from "../model/manager.js";
 let botInstance = null;
 let chatIdInstance = null;
 let commandsInitialized = false;
@@ -145,24 +149,19 @@ async function ensureEventSubscription(directory) {
         await toolMessageBatcher.flushSession(sessionId, "assistant_message_completed");
         try {
             const parts = formatSummary(messageText);
+            const assistantParseMode = getAssistantParseMode();
             logger.debug(`[Bot] Sending completed message to Telegram (chatId=${chatIdInstance}, parts=${parts.length})`);
             for (let i = 0; i < parts.length; i++) {
                 const isLastPart = i === parts.length - 1;
-                if (isLastPart && keyboardManager.isInitialized()) {
-                    // Attach updated keyboard to the last message part (only if initialized)
-                    const keyboard = keyboardManager.getKeyboard();
-                    if (keyboard) {
-                        await botInstance.api.sendMessage(chatIdInstance, parts[i], {
-                            reply_markup: keyboard,
-                        });
-                    }
-                    else {
-                        await botInstance.api.sendMessage(chatIdInstance, parts[i]);
-                    }
-                }
-                else {
-                    await botInstance.api.sendMessage(chatIdInstance, parts[i]);
-                }
+                const keyboard = isLastPart && keyboardManager.isInitialized() ? keyboardManager.getKeyboard() : undefined;
+                const options = keyboard ? { reply_markup: keyboard } : undefined;
+                await sendMessageWithMarkdownFallback({
+                    api: botInstance.api,
+                    chatId: chatIdInstance,
+                    text: parts[i],
+                    options,
+                    parseMode: assistantParseMode,
+                });
             }
         }
         catch (err) {
@@ -584,6 +583,56 @@ export function createBot() {
         chatIdInstance = ctx.chat.id;
         await handleVoiceMessage(ctx, voicePromptDeps);
     });
+    // Photo message handler
+    bot.on("message:photo", async (ctx) => {
+        logger.debug(`[Bot] Received photo message, chatId=${ctx.chat.id}`);
+        const photos = ctx.message?.photo;
+        if (!photos || photos.length === 0) {
+            return;
+        }
+        const caption = ctx.message.caption || "";
+        try {
+            // Get the largest photo (last element in array)
+            const largestPhoto = photos[photos.length - 1];
+            // Check model capabilities
+            const storedModel = getStoredModel();
+            const capabilities = await getModelCapabilities(storedModel.providerID, storedModel.modelID);
+            if (!supportsInput(capabilities, "image")) {
+                logger.warn(`[Bot] Model ${storedModel.providerID}/${storedModel.modelID} doesn't support image input`);
+                await ctx.reply(t("bot.photo_model_no_image"));
+                // Fall back to caption-only if present
+                if (caption.trim().length > 0) {
+                    botInstance = bot;
+                    chatIdInstance = ctx.chat.id;
+                    const promptDeps = { bot, ensureEventSubscription };
+                    await processUserPrompt(ctx, caption, promptDeps);
+                }
+                return;
+            }
+            // Download photo
+            await ctx.reply(t("bot.photo_downloading"));
+            const downloadedFile = await downloadTelegramFile(ctx.api, largestPhoto.file_id);
+            // Convert to data URI (Telegram always converts photos to JPEG)
+            const dataUri = toDataUri(downloadedFile.buffer, "image/jpeg");
+            // Create file part
+            const filePart = {
+                type: "file",
+                mime: "image/jpeg",
+                filename: "photo.jpg",
+                url: dataUri,
+            };
+            logger.info(`[Bot] Sending photo (${downloadedFile.buffer.length} bytes) with prompt`);
+            botInstance = bot;
+            chatIdInstance = ctx.chat.id;
+            // Send via processUserPrompt with file part
+            const promptDeps = { bot, ensureEventSubscription };
+            await processUserPrompt(ctx, caption, promptDeps, [filePart]);
+        }
+        catch (err) {
+            logger.error("[Bot] Error handling photo message:", err);
+            await ctx.reply(t("bot.photo_download_error"));
+        }
+    });
     bot.on("message:text", async (ctx) => {
         const text = ctx.message?.text;
         if (!text) {

package/dist/bot/utils/file-download.js

@@ -0,0 +1,75 @@
+import { config } from "../../config.js";
+import { logger } from "../../utils/logger.js";
+const TELEGRAM_FILE_URL_BASE = "https://api.telegram.org/file/bot";
+const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024; // 20MB Telegram limit
+/**
+ * Download a photo from Telegram servers
+ * @param api Grammy API instance
+ * @param fileId Telegram file_id
+ * @returns Downloaded photo buffer and path
+ */
+export async function downloadTelegramFile(api, fileId) {
+    logger.debug(`[FileDownload] Getting file info for fileId=${fileId}`);
+    const file = await api.getFile(fileId);
+    if (!file.file_path) {
+        throw new Error("File path not available from Telegram");
+    }
+    if (file.file_size && file.file_size > MAX_FILE_SIZE_BYTES) {
+        const sizeMb = (file.file_size / (1024 * 1024)).toFixed(2);
+        throw new Error(`File too large: ${sizeMb}MB (max 20MB)`);
+    }
+    const fileUrl = `${TELEGRAM_FILE_URL_BASE}${config.telegram.token}/${file.file_path}`;
+    logger.debug(`[FileDownload] Downloading from ${fileUrl.replace(config.telegram.token, "***")}`);
+    const fetchOptions = {};
+    // Use proxy if configured
+    if (config.telegram.proxyUrl) {
+        const { HttpsProxyAgent } = await import("https-proxy-agent");
+        fetchOptions.agent = new HttpsProxyAgent(config.telegram.proxyUrl);
+    }
+    const response = await fetch(fileUrl, fetchOptions);
+    if (!response.ok) {
+        throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    logger.debug(`[FileDownload] Downloaded ${buffer.length} bytes`);
+    return {
+        buffer,
+        filePath: file.file_path,
+    };
+}
+/**
+ * Convert buffer to base64 data URI
+ * @param buffer File buffer
+ * @param mimeType MIME type (e.g., "image/jpeg")
+ * @returns Data URI string
+ */
+export function toDataUri(buffer, mimeType) {
+    const base64 = buffer.toString("base64");
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * Check if photo size is within limits
+ * @param fileSize Photo size in bytes
+ * @param maxSizeKb Maximum size in KB (from config)
+ * @returns true if within limit
+ */
+export function isFileSizeAllowed(fileSize, maxSizeKb) {
+    if (!fileSize) {
+        return true; // Unknown size, allow (will be checked on download)
+    }
+    const maxBytes = maxSizeKb * 1024;
+    return fileSize <= maxBytes;
+}
+/**
+ * Get human-readable photo size
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/dist/bot/utils/send-with-markdown-fallback.js

@@ -0,0 +1,58 @@
+import { logger } from "../../utils/logger.js";
+const MARKDOWN_PARSE_ERROR_MARKERS = [
+    "can't parse entities",
+    "can't parse entity",
+    "can't find end of the entity",
+    "entity beginning",
+    "bad request: can't parse",
+];
+function getErrorText(error) {
+    const parts = [];
+    if (error instanceof Error) {
+        parts.push(error.message);
+    }
+    if (typeof error === "object" && error !== null) {
+        const description = Reflect.get(error, "description");
+        if (typeof description === "string") {
+            parts.push(description);
+        }
+        const message = Reflect.get(error, "message");
+        if (typeof message === "string") {
+            parts.push(message);
+        }
+    }
+    if (typeof error === "string") {
+        parts.push(error);
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return parts.join("\n").toLowerCase();
+}
+export function isTelegramMarkdownParseError(error) {
+    const errorText = getErrorText(error);
+    if (!errorText) {
+        return false;
+    }
+    return MARKDOWN_PARSE_ERROR_MARKERS.some((marker) => errorText.includes(marker));
+}
+export async function sendMessageWithMarkdownFallback({ api, chatId, text, options, parseMode, }) {
+    if (!parseMode) {
+        await api.sendMessage(chatId, text, options);
+        return;
+    }
+    const markdownOptions = {
+        ...(options || {}),
+        parse_mode: parseMode,
+    };
+    try {
+        await api.sendMessage(chatId, text, markdownOptions);
+    }
+    catch (error) {
+        if (!isTelegramMarkdownParseError(error)) {
+            throw error;
+        }
+        logger.warn("[Bot] MarkdownV2 parse failed, retrying assistant message in raw mode", error);
+        await api.sendMessage(chatId, text, options);
+    }
+}

package/dist/config.js

@@ -1,5 +1,6 @@
 import dotenv from "dotenv";
 import { getRuntimePaths } from "./runtime/paths.js";
+import { normalizeLocale } from "./i18n/index.js";
 const runtimePaths = getRuntimePaths();
 dotenv.config({ path: runtimePaths.envFilePath });
 function getEnvVar(key, required = true) {
@@ -36,17 +37,7 @@ function getOptionalNonNegativeIntEnvVarFromKeys(keys, defaultValue) {
 }
 function getOptionalLocaleEnvVar(key, defaultValue) {
     const value = getEnvVar(key, false);
-    if (!value) {
-        return defaultValue;
-    }
-    const normalized = value.trim().toLowerCase().split("-")[0];
-    if (normalized === "ru") {
-        return "ru";
-    }
-    if (normalized === "en") {
-        return "en";
-    }
-    return defaultValue;
+    return normalizeLocale(value, defaultValue);
 }
 function getOptionalBooleanEnvVar(key, defaultValue) {
     const value = getEnvVar(key, false);
@@ -62,6 +53,17 @@ function getOptionalBooleanEnvVar(key, defaultValue) {
     }
     return defaultValue;
 }
+function getOptionalMessageFormatModeEnvVar(key, defaultValue) {
+    const value = getEnvVar(key, false);
+    if (!value) {
+        return defaultValue;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "raw" || normalized === "markdown") {
+        return normalized;
+    }
+    return defaultValue;
+}
 export const config = {
     telegram: {
         token: getEnvVar("TELEGRAM_BOT_TOKEN"),
@@ -87,6 +89,7 @@ export const config = {
         serviceMessagesIntervalSec: getOptionalNonNegativeIntEnvVarFromKeys(["SERVICE_MESSAGES_INTERVAL_SEC", "TOOL_MESSAGES_INTERVAL_SEC"], 5),
         hideThinkingMessages: getOptionalBooleanEnvVar("HIDE_THINKING_MESSAGES", false),
         hideToolCallMessages: getOptionalBooleanEnvVar("HIDE_TOOL_CALL_MESSAGES", false),
+        messageFormatMode: getOptionalMessageFormatModeEnvVar("MESSAGE_FORMAT_MODE", "markdown"),
     },
     files: {
         maxFileSizeKb: parseInt(getEnvVar("CODE_FILE_MAX_SIZE_KB", false) || "100", 10),