@grinev/opencode-telegram-bot 0.10.1 → 0.11.0

package/README.md

@@ -26,11 +26,12 @@ Languages: English (`en`), Deutsch (`de`), Español (`es`), Русский (`ru`
 - **Live status** — pinned message with current project, model, context usage, and changed files list, updated in real time
 - **Model switching** — pick models from OpenCode favorites and recent history directly in the chat (favorites are shown first)
 - **Agent modes** — switch between Plan and Build modes on the fly
+- **Custom Commands** — run OpenCode custom commands (and built-ins like `init`/`review`) from an inline menu with confirmation
 - **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
+- **File attachments** — send images, PDF documents, and any text-based files to OpenCode (code, logs, configs etc.)
 - **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** — UI localization is supported for multiple languages (`BOT_LOCALE`)
 
@@ -103,6 +104,7 @@ opencode-telegram config
 | `/sessions`       | Browse and switch between recent sessions               |
 | `/projects`       | Switch between OpenCode projects                        |
 | `/rename`         | Rename the current session                              |
+| `/commands`       | Browse and run custom commands                          |
 | `/opencode_start` | Start the OpenCode server remotely                      |
 | `/opencode_stop`  | Stop the OpenCode server remotely                       |
 | `/help`           | Show available commands                                 |

package/dist/bot/commands/commands.js

@@ -0,0 +1,379 @@
+import { InlineKeyboard } from "grammy";
+import { opencodeClient } from "../../opencode/client.js";
+import { getCurrentProject } from "../../settings/manager.js";
+import { clearSession, getCurrentSession, setCurrentSession, } from "../../session/manager.js";
+import { ingestSessionInfoForCache } from "../../session/cache-manager.js";
+import { interactionManager } from "../../interaction/manager.js";
+import { summaryAggregator } from "../../summary/aggregator.js";
+import { getStoredAgent } from "../../agent/manager.js";
+import { getStoredModel } from "../../model/manager.js";
+import { safeBackgroundTask } from "../../utils/safe-background-task.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+const COMMANDS_CALLBACK_PREFIX = "commands:";
+const COMMANDS_CALLBACK_SELECT_PREFIX = `${COMMANDS_CALLBACK_PREFIX}select:`;
+const COMMANDS_CALLBACK_CANCEL = `${COMMANDS_CALLBACK_PREFIX}cancel`;
+const COMMANDS_CALLBACK_EXECUTE = `${COMMANDS_CALLBACK_PREFIX}execute`;
+const MAX_INLINE_BUTTON_LABEL_LENGTH = 64;
+function formatExecutingCommandMessage(commandName, args) {
+    const commandText = `／${commandName}`;
+    const argsSuffix = args ? ` ${args}` : "";
+    return `${t("commands.executing_prefix")}\n${commandText}${argsSuffix}`;
+}
+function normalizeDirectoryForCommandApi(directory) {
+    return directory.replace(/\\/g, "/");
+}
+function getCallbackMessageId(ctx) {
+    const message = ctx.callbackQuery?.message;
+    if (!message || !("message_id" in message)) {
+        return null;
+    }
+    const messageId = message.message_id;
+    return typeof messageId === "number" ? messageId : null;
+}
+function formatCommandButtonLabel(command) {
+    const description = command.description?.trim() || t("commands.no_description");
+    const rawLabel = `/${command.name} - ${description}`;
+    if (rawLabel.length <= MAX_INLINE_BUTTON_LABEL_LENGTH) {
+        return rawLabel;
+    }
+    return `${rawLabel.slice(0, MAX_INLINE_BUTTON_LABEL_LENGTH - 3)}...`;
+}
+function buildCommandsListKeyboard(commands) {
+    const keyboard = new InlineKeyboard();
+    commands.forEach((command, index) => {
+        keyboard
+            .text(formatCommandButtonLabel(command), `${COMMANDS_CALLBACK_SELECT_PREFIX}${index}`)
+            .row();
+    });
+    keyboard.text(t("commands.button.cancel"), COMMANDS_CALLBACK_CANCEL);
+    return keyboard;
+}
+function buildCommandsConfirmKeyboard() {
+    return new InlineKeyboard()
+        .text(t("commands.button.execute"), COMMANDS_CALLBACK_EXECUTE)
+        .text(t("commands.button.cancel"), COMMANDS_CALLBACK_CANCEL);
+}
+function parseCommandItems(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const commands = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object") {
+            return null;
+        }
+        const commandName = item.name;
+        if (typeof commandName !== "string" || !commandName.trim()) {
+            return null;
+        }
+        const description = item.description;
+        commands.push({
+            name: commandName,
+            description: typeof description === "string" ? description : undefined,
+        });
+    }
+    return commands;
+}
+function parseCommandsMetadata(state) {
+    if (!state || state.kind !== "custom") {
+        return null;
+    }
+    const flow = state.metadata.flow;
+    const stage = state.metadata.stage;
+    const messageId = state.metadata.messageId;
+    const projectDirectory = state.metadata.projectDirectory;
+    if (flow !== "commands" ||
+        typeof messageId !== "number" ||
+        typeof projectDirectory !== "string") {
+        return null;
+    }
+    if (stage === "list") {
+        const commands = parseCommandItems(state.metadata.commands);
+        if (!commands) {
+            return null;
+        }
+        return {
+            flow,
+            stage,
+            messageId,
+            projectDirectory,
+            commands,
+        };
+    }
+    if (stage === "confirm") {
+        const commandName = state.metadata.commandName;
+        if (typeof commandName !== "string" || !commandName.trim()) {
+            return null;
+        }
+        return {
+            flow,
+            stage,
+            messageId,
+            projectDirectory,
+            commandName,
+        };
+    }
+    return null;
+}
+function clearCommandsInteraction(reason) {
+    const metadata = parseCommandsMetadata(interactionManager.getSnapshot());
+    if (metadata) {
+        interactionManager.clear(reason);
+    }
+}
+async function getCommandList(projectDirectory) {
+    const { data, error } = await opencodeClient.command.list({
+        directory: normalizeDirectoryForCommandApi(projectDirectory),
+    });
+    if (error || !data) {
+        throw error || new Error("No command data received");
+    }
+    return data
+        .filter((command) => typeof command.name === "string" && command.name.trim().length > 0)
+        .map((command) => ({
+        name: command.name,
+        description: command.description,
+    }));
+}
+function parseSelectIndex(data) {
+    if (!data.startsWith(COMMANDS_CALLBACK_SELECT_PREFIX)) {
+        return null;
+    }
+    const rawIndex = data.slice(COMMANDS_CALLBACK_SELECT_PREFIX.length);
+    const index = Number(rawIndex);
+    if (!Number.isInteger(index) || index < 0) {
+        return null;
+    }
+    return index;
+}
+async function isSessionBusy(sessionId, directory) {
+    try {
+        const { data, error } = await opencodeClient.session.status({ directory });
+        if (error || !data) {
+            logger.warn("[Commands] Failed to check session status before command:", error);
+            return false;
+        }
+        const sessionStatus = data[sessionId];
+        if (!sessionStatus) {
+            return false;
+        }
+        return sessionStatus.type === "busy";
+    }
+    catch (err) {
+        logger.warn("[Commands] Error checking session status before command:", err);
+        return false;
+    }
+}
+async function ensureSessionForProject(ctx, projectDirectory) {
+    let currentSession = getCurrentSession();
+    if (currentSession && currentSession.directory !== projectDirectory) {
+        logger.warn(`[Commands] Session/project mismatch detected. sessionDirectory=${currentSession.directory}, projectDirectory=${projectDirectory}. Resetting session context.`);
+        clearSession();
+        summaryAggregator.clear();
+        await ctx.reply(t("bot.session_reset_project_mismatch"));
+        currentSession = null;
+    }
+    if (currentSession) {
+        return currentSession;
+    }
+    await ctx.reply(t("bot.creating_session"));
+    const { data: session, error } = await opencodeClient.session.create({
+        directory: projectDirectory,
+    });
+    if (error || !session) {
+        await ctx.reply(t("bot.create_session_error"));
+        return null;
+    }
+    const sessionInfo = {
+        id: session.id,
+        title: session.title,
+        directory: projectDirectory,
+    };
+    setCurrentSession(sessionInfo);
+    await ingestSessionInfoForCache(session);
+    await ctx.reply(t("bot.session_created", { title: session.title }));
+    return sessionInfo;
+}
+async function executeCommand(ctx, deps, params) {
+    if (!ctx.chat) {
+        return;
+    }
+    const args = params.argumentsText.trim();
+    await ctx.reply(formatExecutingCommandMessage(params.commandName, args));
+    const session = await ensureSessionForProject(ctx, params.projectDirectory);
+    if (!session) {
+        return;
+    }
+    await deps.ensureEventSubscription(session.directory);
+    summaryAggregator.setSession(session.id);
+    summaryAggregator.setBotAndChatId(deps.bot, ctx.chat.id);
+    const sessionIsBusy = await isSessionBusy(session.id, session.directory);
+    if (sessionIsBusy) {
+        await ctx.reply(t("bot.session_busy"));
+        return;
+    }
+    const currentAgent = getStoredAgent();
+    const storedModel = getStoredModel();
+    const model = storedModel.providerID && storedModel.modelID
+        ? `${storedModel.providerID}/${storedModel.modelID}`
+        : undefined;
+    safeBackgroundTask({
+        taskName: "session.command",
+        task: () => opencodeClient.session.command({
+            sessionID: session.id,
+            directory: session.directory,
+            command: params.commandName,
+            arguments: args,
+            agent: currentAgent,
+            model,
+            variant: storedModel.variant,
+        }),
+        onSuccess: ({ error }) => {
+            if (error) {
+                logger.error("[Commands] OpenCode API returned an error for session.command", {
+                    sessionId: session.id,
+                    command: params.commandName,
+                    args,
+                });
+                logger.error("[Commands] session.command error details:", error);
+                void ctx.api.sendMessage(ctx.chat.id, t("commands.execute_error")).catch(() => { });
+                return;
+            }
+            logger.info(`[Commands] session.command completed: session=${session.id}, command=/${params.commandName}`);
+        },
+        onError: (error) => {
+            logger.error("[Commands] session.command background task failed", {
+                sessionId: session.id,
+                command: params.commandName,
+                args,
+            });
+            logger.error("[Commands] session.command background failure details:", error);
+            void ctx.api.sendMessage(ctx.chat.id, t("commands.execute_error")).catch(() => { });
+        },
+    });
+}
+export async function commandsCommand(ctx) {
+    try {
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            await ctx.reply(t("bot.project_not_selected"));
+            return;
+        }
+        const commands = await getCommandList(currentProject.worktree);
+        if (commands.length === 0) {
+            await ctx.reply(t("commands.empty"));
+            return;
+        }
+        const keyboard = buildCommandsListKeyboard(commands);
+        const message = await ctx.reply(t("commands.select"), {
+            reply_markup: keyboard,
+        });
+        interactionManager.start({
+            kind: "custom",
+            expectedInput: "callback",
+            metadata: {
+                flow: "commands",
+                stage: "list",
+                messageId: message.message_id,
+                projectDirectory: currentProject.worktree,
+                commands,
+            },
+        });
+    }
+    catch (error) {
+        logger.error("[Commands] Error fetching commands list:", error);
+        await ctx.reply(t("commands.fetch_error"));
+    }
+}
+export async function handleCommandsCallback(ctx, deps) {
+    const data = ctx.callbackQuery?.data;
+    if (!data || !data.startsWith(COMMANDS_CALLBACK_PREFIX)) {
+        return false;
+    }
+    const metadata = parseCommandsMetadata(interactionManager.getSnapshot());
+    const callbackMessageId = getCallbackMessageId(ctx);
+    if (!metadata || callbackMessageId === null || metadata.messageId !== callbackMessageId) {
+        await ctx.answerCallbackQuery({ text: t("commands.inactive_callback"), show_alert: true });
+        return true;
+    }
+    try {
+        if (data === COMMANDS_CALLBACK_CANCEL) {
+            clearCommandsInteraction("commands_cancelled");
+            await ctx.answerCallbackQuery({ text: t("commands.cancelled_callback") });
+            await ctx.deleteMessage().catch(() => { });
+            return true;
+        }
+        if (data === COMMANDS_CALLBACK_EXECUTE) {
+            if (metadata.stage !== "confirm") {
+                await ctx.answerCallbackQuery({ text: t("commands.inactive_callback"), show_alert: true });
+                return true;
+            }
+            clearCommandsInteraction("commands_execute_clicked");
+            await ctx.answerCallbackQuery({ text: t("commands.execute_callback") });
+            await ctx.deleteMessage().catch(() => { });
+            await executeCommand(ctx, deps, {
+                projectDirectory: metadata.projectDirectory,
+                commandName: metadata.commandName,
+                argumentsText: "",
+            });
+            return true;
+        }
+        const commandIndex = parseSelectIndex(data);
+        if (commandIndex === null || metadata.stage !== "list") {
+            await ctx.answerCallbackQuery({ text: t("callback.processing_error"), show_alert: true });
+            return true;
+        }
+        const selectedCommand = metadata.commands[commandIndex];
+        if (!selectedCommand) {
+            await ctx.answerCallbackQuery({ text: t("commands.inactive_callback"), show_alert: true });
+            return true;
+        }
+        await ctx.answerCallbackQuery();
+        await ctx.editMessageText(t("commands.confirm", { command: `/${selectedCommand.name}` }), {
+            reply_markup: buildCommandsConfirmKeyboard(),
+        });
+        interactionManager.transition({
+            expectedInput: "mixed",
+            metadata: {
+                flow: "commands",
+                stage: "confirm",
+                messageId: metadata.messageId,
+                projectDirectory: metadata.projectDirectory,
+                commandName: selectedCommand.name,
+            },
+        });
+        return true;
+    }
+    catch (error) {
+        logger.error("[Commands] Error handling command callback:", error);
+        clearCommandsInteraction("commands_callback_error");
+        await ctx.answerCallbackQuery({ text: t("callback.processing_error") }).catch(() => { });
+        return true;
+    }
+}
+export async function handleCommandTextArguments(ctx, deps) {
+    const text = ctx.message?.text;
+    if (!text || text.startsWith("/")) {
+        return false;
+    }
+    const metadata = parseCommandsMetadata(interactionManager.getSnapshot());
+    if (!metadata || metadata.stage !== "confirm") {
+        return false;
+    }
+    const argumentsText = text.trim();
+    if (!argumentsText) {
+        await ctx.reply(t("commands.arguments_empty"));
+        return true;
+    }
+    clearCommandsInteraction("commands_arguments_submitted");
+    if (ctx.chat) {
+        await ctx.api.deleteMessage(ctx.chat.id, metadata.messageId).catch(() => { });
+    }
+    await executeCommand(ctx, deps, {
+        projectDirectory: metadata.projectDirectory,
+        commandName: metadata.commandName,
+        argumentsText,
+    });
+    return true;
+}

package/dist/bot/commands/definitions.js

@@ -10,6 +10,7 @@ const COMMAND_DEFINITIONS = [
     { command: "sessions", descriptionKey: "cmd.description.sessions" },
     { command: "projects", descriptionKey: "cmd.description.projects" },
     { command: "rename", descriptionKey: "cmd.description.rename" },
+    { command: "commands", descriptionKey: "cmd.description.commands" },
     { command: "opencode_start", descriptionKey: "cmd.description.opencode_start" },
     { command: "opencode_stop", descriptionKey: "cmd.description.opencode_stop" },
     { command: "help", descriptionKey: "cmd.description.help" },

package/dist/bot/handlers/document.js

@@ -0,0 +1,65 @@
+import { config } from "../../config.js";
+import { processUserPrompt } from "./prompt.js";
+import { downloadTelegramFile, toDataUri, isTextMimeType, isFileSizeAllowed, } from "../utils/file-download.js";
+import { getModelCapabilities, supportsInput } from "../../model/capabilities.js";
+import { getStoredModel } from "../../model/manager.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+export async function handleDocumentMessage(ctx, deps) {
+    const downloadFile = deps.downloadFile ?? downloadTelegramFile;
+    const getCapabilities = deps.getModelCapabilities ?? getModelCapabilities;
+    const getStored = deps.getStoredModel ?? getStoredModel;
+    const processPrompt = deps.processPrompt ?? processUserPrompt;
+    const doc = ctx.message?.document;
+    if (!doc) {
+        return;
+    }
+    const caption = ctx.message.caption || "";
+    const mimeType = doc.mime_type || "";
+    const filename = doc.file_name || "document";
+    try {
+        if (isTextMimeType(mimeType)) {
+            if (!isFileSizeAllowed(doc.file_size, config.files.maxFileSizeKb)) {
+                logger.warn(`[Document] Text file too large: ${filename} (${doc.file_size} bytes > ${config.files.maxFileSizeKb}KB)`);
+                await ctx.reply(t("bot.text_file_too_large", { maxSizeKb: String(config.files.maxFileSizeKb) }));
+                return;
+            }
+            await ctx.reply(t("bot.file_downloading"));
+            const downloadedFile = await downloadFile(ctx.api, doc.file_id);
+            const textContent = downloadedFile.buffer.toString("utf-8");
+            const promptWithFile = `--- Content of ${filename} ---\n${textContent}\n--- End of file ---\n\n${caption}`;
+            logger.info(`[Document] Sending text file (${downloadedFile.buffer.length} bytes, ${filename}) as prompt`);
+            await processPrompt(ctx, promptWithFile, deps);
+            return;
+        }
+        if (mimeType === "application/pdf") {
+            const storedModel = getStored();
+            const capabilities = await getCapabilities(storedModel.providerID, storedModel.modelID);
+            if (!supportsInput(capabilities, "pdf")) {
+                logger.warn(`[Document] Model ${storedModel.providerID}/${storedModel.modelID} doesn't support PDF input`);
+                await ctx.reply(t("bot.model_no_pdf"));
+                if (caption.trim().length > 0) {
+                    await processPrompt(ctx, caption, deps);
+                }
+                return;
+            }
+            await ctx.reply(t("bot.file_downloading"));
+            const downloadedFile = await downloadFile(ctx.api, doc.file_id);
+            const dataUri = toDataUri(downloadedFile.buffer, mimeType);
+            const filePart = {
+                type: "file",
+                mime: mimeType,
+                filename: filename,
+                url: dataUri,
+            };
+            logger.info(`[Document] Sending PDF (${downloadedFile.buffer.length} bytes, ${filename}) with prompt`);
+            await processPrompt(ctx, caption, deps, [filePart]);
+            return;
+        }
+        logger.debug(`[Document] Unsupported document MIME type: ${mimeType}, ignoring`);
+    }
+    catch (err) {
+        logger.error("[Document] Error handling document message:", err);
+        await ctx.reply(t("bot.file_download_error"));
+    }
+}

package/dist/bot/index.js

@@ -12,7 +12,7 @@ import { BOT_COMMANDS } from "./commands/definitions.js";
 import { startCommand } from "./commands/start.js";
 import { helpCommand } from "./commands/help.js";
 import { statusCommand } from "./commands/status.js";
-import { MODEL_BUTTON_TEXT_PATTERN, VARIANT_BUTTON_TEXT_PATTERN } from "./message-patterns.js";
+import { AGENT_MODE_BUTTON_TEXT_PATTERN, MODEL_BUTTON_TEXT_PATTERN, VARIANT_BUTTON_TEXT_PATTERN, } from "./message-patterns.js";
 import { sessionsCommand, handleSessionSelect } from "./commands/sessions.js";
 import { newCommand } from "./commands/new.js";
 import { projectsCommand, handleProjectSelect } from "./commands/projects.js";
@@ -20,6 +20,7 @@ import { stopCommand } from "./commands/stop.js";
 import { opencodeStartCommand } from "./commands/opencode-start.js";
 import { opencodeStopCommand } from "./commands/opencode-stop.js";
 import { renameCommand, handleRenameCancel, handleRenameTextAnswer } from "./commands/rename.js";
+import { commandsCommand, handleCommandsCallback, handleCommandTextArguments, } from "./commands/commands.js";
 import { handleQuestionCallback, showCurrentQuestion, handleQuestionTextAnswer, } from "./handlers/question.js";
 import { handlePermissionCallback, showPermissionRequest } from "./handlers/permission.js";
 import { handleAgentSelect, showAgentSelectionMenu } from "./handlers/agent.js";
@@ -43,6 +44,7 @@ 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 { handleDocumentMessage } from "./handlers/document.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";
@@ -456,10 +458,15 @@ export function createBot() {
     bot.command("new", newCommand);
     bot.command("stop", stopCommand);
     bot.command("rename", renameCommand);
+    bot.command("commands", commandsCommand);
     bot.on("message:text", unknownCommandMiddleware);
     bot.on("callback_query:data", async (ctx) => {
         logger.debug(`[Bot] Received callback_query:data: ${ctx.callbackQuery?.data}`);
         logger.debug(`[Bot] Callback context: from=${ctx.from?.id}, chat=${ctx.chat?.id}`);
+        if (ctx.chat) {
+            botInstance = bot;
+            chatIdInstance = ctx.chat.id;
+        }
         try {
             const handledInlineCancel = await handleInlineMenuCancel(ctx);
             const handledSession = await handleSessionSelect(ctx);
@@ -471,7 +478,8 @@ export function createBot() {
             const handledVariant = await handleVariantSelect(ctx);
             const handledCompactConfirm = await handleCompactConfirm(ctx);
             const handledRenameCancel = await handleRenameCancel(ctx);
-            logger.debug(`[Bot] Callback handled: inlineCancel=${handledInlineCancel}, session=${handledSession}, project=${handledProject}, question=${handledQuestion}, permission=${handledPermission}, agent=${handledAgent}, model=${handledModel}, variant=${handledVariant}, compactConfirm=${handledCompactConfirm}, rename=${handledRenameCancel}`);
+            const handledCommands = await handleCommandsCallback(ctx, { bot, ensureEventSubscription });
+            logger.debug(`[Bot] Callback handled: inlineCancel=${handledInlineCancel}, session=${handledSession}, project=${handledProject}, question=${handledQuestion}, permission=${handledPermission}, agent=${handledAgent}, model=${handledModel}, variant=${handledVariant}, compactConfirm=${handledCompactConfirm}, rename=${handledRenameCancel}, commands=${handledCommands}`);
             if (!handledInlineCancel &&
                 !handledSession &&
                 !handledProject &&
@@ -481,7 +489,8 @@ export function createBot() {
                 !handledModel &&
                 !handledVariant &&
                 !handledCompactConfirm &&
-                !handledRenameCancel) {
+                !handledRenameCancel &&
+                !handledCommands) {
                 logger.debug("Unknown callback query:", ctx.callbackQuery?.data);
                 await ctx.answerCallbackQuery({ text: t("callback.unknown_command") });
             }
@@ -493,7 +502,7 @@ export function createBot() {
         }
     });
     // Handle Reply Keyboard button press (agent mode indicator)
-    bot.hears(/^(📋|🛠️|💬|🔍|📝|📄|📦|🤖) \w+ Mode$/, async (ctx) => {
+    bot.hears(AGENT_MODE_BUTTON_TEXT_PATTERN, async (ctx) => {
         logger.debug(`[Bot] Agent mode button pressed: ${ctx.message?.text}`);
         try {
             if (await blockMenuWhileInteractionActive(ctx)) {
@@ -645,11 +654,21 @@ export function createBot() {
             await ctx.reply(t("bot.photo_download_error"));
         }
     });
+    // Document message handler (PDF and text files)
+    bot.on("message:document", async (ctx) => {
+        logger.debug(`[Bot] Received document message, chatId=${ctx.chat.id}`);
+        botInstance = bot;
+        chatIdInstance = ctx.chat.id;
+        const deps = { bot, ensureEventSubscription };
+        await handleDocumentMessage(ctx, deps);
+    });
     bot.on("message:text", async (ctx) => {
         const text = ctx.message?.text;
         if (!text) {
             return;
         }
+        botInstance = bot;
+        chatIdInstance = ctx.chat.id;
         if (text.startsWith("/")) {
             return;
         }
@@ -661,9 +680,11 @@ export function createBot() {
         if (handledRename) {
             return;
         }
-        botInstance = bot;
-        chatIdInstance = ctx.chat.id;
         const promptDeps = { bot, ensureEventSubscription };
+        const handledCommandArgs = await handleCommandTextArguments(ctx, promptDeps);
+        if (handledCommandArgs) {
+            return;
+        }
         await processUserPrompt(ctx, text, promptDeps);
         logger.debug("[Bot] message:text handler completed (prompt sent in background)");
     });

package/dist/bot/message-patterns.js

@@ -1,3 +1,4 @@
-export const MODEL_BUTTON_TEXT_PATTERN = /^🤖\s[\s\S]+$/;
+export const AGENT_MODE_BUTTON_TEXT_PATTERN = /^(📋|🛠️|💬|🔍|📝|📄|📦|🤖)\s.+\sMode$/;
+export const MODEL_BUTTON_TEXT_PATTERN = /^🤖\s(?!.*\sMode$)[\s\S]+$/;
 // Keep support for both legacy "💭" and current "💡" prefix.
 export const VARIANT_BUTTON_TEXT_PATTERN = /^(💡|💭)\s.+$/;

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

@@ -73,3 +73,19 @@ export function formatFileSize(bytes) {
     }
     return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
+const APPLICATION_TEXT_MIME_TYPES = new Set([
+    "application/json",
+    "application/xml",
+    "application/javascript",
+    "application/x-yaml",
+    "application/sql",
+]);
+export function isTextMimeType(mimeType) {
+    if (!mimeType) {
+        return false;
+    }
+    if (mimeType.startsWith("text/")) {
+        return true;
+    }
+    return APPLICATION_TEXT_MIME_TYPES.has(mimeType);
+}

package/dist/i18n/de.js

@@ -4,6 +4,7 @@ export const de = {
     "cmd.description.stop": "Aktuelle Aktion stoppen",
     "cmd.description.sessions": "Sitzungen auflisten",
     "cmd.description.projects": "Projekte auflisten",
+    "cmd.description.commands": "Benutzerdefinierte Befehle",
     "cmd.description.opencode_start": "OpenCode-Server starten",
     "cmd.description.opencode_stop": "OpenCode-Server stoppen",
     "cmd.description.help": "Hilfe",
@@ -48,6 +49,11 @@ export const de = {
     "bot.photo_model_no_image": "⚠️ Das aktuelle Modell unterstützt keine Bildeingabe. Sende nur Text.",
     "bot.photo_download_error": "🔴 Foto konnte nicht heruntergeladen werden",
     "bot.photo_no_caption": "💡 Tipp: Füge eine Bildunterschrift hinzu, um zu beschreiben, was du mit diesem Foto tun möchtest.",
+    "bot.file_downloading": "⏳ Lade Datei herunter...",
+    "bot.file_too_large": "⚠️ Datei ist zu groß (max. {maxSizeMb}MB)",
+    "bot.file_download_error": "🔴 Datei konnte nicht heruntergeladen werden",
+    "bot.model_no_pdf": "⚠️ Das aktuelle Modell unterstützt keine PDF-Eingabe. Sende nur Text.",
+    "bot.text_file_too_large": "⚠️ Textdatei ist zu groß (max. {maxSizeKb}KB)",
     "status.header_running": "🟢 **OpenCode-Server läuft**",
     "status.health.healthy": "OK",
     "status.health.unhealthy": "Nicht OK",
@@ -238,6 +244,19 @@ export const de = {
     "rename.blocked.expected_name": "⚠️ Sende den neuen Sitzungsnamen als Text oder tippe in der Umbenennen-Nachricht auf Abbrechen.",
     "rename.blocked.command_not_allowed": "⚠️ Dieser Befehl ist nicht verfügbar, solange beim Umbenennen auf einen neuen Namen gewartet wird.",
     "rename.button.cancel": "❌ Abbrechen",
+    "commands.select": "Wähle einen OpenCode-Befehl:",
+    "commands.empty": "📭 Für dieses Projekt sind keine OpenCode-Befehle verfügbar.",
+    "commands.fetch_error": "🔴 OpenCode-Befehle konnten nicht geladen werden.",
+    "commands.no_description": "Keine Beschreibung",
+    "commands.button.execute": "✅ Ausführen",
+    "commands.button.cancel": "❌ Abbrechen",
+    "commands.confirm": "Bestätige die Ausführung des Befehls {command}. Für die Ausführung mit Argumenten sende die Argumente als Nachricht.",
+    "commands.inactive_callback": "Dieses Befehlsmenü ist inaktiv",
+    "commands.cancelled_callback": "Abgebrochen",
+    "commands.execute_callback": "Befehl wird ausgeführt...",
+    "commands.executing_prefix": "⚡ Befehl wird ausgeführt:",
+    "commands.arguments_empty": "⚠️ Argumente dürfen nicht leer sein. Sende Text oder tippe auf Ausführen.",
+    "commands.execute_error": "🔴 OpenCode-Befehl konnte nicht ausgeführt werden.",
     "cmd.description.rename": "Aktuelle Sitzung umbenennen",
     "cli.usage": "Verwendung:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nHinweise:\n  - Ohne Befehl wird standardmäßig `start` verwendet\n  - `--mode` wird derzeit nur für `start` unterstützt",
     "cli.placeholder.status": "Befehl `status` ist derzeit ein Platzhalter. Echte Statusprüfungen werden in der Service-Schicht hinzugefügt (Phase 5).",

package/dist/i18n/en.js

@@ -4,6 +4,7 @@ export const en = {
     "cmd.description.stop": "Stop current action",
     "cmd.description.sessions": "List sessions",
     "cmd.description.projects": "List projects",
+    "cmd.description.commands": "Custom commands",
     "cmd.description.opencode_start": "Start OpenCode server",
     "cmd.description.opencode_stop": "Stop OpenCode server",
     "cmd.description.help": "Help",
@@ -48,6 +49,11 @@ export const en = {
     "bot.photo_model_no_image": "⚠️ Current model doesn't support image input. Sending text only.",
     "bot.photo_download_error": "🔴 Failed to download photo",
     "bot.photo_no_caption": "💡 Tip: Add a caption to describe what you want to do with this photo.",
+    "bot.file_downloading": "⏳ Downloading file...",
+    "bot.file_too_large": "⚠️ File is too large (max {maxSizeMb}MB)",
+    "bot.file_download_error": "🔴 Failed to download file",
+    "bot.model_no_pdf": "⚠️ Current model doesn't support PDF input. Sending text only.",
+    "bot.text_file_too_large": "⚠️ Text file is too large (max {maxSizeKb}KB)",
     "status.header_running": "🟢 **OpenCode Server is running**",
     "status.health.healthy": "Healthy",
     "status.health.unhealthy": "Unhealthy",
@@ -238,6 +244,19 @@ export const en = {
     "rename.blocked.expected_name": "⚠️ Enter a new session name as text or tap Cancel in rename message.",
     "rename.blocked.command_not_allowed": "⚠️ This command is not available while rename is waiting for a new name.",
     "rename.button.cancel": "❌ Cancel",
+    "commands.select": "Choose an OpenCode command:",
+    "commands.empty": "📭 No OpenCode commands are available for this project.",
+    "commands.fetch_error": "🔴 Failed to load OpenCode commands.",
+    "commands.no_description": "No description",
+    "commands.button.execute": "✅ Execute",
+    "commands.button.cancel": "❌ Cancel",
+    "commands.confirm": "Confirm execution of command {command}. To run it with arguments, send the arguments as a message.",
+    "commands.inactive_callback": "This command menu is inactive",
+    "commands.cancelled_callback": "Cancelled",
+    "commands.execute_callback": "Executing command...",
+    "commands.executing_prefix": "⚡ Executing command:",
+    "commands.arguments_empty": "⚠️ Arguments cannot be empty. Send text or tap Execute.",
+    "commands.execute_error": "🔴 Failed to execute OpenCode command.",
     "cmd.description.rename": "Rename current session",
     "cli.usage": "Usage:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nNotes:\n  - No command defaults to `start`\n  - `--mode` is currently supported for `start` only",
     "cli.placeholder.status": "Command `status` is currently a placeholder. Real status checks will be added in service layer (Phase 5).",

package/dist/i18n/es.js

@@ -4,6 +4,7 @@ export const es = {
     "cmd.description.stop": "Detener la acción actual",
     "cmd.description.sessions": "Listar sesiones",
     "cmd.description.projects": "Listar proyectos",
+    "cmd.description.commands": "Comandos personalizados",
     "cmd.description.opencode_start": "Iniciar servidor OpenCode",
     "cmd.description.opencode_stop": "Detener servidor OpenCode",
     "cmd.description.help": "Ayuda",
@@ -48,6 +49,11 @@ export const es = {
     "bot.photo_model_no_image": "⚠️ El modelo actual no admite entrada de imagen. Enviaré solo texto.",
     "bot.photo_download_error": "🔴 No se pudo descargar la foto",
     "bot.photo_no_caption": "💡 Consejo: agrega un pie de foto para describir que quieres hacer con esta foto.",
+    "bot.file_downloading": "⏳ Descargando archivo...",
+    "bot.file_too_large": "⚠️ El archivo es demasiado grande (max {maxSizeMb}MB)",
+    "bot.file_download_error": "🔴 No se pudo descargar el archivo",
+    "bot.model_no_pdf": "⚠️ El modelo actual no admite entrada PDF. Enviaré solo texto.",
+    "bot.text_file_too_large": "⚠️ El archivo de texto es demasiado grande (max {maxSizeKb}KB)",
     "status.header_running": "🟢 **OpenCode Server está en ejecución**",
     "status.health.healthy": "Saludable",
     "status.health.unhealthy": "No saludable",
@@ -238,6 +244,19 @@ export const es = {
     "rename.blocked.expected_name": "⚠️ Introduce el nuevo nombre de la sesión como texto o toca Cancelar en el mensaje de cambio de nombre.",
     "rename.blocked.command_not_allowed": "⚠️ Este comando no está disponible mientras el cambio de nombre espera un nuevo nombre.",
     "rename.button.cancel": "❌ Cancelar",
+    "commands.select": "Elige un comando de OpenCode:",
+    "commands.empty": "📭 No hay comandos de OpenCode disponibles para este proyecto.",
+    "commands.fetch_error": "🔴 No se pudieron cargar los comandos de OpenCode.",
+    "commands.no_description": "Sin descripción",
+    "commands.button.execute": "✅ Ejecutar",
+    "commands.button.cancel": "❌ Cancelar",
+    "commands.confirm": "Confirma la ejecución del comando {command}. Para ejecutarlo con argumentos, envía los argumentos como mensaje.",
+    "commands.inactive_callback": "Este menú de comandos está inactivo",
+    "commands.cancelled_callback": "Cancelado",
+    "commands.execute_callback": "Ejecutando comando...",
+    "commands.executing_prefix": "⚡ Ejecutando comando:",
+    "commands.arguments_empty": "⚠️ Los argumentos no pueden estar vacíos. Envía texto o toca Ejecutar.",
+    "commands.execute_error": "🔴 No se pudo ejecutar el comando de OpenCode.",
     "cmd.description.rename": "Renombrar la sesión actual",
     "cli.usage": "Uso:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nNotas:\n  - Sin comando, el valor por defecto es `start`\n  - `--mode` actualmente solo se admite para `start`",
     "cli.placeholder.status": "El comando `status` es actualmente un marcador de posición. Las comprobaciones reales de estado se agregarán en la capa de servicio (Fase 5).",

package/dist/i18n/ru.js

@@ -4,6 +4,7 @@ export const ru = {
     "cmd.description.stop": "Прервать текущее действие",
     "cmd.description.sessions": "Список сессий",
     "cmd.description.projects": "Список проектов",
+    "cmd.description.commands": "Пользовательские команды",
     "cmd.description.opencode_start": "Запустить OpenCode сервер",
     "cmd.description.opencode_stop": "Остановить OpenCode сервер",
     "cmd.description.help": "Справка",
@@ -48,6 +49,11 @@ export const ru = {
     "bot.photo_model_no_image": "⚠️ Текущая модель не поддерживает изображения. Отправляю только текст.",
     "bot.photo_download_error": "🔴 Не удалось скачать фото",
     "bot.photo_no_caption": "💡 Совет: Добавьте подпись, чтобы описать, что делать с этим фото.",
+    "bot.file_downloading": "⏳ Скачиваю файл...",
+    "bot.file_too_large": "⚠️ Файл слишком большой (макс. {maxSizeMb}МБ)",
+    "bot.file_download_error": "🔴 Не удалось скачать файл",
+    "bot.model_no_pdf": "⚠️ Текущая модель не поддерживает PDF. Отправляю только текст.",
+    "bot.text_file_too_large": "⚠️ Текстовый файл слишком большой (макс. {maxSizeKb}КБ)",
     "status.header_running": "🟢 **OpenCode Server запущен**",
     "status.health.healthy": "Healthy",
     "status.health.unhealthy": "Unhealthy",
@@ -238,6 +244,19 @@ export const ru = {
     "rename.blocked.expected_name": "⚠️ Введите новое название текстом или нажмите Отмена в сообщении переименования.",
     "rename.blocked.command_not_allowed": "⚠️ Эта команда недоступна, пока ожидается новое название сессии.",
     "rename.button.cancel": "❌ Отмена",
+    "commands.select": "Выберите команду OpenCode:",
+    "commands.empty": "📭 Для этого проекта нет доступных команд OpenCode.",
+    "commands.fetch_error": "🔴 Не удалось загрузить список команд OpenCode.",
+    "commands.no_description": "Без описания",
+    "commands.button.execute": "✅ Выполнить",
+    "commands.button.cancel": "❌ Отмена",
+    "commands.confirm": "Подтвердите выполнение команды {command}. Для выполнения с аргументами отправьте аргументы отдельным сообщением.",
+    "commands.inactive_callback": "Это меню команд уже неактивно",
+    "commands.cancelled_callback": "Отменено",
+    "commands.execute_callback": "Запускаю команду...",
+    "commands.executing_prefix": "⚡ Выполнение команды:",
+    "commands.arguments_empty": "⚠️ Аргументы не могут быть пустыми. Отправьте текст или нажмите Выполнить.",
+    "commands.execute_error": "🔴 Не удалось выполнить команду OpenCode.",
     "cmd.description.rename": "Переименовать текущую сессию",
     "cli.usage": "Использование:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nЗаметки:\n  - Без команды по умолчанию используется `start`\n  - `--mode` сейчас поддерживается только для `start`",
     "cli.placeholder.status": "Команда `status` пока работает как заглушка. Реальная проверка статуса появится на этапе service-слоя (Этап 5).",

package/dist/i18n/zh.js

@@ -4,6 +4,7 @@ export const zh = {
     "cmd.description.stop": "停止当前操作",
     "cmd.description.sessions": "列出会话",
     "cmd.description.projects": "列出项目",
+    "cmd.description.commands": "自定义命令",
     "cmd.description.opencode_start": "启动 OpenCode 服务器",
     "cmd.description.opencode_stop": "停止 OpenCode 服务器",
     "cmd.description.help": "帮助",
@@ -48,6 +49,11 @@ export const zh = {
     "bot.photo_model_no_image": "⚠️ 当前模型不支持图像输入。将仅发送文本。",
     "bot.photo_download_error": "🔴 下载照片失败",
     "bot.photo_no_caption": "💡 提示：添加说明文字以描述你希望对这张照片做什么。",
+    "bot.file_downloading": "⏳ 正在下载文件...",
+    "bot.file_too_large": "⚠️ 文件过大（最大 {maxSizeMb}MB）",
+    "bot.file_download_error": "🔴 下载文件失败",
+    "bot.model_no_pdf": "⚠️ 当前模型不支持PDF输入。将仅发送文本。",
+    "bot.text_file_too_large": "⚠️ 文本文件过大（最大 {maxSizeKb}KB）",
     "status.header_running": "🟢 **OpenCode 服务器正在运行**",
     "status.health.healthy": "健康",
     "status.health.unhealthy": "不健康",
@@ -238,6 +244,19 @@ export const zh = {
     "rename.blocked.expected_name": "⚠️ 请以文本输入新会话名称，或在重命名消息中点击取消。",
     "rename.blocked.command_not_allowed": "⚠️ 重命名等待新名称期间不可用此命令。",
     "rename.button.cancel": "❌ 取消",
+    "commands.select": "请选择一个 OpenCode 命令：",
+    "commands.empty": "📭 当前项目没有可用的 OpenCode 命令。",
+    "commands.fetch_error": "🔴 加载 OpenCode 命令失败。",
+    "commands.no_description": "无描述",
+    "commands.button.execute": "✅ 执行",
+    "commands.button.cancel": "❌ 取消",
+    "commands.confirm": "请确认执行命令 {command}。若需带参数执行，请发送一条包含参数的消息。",
+    "commands.inactive_callback": "该命令菜单已失效",
+    "commands.cancelled_callback": "已取消",
+    "commands.execute_callback": "正在执行命令...",
+    "commands.executing_prefix": "⚡ 执行命令:",
+    "commands.arguments_empty": "⚠️ 参数不能为空。请发送文本或点击执行。",
+    "commands.execute_error": "🔴 执行 OpenCode 命令失败。",
     "cmd.description.rename": "重命名当前会话",
     "cli.usage": "用法：\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\n说明：\n  - 不带命令时默认执行 `start`\n  - `--mode` 目前仅支持 `start` 命令",
     "cli.placeholder.status": "命令 `status` 目前是占位符。真实状态检查将会在 service 层（阶段 5）添加。",

package/package.json

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